comecerodocs
Invoices

Get an invoice

GET
/invoices/{invoice_id}

Returns one invoice. Send Accept: application/pdf to get the invoice as a PDF file instead of JSON. Takes a secret, trusted or limited token. A limited token must be bound to the invoice and cannot see a draft, and it does not get the settlement_ fields, reference prices or tax codes.

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Path Parameters

invoice_id*string

The invoice id.

Query Parameters

expand?string

Comma-separated child objects to return in full instead of as a URL, for example customer,payments. Use dot notation for nested objects (items.product), up to four levels deep. A single object takes up to 12 paths; a list takes up to 2, applied to every item. Extra paths are dropped without an error. See Expanding objects.

show?string

Comma-separated fields to return; all others are left out. Use dot notation for child fields (customer.email). You cannot send show and hide together (400). See Customizing output.

hide?string

Comma-separated fields to leave out of the response. Use dot notation for child fields (customer.email). You cannot send show and hide together (400). See Customizing output.

formatted?boolean

When true, the object also has a formatted child with amounts and dates as display text in the shopper's language and currency (for example $19.99 or November 7, 2026). The default is false. See Localized formatting.

Defaultfalse
timezone?string

An IANA time zone name, such as America/New_York or UTC. It sets how date_start and date_end are read and the time zone of every date in the response. The default is the account's time zone (Settings, Technical), or UTC when it has none. A name that is not known is a 400.

Response Body

The invoice, or its PDF when you ask for application/pdf.

  1. response

A bill you send to a customer, who pays it from a link. A new invoice is a draft (draft: true): you can change it freely and the customer cannot see it. Publishing it (draft: false) fires invoice:published and, unless you ask otherwise, emails the customer a payment link. When the invoice is paid in full it closes (open: false) and becomes an order with the same id. Money fields are in the invoice currency unless the field name starts with settlement_.

object?"invoice"

The object type. Always invoice.

Value in"invoice"
url?string

The full URL of this invoice.

Formaturi
date_created?string

When the invoice was created.

Formatdate-time
date_modified?string

When the invoice was last changed.

Formatdate-time
date_due?|

When payment is due. Required before the invoice can be published.

Formatdate-time
past_due?boolean

True when date_due has passed and the invoice is still unpaid, scheduled, pending, failed or waiting for a retry.

invoice_id?string

The invoice id. It is also the order_id of the order the invoice becomes when paid.

test?boolean

True for a test invoice.

account_id?string

The account the invoice belongs to.

order_id?string

The id the order will have once the invoice is paid. Same as invoice_id.

open?boolean

True while the invoice can still be changed or paid. It turns false when the invoice is paid in full.

payment_status?string

Where payment stands. unpaid: nothing paid yet. scheduled: Comecero will charge the customer's saved payment method automatically (autopay_at). processing or pending: a payment is under way. completed: paid in full. failed or retry: the last automatic payment failed. cancelled and refunded follow the order.

Value in"unpaid""scheduled""processing""pending""completed""failed""retry""cancelled""refunded"
currency?string

The currency the customer pays in, a three-letter ISO 4217 code.

subtotal?number

The sum of the item subtotals after item discounts.

subtotal_original?number

The sum of the item subtotals before discounts.

shipping?number

Shipping after discounts.

shipping_original?number

Shipping before discounts.

discount?number

The discount on the whole invoice, apart from item discounts.

item_discounts?number

The sum of all item discounts.

total_discounts?number

discount plus item_discounts.

total_discounts_percent?number

The total discount as a fraction of the original total.

tax?number

Tax after discounts.

tax_original?number

Tax before discounts.

total?number

The amount the customer pays.

total_original?number

subtotal_original plus shipping_original plus tax_original.

tax_inclusive?boolean

True when item prices already include tax.

total_payments?number

The amount paid so far.

total_remaining?number

total minus total_payments: what is still to pay.

discount_on_gross?boolean

True when discounts are taken from the tax-inclusive price.

autopay?boolean

True when the invoice is to be charged automatically to the customer's saved payment method on the due date, once it is published.

for_subscription_proration?boolean

True when Comecero made this invoice for a mid-term subscription change.

autopay_at?|

When the automatic payment will run. Null when the invoice is not scheduled for automatic payment.

Formatdate-time
settlement_currency?string

The currency you are paid out in. This and the other settlement_ fields are not returned to limited tokens.

settlement_subtotal?number

subtotal in the settlement currency.

settlement_subtotal_original?number

subtotal_original in the settlement currency.

settlement_shipping?number

shipping in the settlement currency.

settlement_shipping_original?number

shipping_original in the settlement currency.

settlement_discount?number

discount in the settlement currency.

settlement_item_discounts?number

item_discounts in the settlement currency.

settlement_total_discounts?number

total_discounts in the settlement currency.

settlement_tax?number

tax in the settlement currency.

settlement_tax_original?number

tax_original in the settlement currency.

settlement_total?number

total in the settlement currency.

customer_ip_address?|

The customer's IP address, when known.

customer_ip_country?|

The country of customer_ip_address, a two-letter ISO 3166 code.

referrer?|

Where the sale came from, as you set it.

affiliate_id?|

The affiliate credited with the sale, as you set it.

promotion_code?|

The coupon code applied to the invoice.

items_count?integer

The number of items.

items_quantity?number

The sum of the item quantities.

draft?boolean

True while the invoice is a draft. A draft cannot be paid and limited tokens cannot see it. Once published, an invoice cannot go back to draft.

items?array<>

The items on the invoice.

shipping_item?|

The shipping line, or null when the invoice has no shipping.

customer?|

The customer the invoice is for, or null when none is set yet. Before an invoice is published, the customer must have every field your payment settings require.

order?||

Once the invoice is closed and paid, a link to its order, or the order itself when you expand order. Null while the invoice is open. Left out when the token may not read orders.

payments?|

A link to the invoice's payments, or the list of payments when you expand payments on a single invoice. Left out when the token may not read payments.

subscription?||

For a subscription renewal invoice, a link to the subscription, or the subscription itself when you expand subscription. Null otherwise. Left out when the token may not read subscriptions.

subscription_date_period_start?|

For a renewal invoice, the start of the billing period it covers. Left out when the token may not read subscriptions.

Formatdate-time
subscription_date_period_end?|

For a renewal invoice, the end of the billing period it covers. Left out when the token may not read subscriptions.

Formatdate-time
promotions?|

A link to the promotions applied to the invoice, or the list when you expand promotions on a single invoice.

options?|

A link to the payment options for the invoice, or the options themselves when you expand options on a single invoice.

meta?|

Your own data for this invoice, up to 2,048 characters as JSON.

formatted?

Only when you send formatted=true. The money and date fields above as display text in the customer's language.

Example Request
curl -X GET 'https://api.comecero.com/api/v1/invoices/string'
Example Response
{  "object": "invoice",  "url": "https://api.comecero.com/api/v1/invoices/4827-KTPMW-639",  "date_created": "2026-11-02T15:04:11Z",  "date_modified": "2026-11-02T15:10:42Z",  "date_due": "2026-11-30T00:00:00Z",  "past_due": false,  "invoice_id": "4827-KTPMW-639",  "test": true,  "account_id": "AB1234",  "order_id": "4827-KTPMW-639",  "open": true,  "payment_status": "unpaid",  "currency": "USD",  "subtotal": 950,  "subtotal_original": 950,  "shipping": 0,  "shipping_original": 0,  "discount": 0,  "item_discounts": 0,  "total_discounts": 0,  "total_discounts_percent": 0,  "tax": 0,  "tax_original": 0,  "total": 950,  "total_original": 950,  "tax_inclusive": false,  "total_payments": 0,  "total_remaining": 950,  "discount_on_gross": false,  "autopay": false,  "for_subscription_proration": false,  "autopay_at": null,  "settlement_currency": "USD",  "settlement_subtotal": 950,  "settlement_subtotal_original": 950,  "settlement_shipping": 0,  "settlement_shipping_original": 0,  "settlement_discount": 0,  "settlement_item_discounts": 0,  "settlement_total_discounts": 0,  "settlement_tax": 0,  "settlement_tax_original": 0,  "settlement_total": 950,  "customer_ip_address": null,  "customer_ip_country": null,  "referrer": null,  "affiliate_id": null,  "promotion_code": null,  "items_count": 1,  "items_quantity": 10,  "draft": false,  "items": [    {      "object": "invoice_item",      "url": "https://api.comecero.com/api/v1/invoices/4827-KTPMW-639/items/1",      "item_id": "1",      "invoice_id": "4827-KTPMW-639",      "cross_sell_id": null,      "up_sell_id": null,      "bundle_id": null,      "bundle_group_id": null,      "date_created": "2026-11-02T15:04:11Z",      "date_modified": "2026-11-02T15:04:11Z",      "product_id": null,      "name": "Website setup, 10 hours",      "type": "service",      "quantity": 10,      "currency": "USD",      "price": 95,      "price_original": 95,      "reference_price": 95,      "reference_currency": "USD",      "subtotal": 950,      "subtotal_original": 950,      "discount": 0,      "discount_percent": 0,      "tax": 0,      "tax_original": 0,      "total": 950,      "total_original": 950,      "tax_rate": 0,      "tax_code": null,      "product": null,      "subscription_plan": null,      "subscription_terms": null,      "meta": null    }  ],  "shipping_item": null,  "customer": {    "object": "customer",    "url": "https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3",    "customer_id": "0091304300408CuoxY9Pf3",    "date_created": "2026-11-02T18:18:20Z",    "date_modified": "2026-11-02T18:18:20Z",    "account_id": "AB1234",    "test": true,    "company_name": null,    "name": "John Doe",    "email": "john@example.com",    "phone": "555-555-0123",    "billing_address": {      "object": "address",      "name": "John Doe",      "address_1": "100 Main Street",      "address_2": null,      "city": "Springfield",      "state_prov": "IL",      "postal_code": "62701",      "country": "US",      "email": "john@example.com",      "meta": null    },    "shipping_address": {      "object": "address",      "name": null,      "address_1": null,      "address_2": null,      "city": null,      "state_prov": null,      "postal_code": null,      "country": null,      "email": null,      "meta": null    },    "username": "johndoe",    "tax_number": null,    "tax_exempt": false,    "has_payments": true,    "locale": "en-US",    "meta": null,    "payment_methods": "https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/payment_methods",    "payments": "https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/payments",    "refunds": "https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/refunds",    "orders": "https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/orders",    "subscriptions": "https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/subscriptions",    "invoices": "https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/invoices",    "balance": "https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/balance"  },  "order": null,  "payments": "https://api.comecero.com/api/v1/invoices/4827-KTPMW-639/payments",  "subscription": null,  "subscription_date_period_start": null,  "subscription_date_period_end": null,  "promotions": "https://api.comecero.com/api/v1/invoices/4827-KTPMW-639/promotions",  "options": "https://api.comecero.com/api/v1/invoices/4827-KTPMW-639/options",  "meta": {    "project": "Q4-site"  }}

Create an invoice POST

Creates an invoice. It is a draft unless you send `draft: false`. A draft can be changed freely and cannot be paid or seen by limited tokens. Creating fires `invoice:created`. Creating with `draft: false` also publishes it: `invoice:published` fires and the customer is emailed a payment link, unless you send `suppress_customer_notification: true` or have no notification subscription for invoice links. If you send `autopay: true` with a published invoice, Comecero charges the customer's saved payment method on the due date. Items can be catalog products or custom items (a name, a type and a price). Takes a secret or trusted token. Limited tokens cannot create invoices.

Update an invoice POST

Changes an open invoice. Only the fields you send change, except `items`, which replaces every item. You cannot change an invoice once a payment that has not failed is applied to it, or once it is closed. Sending `draft: false` on a draft publishes it: `invoice:published` fires and the customer is emailed a payment link, unless you send `suppress_customer_notification: true`. A published invoice cannot go back to draft, and its customer cannot change. Takes a secret, trusted or limited token. A limited token must be bound to the invoice and may only change `currency`; Comecero ignores every other field it sends.