Create an invoice from an item
Use a catalog item and preserve its price and details for the invoice.
/api/invoices/from-itemCreate an invoice from an immutable catalog-item snapshot. Requires merchant-id and signature headers.
| Field | Type | Required | Description |
|---|---|---|---|
fee_payer | string | No | |
original_price | string | No | |
discount | object | No | |
currency | string | No | Optional item-currency override. Omission uses the item currency. |
amount | string | No | Base price override for ONE unit before any invoice discount. Omission uses the saved item price. The discount applies once to unit amount multiplied by quantity; the catalog item is unchanged. |
network | string | No | Optional network constraint for a crypto-priced invoice. Does not select a method for a fiat-priced invoice. |
order_id | string | No | Stable order reference. Retry the original unit amount, quantity and pricing fields unchanged to retrieve the saved item, discount and fee snapshot. Changed conditions return 409 ORDER_ID_ALREADY_EXISTS. |
expires_at | string | No | For a new invoice, a future ISO timestamp no more than 60 minutes ahead. Omission defaults to 30 minutes. Existing reservations and identical retries retain their original deadline. |
webhook_url | string | No | Public HTTPS receiver. Pass explicitly for invoice events; merchant settings are not inherited. |
success_url | string | null | No | Omission inherits the item URL. Null removes that URL, but merchant-level checkout redirect may still apply. |
metadata | object | No | Optional JSON object. Not echoed by create, public read, or webhook payload. |
item_id | string | Yes | An owned, non-archived catalog item. |
quantity | integer | No | Number of units. Base subtotal is unit amount multiplied by quantity, before applying one invoice-level discount. |
Source: download OpenAPI 3.1. Examples below use illustrative values.
Example request
{
"item_id": "11111111-1111-4111-8111-111111111111",
"quantity": 4,
"amount": "25",
"currency": "USD",
"fee_payer": "CUSTOMER",
"discount": { "type": "PERCENT", "value": "20" },
"order_id": "order-1002",
"webhook_url": "https://shop.example/webhooks/cryptiumpay"
}Pricing and snapshot
quantity defaults to 1. The optional amount overrides the unit price; the base invoice subtotal is unit price multiplied by quantity. Currency can be overridden independently. Both unit and subtotal must satisfy the decimal limits. These overrides do not change the catalog item.
The same pricing rules apply to simple and catalog invoices. A discount applies once to the complete subtotal, rather than separately to each unit. Optional original_price refers to that subtotal: with a discount it must equal the undiscounted subtotal; without a discount it must be at least the goods subtotal. All prices and discount values remain decimal strings.
For the example request, "25" × 4 gives a base subtotal of "100". The server applies 20% off once, returning goods amount: "80" and original_price: "100". At a service fee of 150 basis points, CUSTOMER produces fee.amount: "1.2" and total_amount: "81.2". With the default MERCHANT payer, the customer total is "80" and the fee is deducted from the merchant's proceeds.
The response is the creation summary plus an immutable item snapshot:
{
"item_id": "11111111-1111-4111-8111-111111111111",
"name": "Example item",
"description": null,
"icon_url": null,
"success_url": null,
"quantity": 4,
"unit_amount": "25",
"currency": "USD",
"total_amount": "100"
}The nested item.total_amount preserves the base subtotal before invoice-level discounts and service fees. The top-level response amount is the discounted goods price; top-level total_amount is what the customer pays. The item snapshot, discount result and service-fee terms remain immutable for that invoice.
description is taken from the item; it is not an accepted request override. Omitted success_url inherits the item URL. Explicit null removes that item URL, but a merchant-level checkout return URL can still apply.
Changes and retries
The first request requires an owned, non-archived item. Later catalog edits do not alter its invoice snapshot. An identical retry with the same order_id retrieves the original conditions without adopting a newer price.
A missing or foreign item returns 404 ITEM_NOT_FOUND; an archived item used for a new invoice returns 409 ITEM_ARCHIVED. Changed request conditions for an existing order return 409 ORDER_ID_ALREADY_EXISTS.
Retry the original unit amount, quantity, payer, original price and discount parameters unchanged, including after a lost response. An identical retry returns the saved pricing snapshot and does not adopt later catalog prices or fee rates. Do not replace the original unit amount with the discounted invoice total on retry.
New catalog invoices use the same expiry rule: 30 minutes by default, at most 60 minutes for an explicit future expires_at. An identical retry keeps its originally reserved deadline.