Mark invoice paid
/documents/invoices/{id}/mark_paidCosts 2 rate-limit points · Rate limits
Marks an invoice paid on the document: sets its financial status to paid and the paid-at time, the same field edit the invoice editor saves. Payment reminders stop for it. Shopify is not told; the order itself keeps its own payment state.
Changes the invoice document only (it is marked edited, so a Shopify resync no longer overwrites it). Does not record a payment in Shopify. Calling it on an invoice that is already paid changes nothing and returns the invoice as it is.
Also searched asmark invoice paidmark as paidinvoice was paidrecord payment on invoiceset invoice paidcustomer paid this invoice
Path parameters
idstringRequired
Request body
paid_atstringWhen it was paid (ISO 8601). Default: now.
Returns
idintegerExample:980191007document_typestringExample:invoiceinvoice_numberstringExample:#1001titlestringExample:InvoiceorderobjectShow 3 child attributesHide child attributes
shopify_order_idstringExample:gid://shopify/Order/12213474623569namestringExample:#1001numberintegerExample:1001
customerobjectShow 8 child attributesHide child attributes
idintegerExample:25namestringExample: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:truetrashedbooleanExample:falsee_invoice_statusstring, nullablecreated_atstringExample:2026-11-10T08:35:22Zfulfillment_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:536titlestringExample: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:22Z
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/980191059/mark_paid" \
-H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch("https://app.invoicefalcon.com/api/v3/external/documents/invoices/980191059/mark_paid", {
method: "POST",
headers: {
"X-Auth-Token": process.env.INVOICE_FALCON_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({}),
});
const data = await res.json();import os
import requests
res = requests.post(
"https://app.invoicefalcon.com/api/v3/external/documents/invoices/980191059/mark_paid",
headers={"X-Auth-Token": os.environ["INVOICE_FALCON_API_KEY"]},
json={},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.invoicefalcon.com/api/v3/external/documents/invoices/980191059/mark_paid")
req = Net::HTTP::Post.new(uri, "X-Auth-Token" => ENV["INVOICE_FALCON_API_KEY"], "Content-Type" => "application/json")
req.body = {}.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/980191059/mark_paid" \
-H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"paid_at": "2026-03-14T10:30:00Z"
}'const res = await fetch("https://app.invoicefalcon.com/api/v3/external/documents/invoices/980191059/mark_paid", {
method: "POST",
headers: {
"X-Auth-Token": process.env.INVOICE_FALCON_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"paid_at": "2026-03-14T10:30:00Z"
}),
});
const data = await res.json();import os
import requests
res = requests.post(
"https://app.invoicefalcon.com/api/v3/external/documents/invoices/980191059/mark_paid",
headers={"X-Auth-Token": os.environ["INVOICE_FALCON_API_KEY"]},
json={
"paid_at": "2026-03-14T10:30:00Z"
},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.invoicefalcon.com/api/v3/external/documents/invoices/980191059/mark_paid")
req = Net::HTTP::Post.new(uri, "X-Auth-Token" => ENV["INVOICE_FALCON_API_KEY"], "Content-Type" => "application/json")
req.body = {
paid_at: "2026-03-14T10:30:00Z"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body){
"id": 980191007,
"document_type": "invoice",
"invoice_number": "#1001",
"title": "Invoice",
"order": {
"shopify_order_id": "gid://shopify/Order/12213474623569",
"name": "#1001",
"number": 1001
},
"customer": {
"id": 25,
"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": true,
"trashed": false,
"e_invoice_status": null,
"created_at": "2026-11-10T08:35:22Z",
"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": 536,
"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": 537,
"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": 538,
"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:22Z"
}{
"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"
}