Skip to content

Update invoice

PATCH/documents/invoices/{id}

Costs 2 rate-limit points · Rate limits

Edits the fields of one invoice the invoice editor lets a merchant change: document number, issue, due, tax and fulfilment dates, PO number, payment terms, the order note, the footer note and up to four custom fields. Only the keys sent change; returns the full invoice.

Marks the invoice edited, so a Shopify resync no longer overwrites it until it is regenerated. Allowed even when the shop locks issued invoices: the lock stops Shopify resyncs, not merchant edits. The stored PDF is re-rendered on the next download or send.

Also searched asedit invoicechange invoice due datechange invoice numberadd note to invoiceset po number on invoiceupdate invoice fieldschange invoice dateedit custom fields

Path parameters

  • idstringRequired

Request body

  • invoice_numberstring

    Document number shown on the invoice.

  • issued_onstring

    Invoice date (YYYY-MM-DD).

  • due_onstring, nullable

    Due date; null or "" clears it.

  • tax_datestring, nullable

    Tax point date; null clears it.

  • fulfilled_onstring, nullable

    Fulfilment date; null clears it.

  • po_numberstring, nullable

    Purchase order number; null clears it.

  • payment_termsstring, nullable

    Payment terms text; null clears it.

  • notestring, nullable

    Order note printed on the invoice; null clears it.

  • custom_notestring, nullable

    Footer note for this invoice; null clears it.

  • custom_fieldsarray of objects

    Up to 4 {title, body} pairs; replaces the existing set, [] clears them.

    Show 2 child attributesHide child attributes
    • titlestring
      Example: Ref
    • bodystring
      Example: X1

Returns

  • idinteger
    Example: 980190979
  • document_typestring
    Example: invoice
  • invoice_numberstring
    Example: INV-77
  • titlestring
    Example: Invoice
  • orderobject
    Show 3 child attributesHide child attributes
    • shopify_order_idstring
      Example: gid://shopify/Order/12213474623569
    • namestring
      Example: #1001
    • numberinteger
      Example: 1001
  • customerobject
    Show 8 child attributesHide child attributes
    • idinteger
      Example: 11
    • namestring
      Example: Customer 1
    • emailstring
      Example: cus1@gmail.com
    • shopify_customer_idstring
      Example: gid://shopify/Customer/23935678808145
    • phonestring, nullable
    • tax_numberstring, nullable
    • eori_numberstring, nullable
    • tagsarray of anys
  • financial_statusstring
    Example: paid
  • currencystring
    Example: USD
  • totalstring
    Example: 1100.22
  • issued_onstring
    Example: 2025-12-11
  • due_onstring, nullable
    Example: 2026-03-01
  • sent_atstring, nullable
  • printed_atstring, nullable
  • reminder_sent_atstring, nullable
  • paidboolean
    Example: true
  • editedboolean
    Example: true
  • trashedboolean
    Example: false
  • e_invoice_statusstring, nullable
  • created_atstring
    Example: 2026-11-10T08:35:18Z
  • fulfillment_statusstring, nullable
  • datesobject
    Show 5 child attributesHide child attributes
    • order_placed_atstring
      Example: 2025-12-11T00:00:00Z
    • issued_onstring
      Example: 2025-12-11
    • due_onstring, nullable
      Example: 2026-03-01
    • tax_datestring, nullable
    • fulfilled_onstring, nullable
  • po_numberstring, nullable
    Example: PO-9
  • payment_termsstring, nullable
  • payment_gatewaystring
    Example: manual
  • localestring
    Example: en
  • totalsobject
    Show 11 child attributesHide child attributes
    • currencystring
      Example: USD
    • taxes_includedboolean
      Example: false
    • subtotalstring
      Example: 1497.95
    • discountsstring
      Example: 494.32
    • shippingstring
      Example: 6.90
    • taxstring
      Example: 89.69
    • dutiesstring
      Example: 0.00
    • totalstring
      Example: 1100.22
    • total_paidstring
      Example: 0.00
    • total_refundedstring
      Example: 0.00
    • total_duestring
      Example: 0.00
  • billing_addressobject
    Show 14 child attributesHide child attributes
    • namestring
      Example: Customer 1
    • first_namestring
      Example: Customer
    • last_namestring
      Example: 1
    • companystring, nullable
    • address1string, nullable
    • address2string, nullable
    • citystring, nullable
    • provincestring, nullable
    • zipstring, nullable
    • countrystring
      Example: United States
    • country_codestring
      Example: US
    • phonestring, nullable
    • tax_numberstring, nullable
    • eori_numberstring, nullable
  • shipping_addressobject
    Show 14 child attributesHide child attributes
    • namestring
      Example: Customer 1
    • first_namestring
      Example: Customer
    • last_namestring
      Example: 1
    • companystring, nullable
    • address1string
      Example: New York
    • address2string, nullable
    • citystring
      Example: New York
    • provincestring
      Example: New York
    • zipstring
      Example: 10004
    • countrystring
      Example: United States
    • country_codestring
      Example: US
    • phonestring, nullable
    • tax_numberstring, nullable
    • eori_numberstring, nullable
  • line_itemsarray of objects
    Show 18 child attributesHide child attributes
    • idinteger
      Example: 494
    • titlestring
      Example: The Videographer Snowboard
    • variant_titlestring, nullable
    • skustring
      Example: 9506.11.21
    • barcodestring, nullable
    • product_typestring, nullable
    • quantityinteger
      Example: 1
    • unit_pricestring
      Example: 885.95
    • discountstring
      Example: 0.00
    • discounted_unit_pricestring
      Example: 885.95
    • total_discountstring
      Example: 0.00
    • taxstring
      Example: 78.63
    • tax_linesarray of objects
      Show 2 child attributesHide child attributes
      • titlestring
        Example: New York State Tax
      • ratestring
        Example: 4.0
    • totalstring
      Example: 885.95
    • refunded_quantityinteger
      Example: 0
    • image_urlstring, nullable
    • propertiesarray of anys
    • notestring, nullable
  • shipping_linesarray of objects
    Show 5 child attributesHide child attributes
    • titlestring
      Example: Standard
    • pricestring
      Example: 6.90
    • discountstring
      Example: 0.00
    • taxstring
      Example: 0.62
    • tax_linesarray of objects
      Show 3 child attributesHide child attributes
      • titlestring
        Example: New York State Tax
      • ratestring
        Example: 4.0
      • amountstring
        Example: 0.28
  • tax_linesarray of objects
    Show 3 child attributesHide child attributes
    • titlestring
      Example: New York State Tax
    • ratestring
      Example: 4.0
    • amountstring
      Example: 40.42
  • discount_codesarray of strings
  • notesobject
    Show 3 child attributesHide child attributes
    • notestring, nullable
    • custom_notestring, nullable
      Example: Thanks
    • note_attributesarray of anys
  • custom_fieldsarray of objects
    Show 2 child attributesHide child attributes
    • titlestring
      Example: Ref
    • bodystring
      Example: X1
  • tagsarray of anys
  • trackingobject
    Show 2 child attributesHide child attributes
    • companiesarray of anys, nullable
    • numbersarray of anys, nullable
  • pdfobject
    Show 4 child attributesHide child attributes
    • availableboolean
      Example: false
    • filenamestring, nullable
    • urlstring, nullable
    • generated_atstring, nullable
  • e_invoiceobject
    Show 3 child attributesHide child attributes
    • statusobject, nullable
    • requestedboolean
      Example: false
    • errorstring, nullable
  • updated_atstring
    Example: 2026-11-10T08:35:18Z

Errors

401

Missing or unknown X-Auth-Token, or the shop uninstalled the app.

403

v3_required: the shop still runs the previous dashboard. paid_plan_required: API access needs a paid plan.

404

The resource does not exist for this shop, or no action is registered at this path.

409

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.

422

The request failed validation. Nothing was saved.

429

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.

PATCH/documents/invoices/{id}
curl -X PATCH "https://app.invoicefalcon.com/api/v3/external/documents/invoices/980191059" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_number": "INV-77",
    "due_on": "2026-03-01",
    "po_number": "PO-9",
    "custom_note": "Thanks",
    "custom_fields": [
      {
        "title": "Ref",
        "body": "X1"
      }
    ]
  }'
Response
{
  "id": 980190979,
  "document_type": "invoice",
  "invoice_number": "INV-77",
  "title": "Invoice",
  "order": {
    "shopify_order_id": "gid://shopify/Order/12213474623569",
    "name": "#1001",
    "number": 1001
  },
  "customer": {
    "id": 11,
    "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": "2026-03-01",
  "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:18Z",
  "fulfillment_status": null,
  "dates": {
    "order_placed_at": "2025-12-11T00:00:00Z",
    "issued_on": "2025-12-11",
    "due_on": "2026-03-01",
    "tax_date": null,
    "fulfilled_on": null
  },
  "po_number": "PO-9",
  "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": 494,
      "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": 495,
      "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": 496,
      "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": "Thanks",
    "note_attributes": []
  },
  "custom_fields": [
    {
      "title": "Ref",
      "body": "X1"
    }
  ],
  "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:18Z"
}