comecerodocs
Orders

Capture an order

POST
/orders/{order_id}/capture

Captures the money that was only authorized on the order's pending payments. Money moves. To capture all of it, send no body at all: a JSON body without total, items or shipping (even {}) captures nothing and releases the rest. To capture part, send a total, or items and shipping. The part you do not capture is written down as a record-only refund (no money moves for it), so the order shows what was really charged. When the order has more than one pending payment, the largest is captured first and any payment left over once the amount is reached is voided.

Returns 201 with a payment_list holding each payment and its result. When every capture fails, the API answers with an error instead and puts the payment_list in the error's meta.payment_list.

Needs a secret or trusted token that may create or update payments. A token without that permission gets 401, not 403.

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Path Parameters

order_id*string

The order 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.

Request Body

Optional. Leave it out (no body, not {}) to capture everything authorized.

application/json
  1. body

What to capture. Send no body to capture everything that is authorized. Send either total, or items and/or shipping; never subtotal or tax, which are worked out for you. Whatever you do not capture is recorded as a refund (no money moves for it) so the order shows what was really charged.

total?number

The amount to capture, in the order currency. Cannot be more than the order total. Cannot be sent with items or shipping.

Range0 < value
items?array<>

The items to capture, each by item_id and quantity. Items you leave out, and any quantity you do not list, are not captured. Each item_id may appear once.

Items1 <= items
shipping?number

The shipping amount to capture, with tax, in the order currency. When you leave it out of a request that has items, no shipping is captured.

Response Body

The capture was made for at least one payment.

application/json
  1. response

The result of capturing or voiding an order: every payment the request acted on, with its own result. An order can have more than one payment, so some can succeed while others fail.

object*"payment_list"

The object type. Always payment_list.

Value in"payment_list"
url*string

The URL of this result.

Formaturi
payment_list_id*string

The id of this result.

test*boolean

True for test payments.

account_id*|

The account the payments belong to.

currency*|

The currency of the payments.

subtotal*number

The subtotal of the payments that are now completed or pending, in currency.

shipping*number

The shipping of the payments that are now completed or pending, in currency.

tax*number

The tax of the payments that are now completed or pending, in currency.

total*number

The total of the payments that are now completed or pending, in currency.

success_count*integer

How many payments succeeded.

failure_count*integer

How many payments failed.

payments*array<>

The payments, each with its new status.

curl -X POST 'https://api.comecero.com/api/v1/orders/string/capture' \  -H 'Content-Type: application/json' \  -d '{  "items": [    {      "item_id": "1",      "quantity": 1    }  ],  "shipping": 5}'
Example Response
{  "object": "payment_list",  "url": "https://api.comecero.com/api/v1/payment_list/0093718312045PlK3dVb7q",  "payment_list_id": "0093718312045PlK3dVb7q",  "test": true,  "account_id": "AB1234",  "currency": "USD",  "subtotal": 199.9,  "shipping": 0,  "tax": 14.99,  "total": 214.89,  "success_count": 1,  "failure_count": 0,  "payments": [    {      "object": "payment",      "url": "https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC",      "payment_id": "0090460891496PyrYzd9DC",      "account_id": "AB1234",      "success": true,      "status": "completed",      "date_created": "2026-11-07T19:25:02Z",      "date_modified": "2026-11-07T19:25:04Z",      "date_completed": "2026-11-07T19:25:04Z",      "test": true,      "currency": "USD",      "subtotal": 199.9,      "shipping": 0,      "tax": 14.99,      "total": 214.89,      "customer_ip_address": "203.0.113.44",      "customer_ip_country": "US",      "description": null,      "reference": null,      "merchant_descriptor": "EXAMPLE SHOP",      "merchant_contact": "shop.example.com",      "apply_to_balance": false,      "response_code": "OK",      "response_message": "OK",      "gateway_transaction_id": "test_ch_1029384756",      "gateway_error_code": null,      "gateway_error_message": null,      "risk_decline": false,      "gateway": "https://api.comecero.com/api/v1/gateways/0090100200300GwTest01",      "app_id": null,      "app_version": null,      "payment_method": "https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC/payment_method",      "response_data": "https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC/response_data",      "reporting_currency": "USD",      "reporting_subtotal": 199.9,      "reporting_shipping": 0,      "reporting_tax": 14.99,      "reporting_total": 214.89,      "reporting_fx_rate": 1,      "settlement_currency": "USD",      "settlement_subtotal": 199.9,      "settlement_shipping": 0,      "settlement_tax": 14.99,      "settlement_total": 214.89,      "fx_rate": 1,      "customer": "https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1",      "order": "https://api.comecero.com/api/v1/orders/8352-CSGYX-348",      "cart": "https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1",      "invoice": null,      "refunds": "https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC/refunds",      "fees": "https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC/fees",      "fee_summary": "https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC/fee_summary",      "commissions": "https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC/commissions",      "failed_gateway_attempts": "https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC/failed_gateway_attempts",      "meta": null    }  ]}

Get an order GET

Returns one order with its items. **PDF:** send `Accept: application/pdf` to get the order as a PDF receipt instead of JSON. The PDF uses your account's order template in the customer's language and comes back as a file named `<order_id>.pdf`. Secret and trusted tokens can read any order on the account. A limited token can read an order only when it belongs to the token's customer, and the settlement amounts and some item fields are left out for it.

Get an order's fee summary GET

Returns the Comecero fees on the order: the fees of all its payments and their refunds, added up per currency. Needs a secret or trusted token that may read fees. Limited tokens are refused. A token without the fees permission gets `401`, not `403`.