Invoices

Endpoints under /api2/invoice to list, look up, create (full or partial capture) and resend the email of invoices linked to orders. Supports capture in online, offline or no_capture modes and identification by order_id or order_increment_id.

REST JSON Bearer Token New in 2026

Overview

The invoices resource documents the financial side of the order: capture, gateway interaction and customer email. For shared family rules (pagination, dates, HTTP statuses, items handling), see the main Orders page.

Capture modesonline, offline and no_capture.

Identifiersorder_id or order_increment_id.

opt

Partial itemsorder_item_id or sku + qty.

Aliases/api2/invoice and /api2/invoices.

GET/api2/invoice

List invoices.

ListingFilters

page, limit, include_pagination Optional

Standard pagination.

order_id Optional

Internal order ID.

order_increment_id Optional

Order increment number.

increment_id Optional

Invoice increment number. A single value returns the detailed invoice; list or array works as a filter.

state Optional

Invoice state. Common values: 1 open, 2 paid, 3 canceled.

created_from, created_to Optional

Created-at range.

sort, direction Optional

Accepted fields: entity_id, created_at, updated_at, increment_id, grand_total.

Examples

GET /api2/invoice?page=1&limit=50&include_pagination=1
Authorization: Bearer {{token}}

GET /api2/invoice?order_increment_id=100000123
Authorization: Bearer {{token}}

{
  "page": 1,
  "limit": 50,
  "include_pagination": 1,
  "order_increment_id": "100000123",
  "created_from": "2026-01-01",
  "created_to": "2026-12-31"
}

List responses use the invoices key. Lookup by ID or single increment_id uses the invoice key. A plural alias /api2/invoices exists.

GET/api2/invoice

Get a single invoice.

GET /api2/invoice?id=456
Authorization: Bearer {{token}}

GET /api2/invoice?increment_id=100000045
Authorization: Bearer {{token}}

POST/api2/invoice/create

Capture an order invoice fully or partially.

CaptureInvoice

order_id / order_increment_id

Order identifier. Use exactly one.

items Optional

Items to invoice. Each entry uses order_item_id or sku + qty. If omitted, captures all available quantities.

capture Optional

Accepts online, offline or no_capture. Default offline.

send_email Optional

When true, sends the invoice email after saving.

comment Optional

Comment recorded on the invoice.

is_customer_notified, is_visible_on_front Optional

Comment flags only — they do not trigger an email by themselves.

Full capture

POST /api2/invoice/create
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "order_increment_id": "100000123",
  "capture": "offline",
  "send_email": true,
  "comment": "Invoice created by integration."
}

Partial capture

POST /api2/invoice/create
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "order_id": 123,
  "items": [
    {"order_item_id": 10, "qty": 1},
    {"sku": "PRODUCT-001", "qty": 2}
  ],
  "capture": "no_capture"
}

POST/api2/invoice/email

Resend the invoice email. Identify the invoice with invoice_id, id or increment_id.

POST /api2/invoice/email
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "invoice_id": 456,
  "comment": "Resend requested by integration."
}

Supported usage patterns

Tested and certified combinations for the Invoices resource.

List open invoicesGET /api2/invoice?state=1&include_pagination=1

Invoices for an orderGET /api2/invoice?order_increment_id=100000123

Invoice by numberGET /api2/invoice?increment_id=100000045

Full offline capturePOST /api2/invoice/create + capture=offline

Partial capture without gatewayPOST /api2/invoice/create + items[] + capture=no_capture

Resend emailPOST /api2/invoice/email

Integration recommendations

Avoid

Trusting send_email=true alone instead of an explicit resend via /api2/invoice/email after SMTP failures.
Mixing order_id and order_increment_id in the same payload.
Using capture=online without confirming gateway support — the error will surface from the payment integration.

Financial audit

For accounting reconciliation, prefer capture=offline + comment identifying the source system (e.g. "Invoiced via ERP-XYZ"). This keeps traceability in the order history without touching the gateway.

Common errors

Status	Sample body	When it happens
`400`	`{"error": "Invalid item"}`	An `items` entry without `order_item_id`/`sku` or with non-positive `qty`.
`400`	`{"error": "Cannot create invoice"}`	The order no longer accepts further invoicing (e.g. fully invoiced or canceled).
`401`	`{"error": "Unauthorized"}`	Missing `Authorization` or expired token.
`404`	`{"error": "Order not found"}`	Unknown `order_id` or `order_increment_id`.
`404`	`{"error": "Invoice not found"}`	Unknown `invoice_id` or `increment_id`.
`409`	`{"error": "Conflict on save"}`	Duplicate or deadlock on concurrent writes.
`500`	`{"error": "Payment gateway error"}`	Failure relayed by the payment method when `capture=online`.

Invoices

Overview

Examples

Full capture

Partial capture

Supported usage patterns

Integration recommendations

Recommended

Avoid

Financial audit

Common errors