Create an invoice
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.
AuthorizationBearer <token>A secret, trusted or limited token. See Authentication.
expand?stringComma-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?stringComma-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?stringComma-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?booleanWhen 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.
falsetimezone?stringAn 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.
user_ip_address?stringThe shopper's IP address, when your server calls with a secret token on the shopper's behalf. Comecero uses it for fraud checks and to find the shopper's country. Only read for a secret token: for every other token the address the request comes from is used. A value that is not a valid IPv4 or IPv6 address is ignored.
application/json- body
The fields of an invoice you can set. No field is required to create a draft. To publish (draft: false) the invoice needs a date_due, at least one item, and a customer with every field your payment settings require. On update, only the fields you send change. A limited token may only change currency: everything else it sends is ignored.
invoice_id?stringYour own id for the invoice, on create only. Letters, numbers, underscores, dashes and periods; stored in upper case. It must not be in use by another invoice or order, because the paid invoice becomes an order with this id. If you leave it out, Comecero assigns one. On update it must match the id in the URL.
length <= 30currency?stringThe currency the customer pays in, a three-letter ISO 4217 code that your account accepts. If you leave it out on create, Comecero picks one from the customer's location.
date_due?|When payment is due, as an ISO 8601 date or date and time (for example 2026-11-30). On create it cannot be in the past. You cannot change it on a subscription renewal invoice.
draft?booleanSend false to publish the invoice. New invoices are drafts unless you send false. Publishing fires invoice:published and emails the customer a payment link. Once published, an invoice cannot go back to draft.
truesuppress_customer_notification?booleanSend true with draft: false to publish without emailing the customer. Use it when you send the link yourself (see Create a payment link).
falseautopay?booleanSend true to charge the customer's saved payment method automatically on the due date, once the invoice is published. The customer must have a payment method on file. The invoice's payment_status becomes scheduled.
customer_id?|The id of an existing customer. Send either this or customer, not both. After an invoice is published you cannot change its customer.
customer?A new customer, or changes to an existing one (include its customer_id). Send either this or customer_id, not both.
items?array<>The items. On update, sending items replaces every item on the invoice. Use the item endpoints to change one item. The same product_id or item_id may not appear twice.
promotion_code?|A coupon code to apply. It must be valid for the customer.
shipping_method_id?|The shipping method for physical items. It must exist and ship to the customer's country.
referrer?|Where the sale came from, for your reports.
affiliate_id?|The affiliate to credit with the sale.
meta?|Your own data, up to 2,048 characters as JSON.
The new invoice.
application/json- 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.
"invoice"url?stringThe full URL of this invoice.
uridate_created?stringWhen the invoice was created.
date-timedate_modified?stringWhen the invoice was last changed.
date-timedate_due?|When payment is due. Required before the invoice can be published.
date-timepast_due?booleanTrue when date_due has passed and the invoice is still unpaid, scheduled, pending, failed or waiting for a retry.
invoice_id?stringThe invoice id. It is also the order_id of the order the invoice becomes when paid.
test?booleanTrue for a test invoice.
account_id?stringThe account the invoice belongs to.
order_id?stringThe id the order will have once the invoice is paid. Same as invoice_id.
open?booleanTrue while the invoice can still be changed or paid. It turns false when the invoice is paid in full.
payment_status?stringWhere 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.
"unpaid""scheduled""processing""pending""completed""failed""retry""cancelled""refunded"currency?stringThe currency the customer pays in, a three-letter ISO 4217 code.
subtotal?numberThe sum of the item subtotals after item discounts.
subtotal_original?numberThe sum of the item subtotals before discounts.
shipping?numberShipping after discounts.
shipping_original?numberShipping before discounts.
discount?numberThe discount on the whole invoice, apart from item discounts.
item_discounts?numberThe sum of all item discounts.
total_discounts?numberdiscount plus item_discounts.
total_discounts_percent?numberThe total discount as a fraction of the original total.
tax?numberTax after discounts.
tax_original?numberTax before discounts.
total?numberThe amount the customer pays.
total_original?numbersubtotal_original plus shipping_original plus tax_original.
tax_inclusive?booleanTrue when item prices already include tax.
total_payments?numberThe amount paid so far.
total_remaining?numbertotal minus total_payments: what is still to pay.
discount_on_gross?booleanTrue when discounts are taken from the tax-inclusive price.
autopay?booleanTrue 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?booleanTrue 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.
date-timesettlement_currency?stringThe currency you are paid out in. This and the other settlement_ fields are not returned to limited tokens.
settlement_subtotal?numbersubtotal in the settlement currency.
settlement_subtotal_original?numbersubtotal_original in the settlement currency.
settlement_shipping?numbershipping in the settlement currency.
settlement_shipping_original?numbershipping_original in the settlement currency.
settlement_discount?numberdiscount in the settlement currency.
settlement_item_discounts?numberitem_discounts in the settlement currency.
settlement_total_discounts?numbertotal_discounts in the settlement currency.
settlement_tax?numbertax in the settlement currency.
settlement_tax_original?numbertax_original in the settlement currency.
settlement_total?numbertotal 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?integerThe number of items.
items_quantity?numberThe sum of the item quantities.
draft?booleanTrue 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.
date-timesubscription_date_period_end?|For a renewal invoice, the end of the billing period it covers. Left out when the token may not read subscriptions.
date-timepromotions?|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.
curl -X POST 'https://api.comecero.com/api/v1/invoices' \ -H 'Content-Type: application/json' \ -d '{ "currency": "USD", "customer": { "name": "John Doe", "email": "john@example.com" }, "items": [ { "name": "Consulting, 2 hours", "type": "service", "quantity": 2, "reference_price": 120 } ]}'{ "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" }}List invoices GET
Returns the invoices on your account, oldest first by `date_created` unless you change `date_type` or send `desc=true`. The list is cursor-based: page with `after_item` and `before_item`. Use `q` to search by invoice id, customer name, company name or exact customer email. Takes a secret or trusted token. Limited tokens cannot list invoices.
Get an invoice GET
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.