Create invoice
/documents/invoicesCosts 2 rate-limit points · Rate limits
Creates the invoice for a Shopify order the way the order page does: reads the order from Shopify, builds the invoice with its line items, taxes and addresses, renders the PDF and returns the full invoice. If the shop already has an invoice for that order (most are created by the order webhook) that invoice is returned with already_existed: true instead of a duplicate.
Renders a PDF, which counts against a free plan invoice limit. With send_email: true it also emails the invoice to the customer immediately. An order placed before the store's invoicing start date (account/documents → dates.invoicing_start_date) is refused with 422 before_invoicing_start_date unless ignore_start_date is true; confirm with the merchant first.
Also searched ascreate invoiceinvoice this ordergenerate invoice for ordermake an invoicenew invoiceinvoice order #1001issue invoice
Request body
order_idstringRequiredThe Shopify order: a gid (gid://shopify/Order/123), a bare id, or the order name ('#1001').
send_emailbooleantrue emails the invoice to the order customer right after creating it (default false).
generate_pdfbooleanfalse skips rendering the PDF (default true).
template_idintegerTemplate to render with. Default: the shop default invoice template.
ignore_start_datebooleantrue creates the invoice even though the order was placed before the invoicing start date (default false).
Returns
idintegerExample:980190995document_typestringExample:invoiceinvoice_numberstringExample:#1001titlestringExample:InvoiceorderobjectShow 3 child attributesHide child attributes
shopify_order_idstringExample:gid://shopify/Order/424242namestringExample:#1001numberintegerExample:1001
customerobjectShow 8 child attributesHide child attributes
idintegerExample:19namestringExample: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:2025-12-11due_onstring, nullablesent_atstring, nullableprinted_atstring, nullablereminder_sent_atstring, nullablepaidbooleanExample:trueeditedbooleanExample:falsetrashedbooleanExample:falsee_invoice_statusstring, nullablecreated_atstringExample:2026-11-10T08:35:20Zfulfillment_statusstring, nullabledatesobjectShow 5 child attributesHide child attributes
order_placed_atstringExample:2025-12-11T00:00:00Zissued_onstringExample:2025-12-11due_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:518titlestringExample: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:20Zalready_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 conflicts with the current state (an issued invoice is locked, the next invoice number moved, a template is still in use, a job already finished). Nothing was changed.
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/invoices" \
-H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"order_id": "#1001"
}'const res = await fetch("https://app.invoicefalcon.com/api/v3/external/documents/invoices", {
method: "POST",
headers: {
"X-Auth-Token": process.env.INVOICE_FALCON_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"order_id": "#1001"
}),
});
const data = await res.json();import os
import requests
res = requests.post(
"https://app.invoicefalcon.com/api/v3/external/documents/invoices",
headers={"X-Auth-Token": os.environ["INVOICE_FALCON_API_KEY"]},
json={
"order_id": "#1001"
},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.invoicefalcon.com/api/v3/external/documents/invoices")
req = Net::HTTP::Post.new(uri, "X-Auth-Token" => ENV["INVOICE_FALCON_API_KEY"], "Content-Type" => "application/json")
req.body = {
order_id: "#1001"
}.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/invoices" \
-H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"order_id": "gid://shopify/Order/5873241604411",
"send_email": true
}'const res = await fetch("https://app.invoicefalcon.com/api/v3/external/documents/invoices", {
method: "POST",
headers: {
"X-Auth-Token": process.env.INVOICE_FALCON_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"order_id": "gid://shopify/Order/5873241604411",
"send_email": true
}),
});
const data = await res.json();import os
import requests
res = requests.post(
"https://app.invoicefalcon.com/api/v3/external/documents/invoices",
headers={"X-Auth-Token": os.environ["INVOICE_FALCON_API_KEY"]},
json={
"order_id": "gid://shopify/Order/5873241604411",
"send_email": True
},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.invoicefalcon.com/api/v3/external/documents/invoices")
req = Net::HTTP::Post.new(uri, "X-Auth-Token" => ENV["INVOICE_FALCON_API_KEY"], "Content-Type" => "application/json")
req.body = {
order_id: "gid://shopify/Order/5873241604411",
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/invoices" \
-H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"order_id": 5873241604411,
"generate_pdf": false
}'const res = await fetch("https://app.invoicefalcon.com/api/v3/external/documents/invoices", {
method: "POST",
headers: {
"X-Auth-Token": process.env.INVOICE_FALCON_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"order_id": 5873241604411,
"generate_pdf": false
}),
});
const data = await res.json();import os
import requests
res = requests.post(
"https://app.invoicefalcon.com/api/v3/external/documents/invoices",
headers={"X-Auth-Token": os.environ["INVOICE_FALCON_API_KEY"]},
json={
"order_id": 5873241604411,
"generate_pdf": False
},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.invoicefalcon.com/api/v3/external/documents/invoices")
req = Net::HTTP::Post.new(uri, "X-Auth-Token" => ENV["INVOICE_FALCON_API_KEY"], "Content-Type" => "application/json")
req.body = {
order_id: 5873241604411,
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)curl -X POST "https://app.invoicefalcon.com/api/v3/external/documents/invoices" \
-H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"order_id": "#1001",
"template_id": 311
}'const res = await fetch("https://app.invoicefalcon.com/api/v3/external/documents/invoices", {
method: "POST",
headers: {
"X-Auth-Token": process.env.INVOICE_FALCON_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"order_id": "#1001",
"template_id": 311
}),
});
const data = await res.json();import os
import requests
res = requests.post(
"https://app.invoicefalcon.com/api/v3/external/documents/invoices",
headers={"X-Auth-Token": os.environ["INVOICE_FALCON_API_KEY"]},
json={
"order_id": "#1001",
"template_id": 311
},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.invoicefalcon.com/api/v3/external/documents/invoices")
req = Net::HTTP::Post.new(uri, "X-Auth-Token" => ENV["INVOICE_FALCON_API_KEY"], "Content-Type" => "application/json")
req.body = {
order_id: "#1001",
template_id: 311
}.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/invoices" \
-H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"order_id": "#1001",
"ignore_start_date": true
}'const res = await fetch("https://app.invoicefalcon.com/api/v3/external/documents/invoices", {
method: "POST",
headers: {
"X-Auth-Token": process.env.INVOICE_FALCON_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"order_id": "#1001",
"ignore_start_date": true
}),
});
const data = await res.json();import os
import requests
res = requests.post(
"https://app.invoicefalcon.com/api/v3/external/documents/invoices",
headers={"X-Auth-Token": os.environ["INVOICE_FALCON_API_KEY"]},
json={
"order_id": "#1001",
"ignore_start_date": True
},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.invoicefalcon.com/api/v3/external/documents/invoices")
req = Net::HTTP::Post.new(uri, "X-Auth-Token" => ENV["INVOICE_FALCON_API_KEY"], "Content-Type" => "application/json")
req.body = {
order_id: "#1001",
ignore_start_date: true
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body){
"id": 980190995,
"document_type": "invoice",
"invoice_number": "#1001",
"title": "Invoice",
"order": {
"shopify_order_id": "gid://shopify/Order/424242",
"name": "#1001",
"number": 1001
},
"customer": {
"id": 19,
"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": "2025-12-11",
"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:20Z",
"fulfillment_status": null,
"dates": {
"order_placed_at": "2025-12-11T00:00:00Z",
"issued_on": "2025-12-11",
"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": 518,
"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": 519,
"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": 520,
"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:20Z",
"already_existed": true
}{
"id": 980190995,
"document_type": "invoice",
"invoice_number": "#1001",
"title": "Invoice",
"order": {
"shopify_order_id": "gid://shopify/Order/424242",
"name": "#1001",
"number": 1001
},
"customer": {
"id": 19,
"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": "2025-12-11",
"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:20Z",
"fulfillment_status": null,
"dates": {
"order_placed_at": "2025-12-11T00:00:00Z",
"issued_on": "2025-12-11",
"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": 518,
"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": 519,
"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": 520,
"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:20Z",
"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": [
"This shop keeps issued invoices unchanged, so this invoice cannot be edited."
],
"code": "invoice_locked"
}{
"errors": [
"id is missing"
]
}{
"errors": [
"Rate limit exceeded"
],
"code": "rate_limited"
}