---
title: "Update invoice"
description: "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. On"
url: https://docs.invoicefalcon.com/v3-reference/documents/update-invoice/
api: "API v3 reference"
method: PATCH
path: "/documents/invoices/{id}"
---

# Update invoice

`PATCH https://app.invoicefalcon.com/api/v3/external/documents/invoices/{id}`

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.

**Note:** 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.

## Path parameters

- `id` (string, required)

## Request body

- `invoice_number` (string): Document number shown on the invoice.
- `issued_on` (string): Invoice date (YYYY-MM-DD).
- `due_on` (string, nullable): Due date; null or &quot;&quot; clears it.
- `tax_date` (string, nullable): Tax point date; null clears it.
- `fulfilled_on` (string, nullable): Fulfilment date; null clears it.
- `po_number` (string, nullable): Purchase order number; null clears it.
- `payment_terms` (string, nullable): Payment terms text; null clears it.
- `note` (string, nullable): Order note printed on the invoice; null clears it.
- `custom_note` (string, nullable): Footer note for this invoice; null clears it.
- `custom_fields` (array of objects): Up to 4 {title, body} pairs; replaces the existing set, [] clears them.
  - `title` (string): e.g. `Ref`
  - `body` (string): e.g. `X1`

## Returns

- `id` (integer): e.g. `980190979`
- `document_type` (string): e.g. `invoice`
- `invoice_number` (string): e.g. `INV-77`
- `title` (string): e.g. `Invoice`
- `order` (object)
  - `shopify_order_id` (string): e.g. `gid://shopify/Order/12213474623569`
  - `name` (string): e.g. `#1001`
  - `number` (integer): e.g. `1001`
- `customer` (object)
  - `id` (integer): e.g. `11`
  - `name` (string): e.g. `Customer 1`
  - `email` (string): e.g. `cus1@gmail.com`
  - `shopify_customer_id` (string): e.g. `gid://shopify/Customer/23935678808145`
  - `phone` (string, nullable)
  - `tax_number` (string, nullable)
  - `eori_number` (string, nullable)
  - `tags` (array of anys)
- `financial_status` (string): e.g. `paid`
- `currency` (string): e.g. `USD`
- `total` (string): e.g. `1100.22`
- `issued_on` (string): e.g. `2025-12-11`
- `due_on` (string, nullable): e.g. `2026-03-01`
- `sent_at` (string, nullable)
- `printed_at` (string, nullable)
- `reminder_sent_at` (string, nullable)
- `paid` (boolean): e.g. `true`
- `edited` (boolean): e.g. `true`
- `trashed` (boolean): e.g. `false`
- `e_invoice_status` (string, nullable)
- `created_at` (string): e.g. `2026-11-10T08:35:18Z`
- `fulfillment_status` (string, nullable)
- `dates` (object)
  - `order_placed_at` (string): e.g. `2025-12-11T00:00:00Z`
  - `issued_on` (string): e.g. `2025-12-11`
  - `due_on` (string, nullable): e.g. `2026-03-01`
  - `tax_date` (string, nullable)
  - `fulfilled_on` (string, nullable)
- `po_number` (string, nullable): e.g. `PO-9`
- `payment_terms` (string, nullable)
- `payment_gateway` (string): e.g. `manual`
- `locale` (string): e.g. `en`
- `totals` (object)
  - `currency` (string): e.g. `USD`
  - `taxes_included` (boolean): e.g. `false`
  - `subtotal` (string): e.g. `1497.95`
  - `discounts` (string): e.g. `494.32`
  - `shipping` (string): e.g. `6.90`
  - `tax` (string): e.g. `89.69`
  - `duties` (string): e.g. `0.00`
  - `total` (string): e.g. `1100.22`
  - `total_paid` (string): e.g. `0.00`
  - `total_refunded` (string): e.g. `0.00`
  - `total_due` (string): e.g. `0.00`
- `billing_address` (object)
  - `name` (string): e.g. `Customer 1`
  - `first_name` (string): e.g. `Customer`
  - `last_name` (string): e.g. `1`
  - `company` (string, nullable)
  - `address1` (string, nullable)
  - `address2` (string, nullable)
  - `city` (string, nullable)
  - `province` (string, nullable)
  - `zip` (string, nullable)
  - `country` (string): e.g. `United States`
  - `country_code` (string): e.g. `US`
  - `phone` (string, nullable)
  - `tax_number` (string, nullable)
  - `eori_number` (string, nullable)
- `shipping_address` (object)
  - `name` (string): e.g. `Customer 1`
  - `first_name` (string): e.g. `Customer`
  - `last_name` (string): e.g. `1`
  - `company` (string, nullable)
  - `address1` (string): e.g. `New York`
  - `address2` (string, nullable)
  - `city` (string): e.g. `New York`
  - `province` (string): e.g. `New York`
  - `zip` (string): e.g. `10004`
  - `country` (string): e.g. `United States`
  - `country_code` (string): e.g. `US`
  - `phone` (string, nullable)
  - `tax_number` (string, nullable)
  - `eori_number` (string, nullable)
- `line_items` (array of objects)
  - `id` (integer): e.g. `494`
  - `title` (string): e.g. `The Videographer Snowboard`
  - `variant_title` (string, nullable)
  - `sku` (string): e.g. `9506.11.21`
  - `barcode` (string, nullable)
  - `product_type` (string, nullable)
  - `quantity` (integer): e.g. `1`
  - `unit_price` (string): e.g. `885.95`
  - `discount` (string): e.g. `0.00`
  - `discounted_unit_price` (string): e.g. `885.95`
  - `total_discount` (string): e.g. `0.00`
  - `tax` (string): e.g. `78.63`
  - `tax_lines` (array of objects)
    - `title` (string): e.g. `New York State Tax`
    - `rate` (string): e.g. `4.0`
  - `total` (string): e.g. `885.95`
  - `refunded_quantity` (integer): e.g. `0`
  - `image_url` (string, nullable)
  - `properties` (array of anys)
  - `note` (string, nullable)
- `shipping_lines` (array of objects)
  - `title` (string): e.g. `Standard`
  - `price` (string): e.g. `6.90`
  - `discount` (string): e.g. `0.00`
  - `tax` (string): e.g. `0.62`
  - `tax_lines` (array of objects)
    - `title` (string): e.g. `New York State Tax`
    - `rate` (string): e.g. `4.0`
    - `amount` (string): e.g. `0.28`
- `tax_lines` (array of objects)
  - `title` (string): e.g. `New York State Tax`
  - `rate` (string): e.g. `4.0`
  - `amount` (string): e.g. `40.42`
- `discount_codes` (array of strings)
- `notes` (object)
  - `note` (string, nullable)
  - `custom_note` (string, nullable): e.g. `Thanks`
  - `note_attributes` (array of anys)
- `custom_fields` (array of objects)
  - `title` (string): e.g. `Ref`
  - `body` (string): e.g. `X1`
- `tags` (array of anys)
- `tracking` (object)
  - `companies` (array of anys, nullable)
  - `numbers` (array of anys, nullable)
- `pdf` (object)
  - `available` (boolean): e.g. `false`
  - `filename` (string, nullable)
  - `url` (string, nullable)
  - `generated_at` (string, nullable)
- `e_invoice` (object)
  - `status` (object, nullable)
  - `requested` (boolean): e.g. `false`
  - `error` (string, nullable)
- `updated_at` (string): e.g. `2026-11-10T08:35:18Z`

Rate limit: this call costs 2 points ([rate limits](https://docs.invoicefalcon.com/v3/docs/api-v3/rate-limits/)).

## Example request

```sh
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"
      }
    ]
  }'
```

## 200

The updated resource.

```json
{
  "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"
}
```

## 401

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

```json
{
  "errors": [
    "Invalid API key"
  ],
  "code": "unauthorized"
}
```

## 403

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

```json
{
  "errors": [
    "API access requires a paid plan"
  ],
  "code": "paid_plan_required"
}
```

## 404

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

```json
{
  "errors": [
    "Resource not found"
  ],
  "code": "not_found"
}
```

## 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.

```json
{
  "errors": [
    "This shop keeps issued invoices unchanged, so this invoice cannot be edited."
  ],
  "code": "invoice_locked"
}
```

## 422

The request failed validation. Nothing was saved.

```json
{
  "errors": [
    "id is missing"
  ]
}
```

## 429

Rate limited: cost-weighted per key (reads cost less than writes). Wait `Retry-After` seconds; see `X-RateLimit-*` headers.

```json
{
  "errors": [
    "Rate limit exceeded"
  ],
  "code": "rate_limited"
}
```

