Create credit note
/documents/credit_notesCosts 2 rate-limit points · Rate limits
Raises a credit note for an invoice, as the order page does: a copy of the invoice with the next credit note number that credits the full invoice, then renders its PDF and returns it in full. If the invoice already has a credit note, that one is returned with already_existed: true. Partial credits are not supported; edit the credit note lines in the dashboard editor.
Creates a new numbered document and renders a PDF (counts against a free plan invoice limit). With send_email: true it also emails the credit note to the customer immediately.
Also searched ascreate credit notecredit this invoiceissue credit noterefund invoice as credit noteraise credit note for invoicenew credit notecancel invoice with credit note
Request body
invoice_idintegerRequiredThe invoice to credit (its id from GET /documents/invoices).
send_emailbooleantrue emails the credit note to the customer right after creating it (default false).
generate_pdfbooleanfalse skips rendering the PDF (default true).
template_idintegerTemplate to render with. Default: the shop default credit note template.
Returns
idintegerExample:980190966document_typestringExample:credit_noteinvoice_numberstringExample:1titlestringExample:Credit Noteorderobject, nullablecustomerobjectShow 8 child attributesHide child attributes
idintegerExample:4namestringExample:Customer 1emailstringExample:cus1@gmail.comshopify_customer_idstringExample:gid://shopify/Customer/23935678808145phonestring, nullabletax_numberstring, nullableeori_numberstring, nullabletagsarray of anys
financial_statusstringExample:paidcurrencystringExample:USDtotalstringExample:1100.22issued_onstringExample:2026-11-10due_onstring, nullablesent_atstring, nullableprinted_atstring, nullablereminder_sent_atstring, nullablepaidbooleanExample:trueeditedbooleanExample:falsetrashedbooleanExample:falsee_invoice_statusstring, nullablecreated_atstringExample:2026-11-10T08:35:17ZcreditedobjectShow 3 child attributesHide child attributes
invoice_numberstringExample:#1001invoice_idintegerExample:980190965shopify_order_idstringExample:gid://shopify/Order/12213474623569
fulfillment_statusstring, nullabledatesobjectShow 5 child attributesHide child attributes
order_placed_atstringExample:2026-11-10T00:00:00Zissued_onstringExample:2026-11-10due_onstring, nullabletax_datestring, nullablefulfilled_onstring, nullable
po_numberstring, nullablepayment_termsstring, nullablepayment_gatewaystringExample:manuallocalestringExample:entotalsobjectShow 11 child attributesHide child attributes
currencystringExample:USDtaxes_includedbooleanExample:falsesubtotalstringExample:1497.95discountsstringExample:494.32shippingstringExample:6.90taxstringExample:89.69dutiesstringExample:0.00totalstringExample:1100.22total_paidstringExample:0.00total_refundedstringExample:0.00total_duestringExample:0.00
billing_addressobjectShow 14 child attributesHide child attributes
namestringExample:Customer 1first_namestringExample:Customerlast_namestringExample:1companystring, nullableaddress1string, nullableaddress2string, nullablecitystring, nullableprovincestring, nullablezipstring, nullablecountrystringExample:United Statescountry_codestringExample:USphonestring, nullabletax_numberstring, nullableeori_numberstring, nullable
shipping_addressobjectShow 14 child attributesHide child attributes
namestringExample:Customer 1first_namestringExample:Customerlast_namestringExample:1companystring, nullableaddress1stringExample:New Yorkaddress2string, nullablecitystringExample:New YorkprovincestringExample:New YorkzipstringExample:10004countrystringExample:United Statescountry_codestringExample:USphonestring, nullabletax_numberstring, nullableeori_numberstring, nullable
line_itemsarray of objectsShow 18 child attributesHide child attributes
idintegerExample:473titlestringExample:The Videographer Snowboardvariant_titlestring, nullableskustringExample:9506.11.21barcodestring, nullableproduct_typestring, nullablequantityintegerExample:1unit_pricestringExample:885.95discountstringExample:0.00discounted_unit_pricestringExample:885.95total_discountstringExample:0.00taxstringExample:78.63tax_linesarray of objectsShow 2 child attributesHide child attributes
titlestringExample:New York State TaxratestringExample:4.0
totalstringExample:885.95refunded_quantityintegerExample:0image_urlstring, nullablepropertiesarray of anysnotestring, nullable
shipping_linesarray of objectsShow 5 child attributesHide child attributes
titlestringExample:StandardpricestringExample:6.90discountstringExample:0.00taxstringExample:0.62tax_linesarray of objectsShow 3 child attributesHide child attributes
titlestringExample:New York State TaxratestringExample:4.0amountstringExample:0.28
tax_linesarray of objectsShow 3 child attributesHide child attributes
titlestringExample:New York State TaxratestringExample:4.0amountstringExample:40.42
discount_codesarray of stringsnotesobjectShow 3 child attributesHide child attributes
notestring, nullablecustom_notestring, nullablenote_attributesarray of anys
custom_fieldsarray of anystagsarray of anystrackingobjectShow 2 child attributesHide child attributes
companiesarray of anys, nullablenumbersarray of anys, nullable
pdfobjectShow 4 child attributesHide child attributes
availablebooleanExample:falsefilenamestring, nullableurlstring, nullablegenerated_atstring, nullable
e_invoiceobjectShow 3 child attributesHide child attributes
statusobject, nullablerequestedbooleanExample:falseerrorstring, nullable
updated_atstringExample:2026-11-10T08:35:17Zrefundsarray of anysalready_existedbooleanExample:true
Errors
Missing or unknown X-Auth-Token, or the shop uninstalled the app.
v3_required: the shop still runs the previous dashboard. paid_plan_required: API access needs a paid plan.
The resource does not exist for this shop, or no action is registered at this path.
The request failed validation. Nothing was saved.
Rate limited: cost-weighted per key (reads cost less than writes). Wait Retry-After seconds; see X-RateLimit-* headers.
Every error has the same shape: see Errors.
curl -X POST "https://app.invoicefalcon.com/api/v3/external/documents/credit_notes" \
-H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"invoice_id": 48213
}'const res = await fetch("https://app.invoicefalcon.com/api/v3/external/documents/credit_notes", {
method: "POST",
headers: {
"X-Auth-Token": process.env.INVOICE_FALCON_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"invoice_id": 48213
}),
});
const data = await res.json();import os
import requests
res = requests.post(
"https://app.invoicefalcon.com/api/v3/external/documents/credit_notes",
headers={"X-Auth-Token": os.environ["INVOICE_FALCON_API_KEY"]},
json={
"invoice_id": 48213
},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.invoicefalcon.com/api/v3/external/documents/credit_notes")
req = Net::HTTP::Post.new(uri, "X-Auth-Token" => ENV["INVOICE_FALCON_API_KEY"], "Content-Type" => "application/json")
req.body = {
invoice_id: 48213
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)curl -X POST "https://app.invoicefalcon.com/api/v3/external/documents/credit_notes" \
-H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"invoice_id": 48213,
"send_email": true
}'const res = await fetch("https://app.invoicefalcon.com/api/v3/external/documents/credit_notes", {
method: "POST",
headers: {
"X-Auth-Token": process.env.INVOICE_FALCON_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"invoice_id": 48213,
"send_email": true
}),
});
const data = await res.json();import os
import requests
res = requests.post(
"https://app.invoicefalcon.com/api/v3/external/documents/credit_notes",
headers={"X-Auth-Token": os.environ["INVOICE_FALCON_API_KEY"]},
json={
"invoice_id": 48213,
"send_email": True
},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.invoicefalcon.com/api/v3/external/documents/credit_notes")
req = Net::HTTP::Post.new(uri, "X-Auth-Token" => ENV["INVOICE_FALCON_API_KEY"], "Content-Type" => "application/json")
req.body = {
invoice_id: 48213,
send_email: true
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)curl -X POST "https://app.invoicefalcon.com/api/v3/external/documents/credit_notes" \
-H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"invoice_id": 48213,
"template_id": 313,
"generate_pdf": false
}'const res = await fetch("https://app.invoicefalcon.com/api/v3/external/documents/credit_notes", {
method: "POST",
headers: {
"X-Auth-Token": process.env.INVOICE_FALCON_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"invoice_id": 48213,
"template_id": 313,
"generate_pdf": false
}),
});
const data = await res.json();import os
import requests
res = requests.post(
"https://app.invoicefalcon.com/api/v3/external/documents/credit_notes",
headers={"X-Auth-Token": os.environ["INVOICE_FALCON_API_KEY"]},
json={
"invoice_id": 48213,
"template_id": 313,
"generate_pdf": False
},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.invoicefalcon.com/api/v3/external/documents/credit_notes")
req = Net::HTTP::Post.new(uri, "X-Auth-Token" => ENV["INVOICE_FALCON_API_KEY"], "Content-Type" => "application/json")
req.body = {
invoice_id: 48213,
template_id: 313,
generate_pdf: false
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body){
"id": 980190966,
"document_type": "credit_note",
"invoice_number": "1",
"title": "Credit Note",
"order": null,
"customer": {
"id": 4,
"name": "Customer 1",
"email": "cus1@gmail.com",
"shopify_customer_id": "gid://shopify/Customer/23935678808145",
"phone": null,
"tax_number": null,
"eori_number": null,
"tags": []
},
"financial_status": "paid",
"currency": "USD",
"total": "1100.22",
"issued_on": "2026-11-10",
"due_on": null,
"sent_at": null,
"printed_at": null,
"reminder_sent_at": null,
"paid": true,
"edited": false,
"trashed": false,
"e_invoice_status": null,
"created_at": "2026-11-10T08:35:17Z",
"credited": {
"invoice_number": "#1001",
"invoice_id": 980190965,
"shopify_order_id": "gid://shopify/Order/12213474623569"
},
"fulfillment_status": null,
"dates": {
"order_placed_at": "2026-11-10T00:00:00Z",
"issued_on": "2026-11-10",
"due_on": null,
"tax_date": null,
"fulfilled_on": null
},
"po_number": null,
"payment_terms": null,
"payment_gateway": "manual",
"locale": "en",
"totals": {
"currency": "USD",
"taxes_included": false,
"subtotal": "1497.95",
"discounts": "494.32",
"shipping": "6.90",
"tax": "89.69",
"duties": "0.00",
"total": "1100.22",
"total_paid": "0.00",
"total_refunded": "0.00",
"total_due": "0.00"
},
"billing_address": {
"name": "Customer 1",
"first_name": "Customer",
"last_name": "1",
"company": null,
"address1": null,
"address2": null,
"city": null,
"province": null,
"zip": null,
"country": "United States",
"country_code": "US",
"phone": null,
"tax_number": null,
"eori_number": null
},
"shipping_address": {
"name": "Customer 1",
"first_name": "Customer",
"last_name": "1",
"company": null,
"address1": "New York",
"address2": null,
"city": "New York",
"province": "New York",
"zip": "10004",
"country": "United States",
"country_code": "US",
"phone": null,
"tax_number": null,
"eori_number": null
},
"line_items": [
{
"id": 473,
"title": "The Videographer Snowboard",
"variant_title": null,
"sku": "9506.11.21",
"barcode": null,
"product_type": null,
"quantity": 1,
"unit_price": "885.95",
"discount": "0.00",
"discounted_unit_price": "885.95",
"total_discount": "0.00",
"tax": "78.63",
"tax_lines": [
{
"title": "New York State Tax",
"rate": "4.0"
},
{
"title": "New York City City Tax",
"rate": "4.5"
},
{
"title": "Metropolitan Commuter Transportation District",
"rate": "0.375"
}
],
"total": "885.95",
"refunded_quantity": 0,
"image_url": null,
"properties": [],
"note": null
},
{
"id": 474,
"title": "Custom 1",
"variant_title": null,
"sku": null,
"barcode": null,
"product_type": null,
"quantity": 1,
"unit_price": "12.00",
"discount": "0.00",
"discounted_unit_price": "12.00",
"total_discount": "0.00",
"tax": "1.07",
"tax_lines": [
{
"title": "New York State Tax",
"rate": "4.0"
},
{
"title": "New York City City Tax",
"rate": "4.5"
},
{
"title": "Metropolitan Commuter Transportation District",
"rate": "0.375"
}
],
"total": "12.00",
"refunded_quantity": 0,
"image_url": null,
"properties": [],
"note": null
},
{
"id": 475,
"title": "The Collection Snowboard: Hydrogen",
"variant_title": null,
"sku": "9506.11.21",
"barcode": null,
"product_type": null,
"quantity": 1,
"unit_price": "600.00",
"discount": "0.00",
"discounted_unit_price": "600.00",
"total_discount": "0.00",
"tax": "53.25",
"tax_lines": [
{
"title": "New York State Tax",
"rate": "4.0"
},
{
"title": "New York City City Tax",
"rate": "4.5"
},
{
"title": "Metropolitan Commuter Transportation District",
"rate": "0.375"
}
],
"total": "600.00",
"refunded_quantity": 0,
"image_url": null,
"properties": [],
"note": null
}
],
"shipping_lines": [
{
"title": "Standard",
"price": "6.90",
"discount": "0.00",
"tax": "0.62",
"tax_lines": [
{
"title": "New York State Tax",
"rate": "4.0",
"amount": "0.28"
},
{
"title": "New York City City Tax",
"rate": "4.5",
"amount": "0.31"
},
{
"title": "Metropolitan Commuter Transportation District",
"rate": "0.375",
"amount": "0.03"
}
]
}
],
"tax_lines": [
{
"title": "New York State Tax",
"rate": "4.0",
"amount": "40.42"
},
{
"title": "New York City City Tax",
"rate": "4.5",
"amount": "45.47"
},
{
"title": "Metropolitan Commuter Transportation District",
"rate": "0.375",
"amount": "3.80"
}
],
"discount_codes": [
"Order discount in percentage"
],
"notes": {
"note": null,
"custom_note": null,
"note_attributes": []
},
"custom_fields": [],
"tags": [],
"tracking": {
"companies": null,
"numbers": null
},
"pdf": {
"available": false,
"filename": null,
"url": null,
"generated_at": null
},
"e_invoice": {
"status": null,
"requested": false,
"error": null
},
"updated_at": "2026-11-10T08:35:17Z",
"refunds": [],
"already_existed": true
}{
"id": 980190966,
"document_type": "credit_note",
"invoice_number": "1",
"title": "Credit Note",
"order": null,
"customer": {
"id": 4,
"name": "Customer 1",
"email": "cus1@gmail.com",
"shopify_customer_id": "gid://shopify/Customer/23935678808145",
"phone": null,
"tax_number": null,
"eori_number": null,
"tags": []
},
"financial_status": "paid",
"currency": "USD",
"total": "1100.22",
"issued_on": "2026-11-10",
"due_on": null,
"sent_at": null,
"printed_at": null,
"reminder_sent_at": null,
"paid": true,
"edited": false,
"trashed": false,
"e_invoice_status": null,
"created_at": "2026-11-10T08:35:17Z",
"credited": {
"invoice_number": "#1001",
"invoice_id": 980190965,
"shopify_order_id": "gid://shopify/Order/12213474623569"
},
"fulfillment_status": null,
"dates": {
"order_placed_at": "2026-11-10T00:00:00Z",
"issued_on": "2026-11-10",
"due_on": null,
"tax_date": null,
"fulfilled_on": null
},
"po_number": null,
"payment_terms": null,
"payment_gateway": "manual",
"locale": "en",
"totals": {
"currency": "USD",
"taxes_included": false,
"subtotal": "1497.95",
"discounts": "494.32",
"shipping": "6.90",
"tax": "89.69",
"duties": "0.00",
"total": "1100.22",
"total_paid": "0.00",
"total_refunded": "0.00",
"total_due": "0.00"
},
"billing_address": {
"name": "Customer 1",
"first_name": "Customer",
"last_name": "1",
"company": null,
"address1": null,
"address2": null,
"city": null,
"province": null,
"zip": null,
"country": "United States",
"country_code": "US",
"phone": null,
"tax_number": null,
"eori_number": null
},
"shipping_address": {
"name": "Customer 1",
"first_name": "Customer",
"last_name": "1",
"company": null,
"address1": "New York",
"address2": null,
"city": "New York",
"province": "New York",
"zip": "10004",
"country": "United States",
"country_code": "US",
"phone": null,
"tax_number": null,
"eori_number": null
},
"line_items": [
{
"id": 473,
"title": "The Videographer Snowboard",
"variant_title": null,
"sku": "9506.11.21",
"barcode": null,
"product_type": null,
"quantity": 1,
"unit_price": "885.95",
"discount": "0.00",
"discounted_unit_price": "885.95",
"total_discount": "0.00",
"tax": "78.63",
"tax_lines": [
{
"title": "New York State Tax",
"rate": "4.0"
},
{
"title": "New York City City Tax",
"rate": "4.5"
},
{
"title": "Metropolitan Commuter Transportation District",
"rate": "0.375"
}
],
"total": "885.95",
"refunded_quantity": 0,
"image_url": null,
"properties": [],
"note": null
},
{
"id": 474,
"title": "Custom 1",
"variant_title": null,
"sku": null,
"barcode": null,
"product_type": null,
"quantity": 1,
"unit_price": "12.00",
"discount": "0.00",
"discounted_unit_price": "12.00",
"total_discount": "0.00",
"tax": "1.07",
"tax_lines": [
{
"title": "New York State Tax",
"rate": "4.0"
},
{
"title": "New York City City Tax",
"rate": "4.5"
},
{
"title": "Metropolitan Commuter Transportation District",
"rate": "0.375"
}
],
"total": "12.00",
"refunded_quantity": 0,
"image_url": null,
"properties": [],
"note": null
},
{
"id": 475,
"title": "The Collection Snowboard: Hydrogen",
"variant_title": null,
"sku": "9506.11.21",
"barcode": null,
"product_type": null,
"quantity": 1,
"unit_price": "600.00",
"discount": "0.00",
"discounted_unit_price": "600.00",
"total_discount": "0.00",
"tax": "53.25",
"tax_lines": [
{
"title": "New York State Tax",
"rate": "4.0"
},
{
"title": "New York City City Tax",
"rate": "4.5"
},
{
"title": "Metropolitan Commuter Transportation District",
"rate": "0.375"
}
],
"total": "600.00",
"refunded_quantity": 0,
"image_url": null,
"properties": [],
"note": null
}
],
"shipping_lines": [
{
"title": "Standard",
"price": "6.90",
"discount": "0.00",
"tax": "0.62",
"tax_lines": [
{
"title": "New York State Tax",
"rate": "4.0",
"amount": "0.28"
},
{
"title": "New York City City Tax",
"rate": "4.5",
"amount": "0.31"
},
{
"title": "Metropolitan Commuter Transportation District",
"rate": "0.375",
"amount": "0.03"
}
]
}
],
"tax_lines": [
{
"title": "New York State Tax",
"rate": "4.0",
"amount": "40.42"
},
{
"title": "New York City City Tax",
"rate": "4.5",
"amount": "45.47"
},
{
"title": "Metropolitan Commuter Transportation District",
"rate": "0.375",
"amount": "3.80"
}
],
"discount_codes": [
"Order discount in percentage"
],
"notes": {
"note": null,
"custom_note": null,
"note_attributes": []
},
"custom_fields": [],
"tags": [],
"tracking": {
"companies": null,
"numbers": null
},
"pdf": {
"available": false,
"filename": null,
"url": null,
"generated_at": null
},
"e_invoice": {
"status": null,
"requested": false,
"error": null
},
"updated_at": "2026-11-10T08:35:17Z",
"refunds": [],
"already_existed": false
}{
"errors": [
"Invalid API key"
],
"code": "unauthorized"
}{
"errors": [
"API access requires a paid plan"
],
"code": "paid_plan_required"
}{
"errors": [
"Resource not found"
],
"code": "not_found"
}{
"errors": [
"id is missing"
]
}{
"errors": [
"Rate limit exceeded"
],
"code": "rate_limited"
}