{"openapi":"3.1.0","info":{"title":"Comecero API","version":"1.0","description":"The REST API behind every Comecero shop. All requests go to `https://api.comecero.com/api/v1` over HTTPS with a token in the `Authorization: Bearer` header. Test and live data are kept apart by the token you use.","contact":{"name":"Comecero Support","url":"https://comecero.com/contact"}},"servers":[{"url":"https://api.comecero.com/api/v1","description":"Production (test or live is set by the token)"}],"security":[{"bearer":[]},{"oauth":[]}],"tags":[{"name":"products","x-displayName":"Products","description":"What you sell: one-time items, subscriptions, downloads and license keys, with prices per currency."},{"name":"subscription_plans","x-displayName":"Subscription plans","description":"The billing rules a subscription product follows: interval, trial, number of renewals."},{"name":"promotions","x-displayName":"Promotions","description":"Coupon codes and automatic discounts."},{"name":"shipping_methods","x-displayName":"Shipping methods","description":"The shipping options a shopper can pick, and how each is priced."},{"name":"license_services","x-displayName":"License services","description":"Where license keys come from: a stored list or your own key server."},{"name":"carts","x-displayName":"Carts","description":"A shopper's basket. Add items, set the customer, then take a payment on the cart to create an order."},{"name":"payments","x-displayName":"Payments","description":"Money taken from a customer, with capture, void and refund."},{"name":"invoices","x-displayName":"Invoices","description":"A bill you send to a customer, paid by card on a hosted page or through the API."},{"name":"orders","x-displayName":"Orders","description":"What a paid cart or invoice becomes: the items, totals, shipments and refunds."},{"name":"refunds","x-displayName":"Refunds","description":"Money given back on a payment, in full or in part."},{"name":"subscriptions","x-displayName":"Subscriptions","description":"Recurring billing for a customer: renew, change items, cancel, extend."},{"name":"shipments","x-displayName":"Shipments","description":"Physical delivery of order items, with carrier and tracking."},{"name":"licenses","x-displayName":"Licenses","description":"License keys given to customers on their orders."},{"name":"license_requests","x-displayName":"License requests","description":"Calls Comecero made to your license key server, and their results."},{"name":"downloads","x-displayName":"Downloads","description":"Digital files a customer may download from an order."},{"name":"customers","x-displayName":"Customers","description":"The people who buy: contact details, saved payment methods, store credit and history."},{"name":"event_subscriptions","x-displayName":"Webhooks","description":"Endpoints on your server that receive events (order created, payment completed and more)."},{"name":"events","x-displayName":"Events","description":"Every event Comecero sent to your webhooks, with its delivery status. Retry from here."},{"name":"notification_subscriptions","x-displayName":"Notification subscriptions","description":"Which emails go out, and to whom."},{"name":"notifications","x-displayName":"Notifications","description":"Emails Comecero sent (receipts, invoices, renewal notices), with resend."},{"name":"templates","x-displayName":"Templates","description":"The content of the emails and documents Comecero sends."},{"name":"files","x-displayName":"Files","description":"Files you upload, such as downloads you sell."},{"name":"images","x-displayName":"Images","description":"Product and shop images."},{"name":"reports","x-displayName":"Reports","description":"Sales, items, tax, fees and commission totals for a date range."},{"name":"fees","x-displayName":"Fees","description":"Fees charged on payments and refunds."},{"name":"commissions","x-displayName":"Commissions","description":"What Comecero owes you for sales taken on a Comecero gateway, per payment and refund."},{"name":"foreign_exchange","x-displayName":"Currency conversion","description":"Convert prices and amounts between currencies at today's rate."},{"name":"accounts","x-displayName":"Account","description":"Your Comecero account: company details, mode and status."},{"name":"auths","x-displayName":"Tokens","description":"API tokens: secret (server), trusted and limited (browser)."},{"name":"users","x-displayName":"Users","description":"People who can sign in to your dashboard."},{"name":"roles","x-displayName":"Roles","description":"What a user may see and do."},{"name":"gateways","x-displayName":"Gateways","description":"The payment processors connected to your account."},{"name":"settings","x-displayName":"Settings","description":"Account settings: general, payment, tax, shipping, subscription, analytics and more."},{"name":"countries","x-displayName":"Countries and currencies","description":"The countries and currencies Comecero supports, with the details forms need."}],"paths":{"/accounts":{"get":{"summary":"List accounts","operationId":"list_accounts","description":"Lists every Comecero account. This is for Comecero platform staff only: any other token, including your secret token, gets `403`. To read your own account, call `GET /accounts/me`.\n\nThe list is cursor-based. Page with `after_item` and `before_item`.","tags":["accounts"],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/after_item"},{"$ref":"#/components/parameters/before_item"},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/date_start"},{"$ref":"#/components/parameters/date_end"},{"$ref":"#/components/parameters/date_type"},{"name":"q","in":"query","description":"Finds accounts by ID, name, email or exact alias.","required":false,"schema":{"type":"string"}},{"name":"live","in":"query","description":"`true` for live accounts only, `false` for accounts not yet live.","required":false,"schema":{"type":"boolean"}},{"name":"closed","in":"query","description":"`true` for closed accounts only, `false` for open ones only.","required":false,"schema":{"type":"boolean"}},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/timezone"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A cursor-based list of accounts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/account_list"},"example":{"next_page_url":null,"next_page_after_item":null,"previous_page_url":null,"previous_page_before_item":null,"current_page_url":"https://api.comecero.com/api/v1/accounts?limit=10","data":[{"object":"account","url":"https://api.comecero.com/api/v1/accounts/AB1234","account_id":"AB1234","alias":"example-shop","date_created":"2026-03-01T14:36:52Z","date_modified":"2026-10-01T09:20:11Z","company_name":"Example Software Ltd","dba":"Example Software","name":"John Doe","email":"john@example.com","website":"https://www.example.com","phone":"+1 555 0100","tax_number":null,"registration_number":null,"logo_url":"https://www.example.com/logo.png","address_1":"100 Main Street","address_2":null,"city":"Springfield","state_prov":"IL","postal_code":"62701","country":"US","support_email":"support@example.com","support_website":"https://www.example.com/support","live":true,"closed":false,"date_closed":null,"account_meta":"https://api.comecero.com/api/v1/accounts/AB1234/account_meta"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Sign up for an account","operationId":"create_account","description":"Creates a new Comecero account with its first user, who becomes the account owner. This is how someone signs up, so it needs no token. The response has a live trusted `token` for the owner, so they are signed in at once.\n\nThe new account is not live: it can take test payments right away, and Comecero sets `live` once the account is approved. Default settings, a test gateway and a shipping method for the account's country are created with it.","tags":["accounts"],"security":[{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/account_create_request"},"examples":{"minimal":{"summary":"Required fields only","value":{"name":"John Doe","email":"john@example.com","user_id":"john.doe","password":"correct-horse-battery"}},"full":{"summary":"With company details","value":{"name":"John Doe","email":"john@example.com","user_id":"john.doe","password":"correct-horse-battery","company_name":"Example Software Ltd","website":"www.example.com","country":"US"}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new account, with a trusted `token` for its owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/account"},"example":{"object":"account","url":"https://api.comecero.com/api/v1/accounts/AB1234","account_id":"AB1234","alias":"example-software-ltd","date_created":"2026-11-07T14:36:52Z","date_modified":"2026-11-07T14:36:52Z","company_name":"Example Software Ltd","dba":"Example Software Ltd","name":"John Doe","email":"john@example.com","website":"https://www.example.com","phone":null,"tax_number":null,"registration_number":null,"logo_url":null,"address_1":null,"address_2":null,"city":null,"state_prov":null,"postal_code":null,"country":"US","support_email":null,"support_website":"https://www.example.com","live":false,"closed":false,"date_closed":null,"token":"trusted.live.Ty5Qm8Rk2Lp9Wv3Xz7Bn4Cd1Fg6Hj0Sa8Ue2Io5Kl3Mq.1793887012.8c2f5a7b1d","account_meta":"https://api.comecero.com/api/v1/accounts/AB1234/account_meta"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/accounts/{account_id}":{"parameters":[{"name":"account_id","in":"path","description":"Your account ID, or `me` for the account of the token you call with.","required":true,"schema":{"type":"string"},"example":"me"}],"get":{"summary":"Get your account","operationId":"get_account","description":"Gets your account. Use `me` so you do not need to know the account ID. You can only read the account your token belongs to (`403` for any other).\n\nThe account is not split by mode, so this needs a live token. A test token gets `400` with the code `token_type_mismatch`.\n\nLive secret and trusted tokens may call this with the `accounts` read permission.","tags":["accounts"],"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/timezone"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/account"},"example":{"object":"account","url":"https://api.comecero.com/api/v1/accounts/AB1234","account_id":"AB1234","alias":"example-shop","date_created":"2026-03-01T14:36:52Z","date_modified":"2026-10-01T09:20:11Z","company_name":"Example Software Ltd","dba":"Example Software","name":"John Doe","email":"john@example.com","website":"https://www.example.com","phone":"+1 555 0100","tax_number":null,"registration_number":null,"logo_url":"https://www.example.com/logo.png","address_1":"100 Main Street","address_2":null,"city":"Springfield","state_prov":"IL","postal_code":"62701","country":"US","support_email":"support@example.com","support_website":"https://www.example.com/support","live":true,"closed":false,"date_closed":null,"account_meta":"https://api.comecero.com/api/v1/accounts/AB1234/account_meta"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Update your account","operationId":"update_account","description":"Changes your company and contact details or your alias. Only the fields you send change. `live` and `closed` are set by Comecero and are ignored here. Fires the `account:modified` event.\n\nThis needs a live token: a test token gets `400` with the code `token_type_mismatch`. Live secret and trusted tokens may call this with the `accounts` update permission.","tags":["accounts"],"parameters":[{"$ref":"#/components/parameters/expand"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/account_request"},"examples":{"support":{"summary":"Set the support email and tax number","value":{"support_email":"help@example.com","tax_number":"GB123456789"}},"address":{"summary":"Change the business address","value":{"company_name":"Example Software Ltd","address_1":"1 Main St","city":"High Point","state_prov":"NC","postal_code":"27265","country":"US"}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The updated account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/account"},"example":{"object":"account","url":"https://api.comecero.com/api/v1/accounts/AB1234","account_id":"AB1234","alias":"example-shop","date_created":"2026-03-01T14:36:52Z","date_modified":"2026-10-01T09:20:11Z","company_name":"Example Software Ltd","dba":"Example Software","name":"John Doe","email":"john@example.com","website":"https://www.example.com","phone":"+1 555 0100","tax_number":null,"registration_number":null,"logo_url":"https://www.example.com/logo.png","address_1":"100 Main Street","address_2":null,"city":"Springfield","state_prov":"IL","postal_code":"62701","country":"US","support_email":"support@example.com","support_website":"https://www.example.com/support","live":true,"closed":false,"date_closed":null,"account_meta":"https://api.comecero.com/api/v1/accounts/AB1234/account_meta"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/auths":{"get":{"summary":"List tokens","operationId":"list_auths","description":"Lists the tokens of your account in the mode of the token you call with: a test token lists test tokens, a live token lists live tokens. The list is offset-based. Each token shows a masked `token`, never the full value.\n\nTo find one token, send the full token in `q`. You get that token, or an empty list.\n\nSecret and trusted tokens may call this with the `auths` read permission.","tags":["auths"],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"name":"sort_by","in":"query","description":"The field to sort by. The default is `date_created`.","required":false,"schema":{"type":"string","enum":["date_created","date_modified","auth_id"],"default":"date_created"}},{"$ref":"#/components/parameters/desc"},{"name":"q","in":"query","description":"A full token. Returns only that token.","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/timezone"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"An offset-based list of tokens.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/auth_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/auths","data":[{"object":"auth","url":"https://api.comecero.com/api/v1/auths/9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","auth_id":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","test":true,"account_id":"AB1234","account_alias":"example-shop","type":"secret","ip_address":null,"token":"secret.test.Hq7...4c1e","expires":null,"expires_in_seconds":null,"date_last_used":"2026-11-06T00:00:00Z","comments":"Order sync server","date_created":"2026-10-01T14:36:52Z","date_modified":"2026-10-01T14:36:52Z","roles":[],"permissions":[{"resource":"orders","methods":["read"],"allow":true}],"effective_permissions":{"orders":{"create":false,"read":true,"update":false,"delete":false}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/auths/limited":{"post":{"summary":"Create a limited token","operationId":"create_limited_auth","description":"Creates a limited token for a shopper's browser. A limited token works like a session: it can read your public catalog, and it can change only the carts, payments and other objects it created itself.\n\nCall it without an `Authorization` header from the browser, with your `account_id` in the query string (`400` without it). The new token is live. To get a test token this way, add `test=true`. That works only when your account allows limited test tokens without a token (Settings, Technical, `allow_public_limited_test_tokens`); otherwise the answer is `403`.\n\nYour server may also call it with a secret or trusted token that may create tokens. Then `account_id` is optional (it must match the token, `400` otherwise), the new token takes the mode of your token unless you send `test`, and you may send a `customer_id` to make the token for one customer. A limited token in the header is refused (`403`): to get a new one, call without a header.\n\nA new limited token lasts two hours. Each use moves the expiry forward, and a token that keeps being used lasts longer: 12 hours for its first uses, 24 hours after 5 uses and 15 days after 10 uses.","tags":["auths"],"security":[{},{"bearer":[]}],"parameters":[{"name":"account_id","in":"query","description":"Your account ID. Required when you call without a token. With a token, it must match the token's account.","required":false,"schema":{"type":"string"},"example":"AB1234"},{"name":"test","in":"query","description":"`true` for a test token, `false` for a live one. Without a token the default is live. With a token the default is your token's mode.","required":false,"schema":{"type":"boolean"}},{"name":"browser_info","in":"query","description":"When `true`, the response also has `browser_info`.","required":false,"schema":{"type":"boolean","default":false}},{"$ref":"#/components/parameters/user_ip_address"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/auth_limited_request"},"examples":{"customer":{"summary":"Limited token for one customer (server call)","value":{"customer_id":"0106784119870CueWmZ9P7"}},"anonymous":{"summary":"Limited token for a new shopper","value":{}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new limited token, with the full `token` value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/auth"},"example":{"object":"auth","url":"https://api.comecero.com/api/v1/auths/fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9","auth_id":"fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9","test":true,"account_id":"AB1234","account_alias":"example-shop","type":"limited","ip_address":"203.0.113.10","token":"limited.test.Pq3Wn7Rx1Ks5Lm9Vb2Zc8Fd4Gh6Jt0Ya3Ue7Io1Mk5Nq.1793887012.1a2b3c4d5e","expires":"2026-11-07T16:36:52Z","expires_in_seconds":7200,"date_last_used":null,"comments":null,"date_created":"2026-11-07T14:36:52Z","date_modified":"2026-11-07T14:36:52Z","roles":[],"permissions":[{"resource":"*","methods":["*"],"allow":true}],"effective_permissions":{"carts":{"create":true,"read":true,"update":true,"delete":true},"products":{"create":false,"read":true,"update":false,"delete":false}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/auths/options":{"get":{"summary":"List token permission options","operationId":"get_auth_options","description":"Lists the resources and methods a token of one type may be given. Use it to build a permissions form, or to check a request before you create a secret token. Send `type`: without it the list is empty.\n\nAny valid token may call this, including a limited token. No permission is needed.","tags":["auths"],"x-limited":true,"parameters":[{"name":"type","in":"query","description":"The token type to list the options for.","required":false,"schema":{"type":"string","enum":["secret","trusted","limited"]}},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The permissions the token type may be given.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/auth_options"},"example":{"account_id":"AB1234","test":true,"permissions":[{"resource":"carts","methods":["create","read","update","delete"]},{"resource":"products","methods":["read"]}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/auths/secret":{"post":{"summary":"Create a secret token","operationId":"create_secret_auth","description":"Creates a secret token for your server. The response is the only time you see the full token, so store it safely. Keep secret tokens on your server and never put one in a browser or an app.\n\nThe new token is live unless you send `test=true` in the query string. The mode of the token you call with does not decide it: a test token that leaves out `test=true` asks for a live token and gets `403`.\n\nGive the token only the permissions it needs. It needs at least one role or one permission, and the token you call with must hold every permission you ask for.\n\nSecret and trusted tokens may call this with the `auths` create permission.","tags":["auths"],"parameters":[{"name":"test","in":"query","description":"`true` makes a test token, `false` or no value makes a live token. Only a live token may create a live token.","required":false,"schema":{"type":"boolean","default":false}},{"name":"browser_info","in":"query","description":"When `true`, the response also has `browser_info`.","required":false,"schema":{"type":"boolean","default":false}},{"$ref":"#/components/parameters/timezone"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/auth_secret_request"},"examples":{"permissions":{"summary":"Read-only access to orders","value":{"comments":"Order sync server","permissions":[{"resource":"orders","methods":["read"],"allow":true}]}},"roles":{"summary":"Token with a role","value":{"comments":"Support desk","roles":["support"]}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new token, with the full `token` value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/auth"},"example":{"object":"auth","url":"https://api.comecero.com/api/v1/auths/9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","auth_id":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","test":true,"account_id":"AB1234","account_alias":"example-shop","type":"secret","ip_address":null,"token":"secret.test.Hq7Zp2LkQ8rT1vWm3XyB6nCd9FgJ0sAe5uIo4hKl7Ec.1793887012.4b9e2d1c4e","expires":null,"expires_in_seconds":null,"date_last_used":null,"comments":"Order sync server","date_created":"2026-11-07T14:36:52Z","date_modified":"2026-11-07T14:36:52Z","roles":[],"permissions":[{"resource":"orders","methods":["read"],"allow":true}],"effective_permissions":{"orders":{"create":false,"read":true,"update":false,"delete":false}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/auths/trusted":{"post":{"summary":"Create a test trusted token","operationId":"create_trusted_auth","description":"Swaps a live trusted token for a test trusted token with the same user and permissions. Use it when a signed-in user switches the dashboard or your own tool to test mode.\n\nYou cannot ask for any other kind of trusted token. Trusted tokens are given to users when they sign in, not created through the API. Send `test=true` in the query string (`400` without it) and no request body (`403` with one). The token you call with must be a live trusted token (`403` otherwise).\n\nThe new token lasts two hours from its last use.","tags":["auths"],"parameters":[{"name":"test","in":"query","description":"Must be `true`.","required":true,"schema":{"type":"boolean","enum":[true]}},{"name":"browser_info","in":"query","description":"When `true`, the response also has `browser_info`.","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new test trusted token, with the full `token` value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/auth"},"example":{"object":"auth","url":"https://api.comecero.com/api/v1/auths/2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae","auth_id":"2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae","test":true,"account_id":"AB1234","account_alias":"example-shop","type":"trusted","ip_address":"203.0.113.10","token":"trusted.test.Ty5Qm8Rk2Lp9Wv3Xz7Bn4Cd1Fg6Hj0Sa8Ue2Io5Kl3Mq.1793887012.8c2f5a7b1d","expires":"2026-11-07T16:36:52Z","expires_in_seconds":7200,"date_last_used":null,"comments":null,"date_created":"2026-11-07T14:36:52Z","date_modified":"2026-11-07T14:36:52Z","user":"https://api.comecero.com/api/v1/users/john.doe","roles":[],"permissions":[{"resource":"*","methods":["*"],"allow":true}],"effective_permissions":{"orders":{"create":true,"read":true,"update":true,"delete":true}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/auths/{auth_id}":{"parameters":[{"name":"auth_id","in":"path","description":"The token's `auth_id`, which is the SHA-256 hash of the full token in lower-case hex. Never put the full token in a URL. Use `me` for the token you call with.","required":true,"schema":{"type":"string"},"example":"me"}],"get":{"summary":"Get a token","operationId":"get_auth","description":"Gets one token by its `auth_id`. Use `me` to see the token you are calling with, for example to read its permissions or its expiry.\n\nAny token may read itself with `me`, including a limited token. To read another token you need a secret or trusted token with the `auths` read permission. A test token cannot read a live token (`404`).","tags":["auths"],"x-limited":true,"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/timezone"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The token, with a masked `token` value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/auth"},"example":{"object":"auth","url":"https://api.comecero.com/api/v1/auths/9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","auth_id":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","test":true,"account_id":"AB1234","account_alias":"example-shop","type":"secret","ip_address":null,"token":"secret.test.Hq7...4c1e","expires":null,"expires_in_seconds":null,"date_last_used":"2026-11-06T00:00:00Z","comments":"Order sync server","date_created":"2026-10-01T14:36:52Z","date_modified":"2026-10-01T14:36:52Z","roles":[],"permissions":[{"resource":"orders","methods":["read"],"allow":true}],"effective_permissions":{"orders":{"create":false,"read":true,"update":false,"delete":false}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Update a token","operationId":"update_auth","description":"Changes a secret token's label, expiry, roles or permissions. Only the fields you send change. Sending `roles` or `permissions` replaces that whole list. Trusted and limited tokens cannot be changed (`400`).\n\nThe token you call with must hold every permission the updated token will have (`403` otherwise), and only a live token may change a live token.\n\nSecret and trusted tokens may call this with the `auths` update permission. This is true for `me` too: a token may not widen its own permissions.","tags":["auths"],"parameters":[{"$ref":"#/components/parameters/timezone"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/auth_secret_request"},"example":{"comments":"Order sync server (read only)","expires":"2027-06-30T00:00:00Z"}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The updated token, with a masked `token` value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/auth"},"example":{"object":"auth","url":"https://api.comecero.com/api/v1/auths/9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","auth_id":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","test":true,"account_id":"AB1234","account_alias":"example-shop","type":"secret","ip_address":null,"token":"secret.test.Hq7...4c1e","expires":null,"expires_in_seconds":null,"date_last_used":"2026-11-06T00:00:00Z","comments":"Order sync server","date_created":"2026-10-01T14:36:52Z","date_modified":"2026-10-01T14:36:52Z","roles":[],"permissions":[{"resource":"orders","methods":["read"],"allow":true}],"effective_permissions":{"orders":{"create":false,"read":true,"update":false,"delete":false}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"summary":"Delete a token","operationId":"delete_auth","description":"Deletes a token so it stops working at once. Use `me` to sign out the token you call with, for example when a shopper logs out.\n\nAny token may delete itself with `me`, including a limited token. To delete another token you need a secret or trusted token with the `auths` delete permission.","tags":["auths"],"x-limited":true,"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The token is deleted. No body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/carts":{"get":{"summary":"List all carts","operationId":"list_carts","description":"Lists the carts of your account, newest last unless you send `desc=true`. A cursor-based list: page with `after_item` and `before_item`. It has no `sort_by`. Secret and trusted tokens only; a limited token gets `403`. Inside the list, `payments`, `promotions`, `options`, `related_products`, `cross_sells` and `up_sells` are always URLs.","tags":["carts"],"x-limited":false,"parameters":[{"name":"open","in":"query","description":"`true` for open carts only, `false` for closed (paid) carts only.","required":false,"schema":{"type":"boolean"}},{"name":"payment_status","in":"query","description":"Only carts with this payment status. Open carts have none, so this finds paid carts.","required":false,"schema":{"type":"string","enum":["pending","completed","refunded","cancelled"]}},{"name":"q","in":"query","description":"Search text. Matches the cart_id, the customer's email or customer_id exactly, or part of the customer's name or company name.","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/after_item"},{"$ref":"#/components/parameters/before_item"},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/date_start"},{"$ref":"#/components/parameters/date_end"},{"$ref":"#/components/parameters/date_type"},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of carts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cart_list"},"example":{"next_page_url":"https://api.comecero.com/api/v1/carts?after_item=0091307952465CafhFSTa1","next_page_after_item":"0091307952465CafhFSTa1","previous_page_url":null,"previous_page_before_item":null,"data":[]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Create a cart","operationId":"create_cart","description":"Creates a cart, with items and a customer if you send them. Prices, tax, shipping and promotions are worked out for you. Any token type may call it. A limited token is bound to the new cart, so it can read and change it later. With no customer in the request, an empty customer is made for the cart. A limited token may not set `reference_price` on an item (`403`, error `m82tixT`). `max_cross_sells` and `max_up_sells` limit the offers when you expand them.","tags":["carts"],"x-limited":true,"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/timezone"},{"name":"max_cross_sells","in":"query","description":"How many cross-sell offers to return when `cross_sells` is expanded, 0 to 10. Default 3.","required":false,"schema":{"type":"integer","minimum":0,"maximum":10}},{"name":"max_up_sells","in":"query","description":"How many up-sell offers to return when `up_sells` is expanded, 0 to 10. Default 3.","required":false,"schema":{"type":"integer","minimum":0,"maximum":10}},{"$ref":"#/components/parameters/user_ip_address"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cart_request"},"examples":{"minimal":{"summary":"A cart with one product","value":{"currency":"USD","items":[{"product_id":"widget-pro.test","quantity":1}]}},"full":{"summary":"With the customer and a referrer","value":{"currency":"USD","items":[{"product_id":"widget-pro.test","quantity":2}],"customer":{"name":"John Smith","email":"john@example.com","billing_address":{"country":"US","postal_code":"27265"}},"referrer":"campaign-0044"}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new cart.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cart"},"example":{"object":"cart","url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1","cart_id":"0091307952465CafhFSTa1","date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:21:40Z","test":true,"account_id":"AB1234","order_id":"8352-CSGYX-348","open":true,"payment_status":null,"currency":"USD","subtotal":199.9,"subtotal_original":199.9,"shipping":0,"shipping_original":0,"discount":0,"item_discounts":0,"total_discounts":0,"total_discounts_percent":0,"tax":14.99,"tax_original":14.99,"total":214.89,"total_original":214.89,"tax_inclusive":false,"total_payments":0,"total_remaining":214.89,"discount_on_gross":false,"settlement_currency":"USD","settlement_subtotal":199.9,"settlement_subtotal_original":199.9,"settlement_shipping":0,"settlement_shipping_original":0,"settlement_discount":0,"settlement_total_discounts":0,"settlement_tax":14.99,"settlement_tax_original":14.99,"settlement_total":214.89,"settlement_total_original":214.89,"customer_ip_address":"203.0.113.44","customer_ip_country":"US","referrer":"campaign-0044","affiliate_id":null,"promotion_code":null,"items_count":1,"items_quantity":2,"items":[{"object":"cart_item","url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/items/pdf-pro.test","item_id":"pdf-pro.test","cross_sell_id":null,"up_sell_id":null,"bundle_id":null,"bundle_group_id":null,"date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:19:12Z","product_id":"pdf-pro.test","cart_id":"0091307952465CafhFSTa1","name":"PDF Viewer Pro","type":"digital","quantity":2,"currency":"USD","price":99.95,"price_original":99.95,"reference_price":null,"reference_currency":null,"subtotal":199.9,"subtotal_original":199.9,"discount":0,"discount_percent":0,"tax":14.99,"tax_original":14.99,"total":214.89,"total_original":214.89,"tax_rate":0.075,"tax_code":null,"settlement_currency":"USD","settlement_price":99.95,"settlement_price_original":99.95,"settlement_subtotal":199.9,"settlement_subtotal_original":199.9,"settlement_discount":0,"settlement_tax":14.99,"settlement_tax_original":14.99,"settlement_total":214.89,"settlement_total_original":214.89,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription_plan":null,"subscription_terms":null,"meta":null}],"shipping_item":null,"customer":{"object":"customer","url":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1","customer_id":"0091307952481CuXUhvCA1","date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:21:40Z","account_id":"AB1234","test":true,"company_name":null,"name":"John Smith","email":"john@example.com","phone":null,"billing_address":{"object":"address","name":null,"address_1":null,"address_2":null,"city":null,"state_prov":null,"postal_code":"27265","country":"US","email":null,"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":null,"tax_number":null,"tax_exempt":false,"has_payments":false,"locale":"en-US","meta":null,"payment_methods":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/payment_methods","payments":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/payments","refunds":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/refunds","orders":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/orders","subscriptions":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/subscriptions","invoices":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/invoices"},"order":null,"payments":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/payments","promotions":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/promotions","options":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/options","meta":null,"related_products":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/related_products","cross_sells":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/cross_sells","up_sells":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/up_sells"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/carts/{cart_id}":{"get":{"summary":"Retrieve a cart","operationId":"get_cart","description":"Returns a cart with fresh prices. Any token type may call it; a limited token only for a cart it is bound to (`403` otherwise). A cart not used for a while expires and is then `404`. Add `expand=options` to get the cart options in the same call. When a bundle in the cart holds a product that was since removed, the cart has `warnings`.","tags":["carts"],"x-limited":true,"parameters":[{"name":"cart_id","in":"path","required":true,"description":"The id of the cart.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/timezone"},{"name":"max_cross_sells","in":"query","required":false,"description":"How many cross-sell offers to return when `cross_sells` is expanded, 0 to 10. Default 3.","schema":{"type":"integer","minimum":0,"maximum":10}},{"name":"max_up_sells","in":"query","required":false,"description":"How many up-sell offers to return when `up_sells` is expanded, 0 to 10. Default 3.","schema":{"type":"integer","minimum":0,"maximum":10}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The cart.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cart"},"example":{"object":"cart","url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1","cart_id":"0091307952465CafhFSTa1","date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:21:40Z","test":true,"account_id":"AB1234","order_id":"8352-CSGYX-348","open":true,"payment_status":null,"currency":"USD","subtotal":199.9,"subtotal_original":199.9,"shipping":0,"shipping_original":0,"discount":0,"item_discounts":0,"total_discounts":0,"total_discounts_percent":0,"tax":14.99,"tax_original":14.99,"total":214.89,"total_original":214.89,"tax_inclusive":false,"total_payments":0,"total_remaining":214.89,"discount_on_gross":false,"settlement_currency":"USD","settlement_subtotal":199.9,"settlement_subtotal_original":199.9,"settlement_shipping":0,"settlement_shipping_original":0,"settlement_discount":0,"settlement_total_discounts":0,"settlement_tax":14.99,"settlement_tax_original":14.99,"settlement_total":214.89,"settlement_total_original":214.89,"customer_ip_address":"203.0.113.44","customer_ip_country":"US","referrer":"campaign-0044","affiliate_id":null,"promotion_code":null,"items_count":1,"items_quantity":2,"items":[{"object":"cart_item","url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/items/pdf-pro.test","item_id":"pdf-pro.test","cross_sell_id":null,"up_sell_id":null,"bundle_id":null,"bundle_group_id":null,"date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:19:12Z","product_id":"pdf-pro.test","cart_id":"0091307952465CafhFSTa1","name":"PDF Viewer Pro","type":"digital","quantity":2,"currency":"USD","price":99.95,"price_original":99.95,"reference_price":null,"reference_currency":null,"subtotal":199.9,"subtotal_original":199.9,"discount":0,"discount_percent":0,"tax":14.99,"tax_original":14.99,"total":214.89,"total_original":214.89,"tax_rate":0.075,"tax_code":null,"settlement_currency":"USD","settlement_price":99.95,"settlement_price_original":99.95,"settlement_subtotal":199.9,"settlement_subtotal_original":199.9,"settlement_discount":0,"settlement_tax":14.99,"settlement_tax_original":14.99,"settlement_total":214.89,"settlement_total_original":214.89,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription_plan":null,"subscription_terms":null,"meta":null}],"shipping_item":null,"customer":{"object":"customer","url":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1","customer_id":"0091307952481CuXUhvCA1","date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:21:40Z","account_id":"AB1234","test":true,"company_name":null,"name":"John Smith","email":"john@example.com","phone":null,"billing_address":{"object":"address","name":null,"address_1":null,"address_2":null,"city":null,"state_prov":null,"postal_code":"27265","country":"US","email":null,"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":null,"tax_number":null,"tax_exempt":false,"has_payments":false,"locale":"en-US","meta":null,"payment_methods":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/payment_methods","payments":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/payments","refunds":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/refunds","orders":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/orders","subscriptions":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/subscriptions","invoices":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/invoices"},"order":null,"payments":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/payments","promotions":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/promotions","options":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/options","meta":null,"related_products":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/related_products","cross_sells":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/cross_sells","up_sells":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/up_sells"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Update a cart","operationId":"update_cart","description":"Changes a cart. Only the fields you send change, but `items` replaces all items. Prices, tax, shipping and promotions are worked out again. Any token type may call it; a limited token only for a bound cart. A closed cart cannot change (`422`). `order_id` can only be set on create. A limited token may not set `reference_price` (`403`, error `m82tixT`).","tags":["carts"],"x-limited":true,"parameters":[{"name":"cart_id","in":"path","required":true,"description":"The id of the cart.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/timezone"},{"name":"max_cross_sells","in":"query","required":false,"description":"How many cross-sell offers to return when `cross_sells` is expanded, 0 to 10. Default 3.","schema":{"type":"integer","minimum":0,"maximum":10}},{"name":"max_up_sells","in":"query","required":false,"description":"How many up-sell offers to return when `up_sells` is expanded, 0 to 10. Default 3.","schema":{"type":"integer","minimum":0,"maximum":10}},{"$ref":"#/components/parameters/user_ip_address"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cart_request"},"example":{"shipping_method_id":"standard-us","promotion_code":"SAVE10"}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The changed cart.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cart"},"example":{"object":"cart","url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1","cart_id":"0091307952465CafhFSTa1","date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:21:40Z","test":true,"account_id":"AB1234","order_id":"8352-CSGYX-348","open":true,"payment_status":null,"currency":"USD","subtotal":199.9,"subtotal_original":199.9,"shipping":0,"shipping_original":0,"discount":0,"item_discounts":0,"total_discounts":0,"total_discounts_percent":0,"tax":14.99,"tax_original":14.99,"total":214.89,"total_original":214.89,"tax_inclusive":false,"total_payments":0,"total_remaining":214.89,"discount_on_gross":false,"settlement_currency":"USD","settlement_subtotal":199.9,"settlement_subtotal_original":199.9,"settlement_shipping":0,"settlement_shipping_original":0,"settlement_discount":0,"settlement_total_discounts":0,"settlement_tax":14.99,"settlement_tax_original":14.99,"settlement_total":214.89,"settlement_total_original":214.89,"customer_ip_address":"203.0.113.44","customer_ip_country":"US","referrer":"campaign-0044","affiliate_id":null,"promotion_code":null,"items_count":1,"items_quantity":2,"items":[{"object":"cart_item","url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/items/pdf-pro.test","item_id":"pdf-pro.test","cross_sell_id":null,"up_sell_id":null,"bundle_id":null,"bundle_group_id":null,"date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:19:12Z","product_id":"pdf-pro.test","cart_id":"0091307952465CafhFSTa1","name":"PDF Viewer Pro","type":"digital","quantity":2,"currency":"USD","price":99.95,"price_original":99.95,"reference_price":null,"reference_currency":null,"subtotal":199.9,"subtotal_original":199.9,"discount":0,"discount_percent":0,"tax":14.99,"tax_original":14.99,"total":214.89,"total_original":214.89,"tax_rate":0.075,"tax_code":null,"settlement_currency":"USD","settlement_price":99.95,"settlement_price_original":99.95,"settlement_subtotal":199.9,"settlement_subtotal_original":199.9,"settlement_discount":0,"settlement_tax":14.99,"settlement_tax_original":14.99,"settlement_total":214.89,"settlement_total_original":214.89,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription_plan":null,"subscription_terms":null,"meta":null}],"shipping_item":null,"customer":{"object":"customer","url":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1","customer_id":"0091307952481CuXUhvCA1","date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:21:40Z","account_id":"AB1234","test":true,"company_name":null,"name":"John Smith","email":"john@example.com","phone":null,"billing_address":{"object":"address","name":null,"address_1":null,"address_2":null,"city":null,"state_prov":null,"postal_code":"27265","country":"US","email":null,"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":null,"tax_number":null,"tax_exempt":false,"has_payments":false,"locale":"en-US","meta":null,"payment_methods":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/payment_methods","payments":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/payments","refunds":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/refunds","orders":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/orders","subscriptions":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/subscriptions","invoices":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/invoices"},"order":null,"payments":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/payments","promotions":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/promotions","options":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/options","meta":null,"related_products":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/related_products","cross_sells":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/cross_sells","up_sells":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/up_sells"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/carts/{cart_id}/cross_sells":{"get":{"summary":"List cart cross-sells","operationId":"list_cart_cross_sells","description":"Returns cross-sell offers for the cart: other products, often at a discount, picked from your active cross-sell promotions for the products in the cart. The pick is weighted and random, so it can change between calls. To take an offer, add its product with its `cross_sell_id`. One page. Any token type may call it; a limited token only for a bound cart.","tags":["carts"],"x-limited":true,"parameters":[{"name":"cart_id","in":"path","required":true,"description":"The id of the cart.","schema":{"type":"string"}},{"name":"max_cross_sells","in":"query","required":false,"description":"How many cross-sell offers to return when `cross_sells` is expanded, 0 to 10. Default 3.","schema":{"type":"integer","minimum":0,"maximum":10}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The cross-sell offers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cart_cross_sell_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/cross_sells?offset=0&limit=10","data":[{"cross_sell_id":"0091307952500PtXk3Lw-a1b2","product_id":"pdf-fonts.test","name":"Font Pack","price":15.99,"price_original":19.99,"discount":4,"discount_percent":0.2,"currency":"USD","product":"https://api.comecero.com/api/v1/products/pdf-fonts.test"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/carts/{cart_id}/items":{"get":{"summary":"List cart items","operationId":"list_cart_items","description":"Lists the items in a cart. An offset-based list; with no `limit` every item is on one page. `sort_by` takes `date_created` (the default), `date_modified`, `product_id` or `item_id`. Any token type may call it; a limited token only for a bound cart.","tags":["carts"],"x-limited":true,"parameters":[{"name":"cart_id","in":"path","required":true,"description":"The id of the cart.","schema":{"type":"string"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"name":"sort_by","in":"query","required":false,"description":"The field to sort by.","schema":{"type":"string","enum":["date_created","date_modified","product_id","item_id"],"default":"date_created"}},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The items in the cart.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cart_item_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/items","data":[]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Add an item to a cart","operationId":"create_cart_item","description":"Adds a product to a cart. `product_id` is required (error `BpmhEyl`). The price comes from the product; only a secret or trusted token may set `reference_price` (a limited token gets `403`, error `m82tixT`). A product already in the cart is replaced, not added to. Adding a bundle adds one item for the bundle and one for each of its products, and then the answer is an offset list of those items instead of one item. Tax, shipping and promotions are worked out again. Any token type may call it; a limited token only for a bound cart. A closed cart is `422`.","tags":["carts"],"x-limited":true,"parameters":[{"name":"cart_id","in":"path","required":true,"description":"The id of the cart.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cart_item_request"},"examples":{"product":{"summary":"Add a product","value":{"product_id":"widget-pro.test","quantity":1}},"with_meta":{"summary":"Add a product with your own data","value":{"product_id":"widget-pro.test","quantity":2,"meta":{"gift":true}}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new item, or for a bundle a list of the new items.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/cart_item"},{"$ref":"#/components/schemas/cart_item_list"}]},"example":{"object":"cart_item","url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/items/pdf-pro.test","item_id":"pdf-pro.test","cross_sell_id":null,"up_sell_id":null,"bundle_id":null,"bundle_group_id":null,"date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:19:12Z","product_id":"pdf-pro.test","cart_id":"0091307952465CafhFSTa1","name":"PDF Viewer Pro","type":"digital","quantity":2,"currency":"USD","price":99.95,"price_original":99.95,"reference_price":null,"reference_currency":null,"subtotal":199.9,"subtotal_original":199.9,"discount":0,"discount_percent":0,"tax":14.99,"tax_original":14.99,"total":214.89,"total_original":214.89,"tax_rate":0.075,"tax_code":null,"settlement_currency":"USD","settlement_price":99.95,"settlement_price_original":99.95,"settlement_subtotal":199.9,"settlement_subtotal_original":199.9,"settlement_discount":0,"settlement_tax":14.99,"settlement_tax_original":14.99,"settlement_total":214.89,"settlement_total_original":214.89,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription_plan":null,"subscription_terms":null,"meta":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"summary":"Remove all cart items","operationId":"delete_cart_items","description":"Empties a cart. Any token type may call it, a limited token too (only for a bound cart). A closed cart is `422`.","tags":["carts"],"x-limited":true,"parameters":[{"name":"cart_id","in":"path","required":true,"description":"The id of the cart.","schema":{"type":"string"}}],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The cart is empty."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/carts/{cart_id}/items/{item_id}":{"get":{"summary":"Retrieve a cart item","operationId":"get_cart_item","description":"Returns one item of a cart. Any token type may call it; a limited token only for a bound cart.","tags":["carts"],"x-limited":true,"parameters":[{"name":"cart_id","in":"path","required":true,"description":"The id of the cart.","schema":{"type":"string"}},{"name":"item_id","in":"path","required":true,"description":"The id of the item. For a product, the product_id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cart_item"},"example":{"object":"cart_item","url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/items/pdf-pro.test","item_id":"pdf-pro.test","cross_sell_id":null,"up_sell_id":null,"bundle_id":null,"bundle_group_id":null,"date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:19:12Z","product_id":"pdf-pro.test","cart_id":"0091307952465CafhFSTa1","name":"PDF Viewer Pro","type":"digital","quantity":2,"currency":"USD","price":99.95,"price_original":99.95,"reference_price":null,"reference_currency":null,"subtotal":199.9,"subtotal_original":199.9,"discount":0,"discount_percent":0,"tax":14.99,"tax_original":14.99,"total":214.89,"total_original":214.89,"tax_rate":0.075,"tax_code":null,"settlement_currency":"USD","settlement_price":99.95,"settlement_price_original":99.95,"settlement_subtotal":199.9,"settlement_subtotal_original":199.9,"settlement_discount":0,"settlement_tax":14.99,"settlement_tax_original":14.99,"settlement_total":214.89,"settlement_total_original":214.89,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription_plan":null,"subscription_terms":null,"meta":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Update a cart item","operationId":"update_cart_item","description":"Changes the quantity, `meta` or (secret and trusted tokens only) `reference_price` of an item. A limited token sending `reference_price` or `reference_currency` gets `403` (error `m82tixT`). An item that is part of a bundle cannot be changed (`400`, error `kx3Bq7T`): delete it and add the bundle again. Any token type may call it; a limited token only for a bound cart. A closed cart is `422`.","tags":["carts"],"x-limited":true,"parameters":[{"name":"cart_id","in":"path","required":true,"description":"The id of the cart.","schema":{"type":"string"}},{"name":"item_id","in":"path","required":true,"description":"The id of the item. For a product, the product_id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cart_item_request"},"example":{"quantity":3}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The changed item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cart_item"},"example":{"object":"cart_item","url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/items/pdf-pro.test","item_id":"pdf-pro.test","cross_sell_id":null,"up_sell_id":null,"bundle_id":null,"bundle_group_id":null,"date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:19:12Z","product_id":"pdf-pro.test","cart_id":"0091307952465CafhFSTa1","name":"PDF Viewer Pro","type":"digital","quantity":2,"currency":"USD","price":99.95,"price_original":99.95,"reference_price":null,"reference_currency":null,"subtotal":199.9,"subtotal_original":199.9,"discount":0,"discount_percent":0,"tax":14.99,"tax_original":14.99,"total":214.89,"total_original":214.89,"tax_rate":0.075,"tax_code":null,"settlement_currency":"USD","settlement_price":99.95,"settlement_price_original":99.95,"settlement_subtotal":199.9,"settlement_subtotal_original":199.9,"settlement_discount":0,"settlement_tax":14.99,"settlement_tax_original":14.99,"settlement_total":214.89,"settlement_total_original":214.89,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription_plan":null,"subscription_terms":null,"meta":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"summary":"Remove a cart item","operationId":"delete_cart_item","description":"Removes one item. Removing an item of a bundle removes the whole bundle. Secret and trusted tokens only: a limited token gets `403`. To let a shopper remove an item, update the cart with the new `items` list. A closed cart is `422`.","tags":["carts"],"x-limited":false,"parameters":[{"name":"cart_id","in":"path","required":true,"description":"The id of the cart.","schema":{"type":"string"}},{"name":"item_id","in":"path","required":true,"description":"The id of the item. For a product, the product_id.","schema":{"type":"string"}}],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The item is removed."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/carts/{cart_id}/items/{item_id}/subscription_terms":{"get":{"summary":"Retrieve cart item subscription terms","operationId":"get_cart_item_subscription_terms","description":"Returns the subscription the item would start if the cart were paid now: the price per period, how often, any trial and discount. Use it to show the shopper what they sign up for. An item whose product is not a subscription is `404`. Any token type may call it; a limited token only for a bound cart.","tags":["carts"],"x-limited":true,"parameters":[{"name":"cart_id","in":"path","required":true,"description":"The id of the cart.","schema":{"type":"string"}},{"name":"item_id","in":"path","required":true,"description":"The id of the item. For a product, the product_id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The subscription terms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_terms"},"example":{"object":"subscription_terms","price":19.95,"quantity":1,"currency":"USD","discount":0,"discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"tax_inclusve":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"date_trial_start":null,"date_trial_end":null,"end_at_billing_count":null,"date_billing_start":"2026-10-02T15:21:28Z","subscription_id":"0093799318129SuLByRPW8","description":"Acme Pro (monthly) is a subscription that renews every month with a payment of $19.95.","price_per_day":0.66,"price_per_month":19.95,"price_per_year":239.4}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/carts/{cart_id}/login":{"post":{"summary":"Sign a customer in to a cart","operationId":"login_cart","description":"Checks a customer's username and password and, when they match, puts that customer on the cart. Tax, shipping and promotions are worked out again for the customer's details. For a limited token this is how a shopper signs in during checkout; the token can then use the customer's saved payment methods. Wrong details are `401` with code `invalid_login`; after too many failures the customer is locked for 10 minutes (`401`, code `account_locked`). Any token type may call it; a limited token only for a bound cart.","tags":["carts"],"x-limited":true,"parameters":[{"name":"cart_id","in":"path","required":true,"description":"The id of the cart.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/formatted"},{"name":"max_cross_sells","in":"query","required":false,"description":"How many cross-sell offers to return when `cross_sells` is expanded, 0 to 10. Default 3.","schema":{"type":"integer","minimum":0,"maximum":10}},{"name":"max_up_sells","in":"query","required":false,"description":"How many up-sell offers to return when `up_sells` is expanded, 0 to 10. Default 3.","schema":{"type":"integer","minimum":0,"maximum":10}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cart_login_request"},"examples":{"login":{"summary":"Sign the customer in","value":{"username":"john@example.com","password":"example-password"}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The cart, now with the customer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cart"},"example":{"object":"cart","url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1","cart_id":"0091307952465CafhFSTa1","date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:21:40Z","test":true,"account_id":"AB1234","order_id":"8352-CSGYX-348","open":true,"payment_status":null,"currency":"USD","subtotal":199.9,"subtotal_original":199.9,"shipping":0,"shipping_original":0,"discount":0,"item_discounts":0,"total_discounts":0,"total_discounts_percent":0,"tax":14.99,"tax_original":14.99,"total":214.89,"total_original":214.89,"tax_inclusive":false,"total_payments":0,"total_remaining":214.89,"discount_on_gross":false,"settlement_currency":"USD","settlement_subtotal":199.9,"settlement_subtotal_original":199.9,"settlement_shipping":0,"settlement_shipping_original":0,"settlement_discount":0,"settlement_total_discounts":0,"settlement_tax":14.99,"settlement_tax_original":14.99,"settlement_total":214.89,"settlement_total_original":214.89,"customer_ip_address":"203.0.113.44","customer_ip_country":"US","referrer":"campaign-0044","affiliate_id":null,"promotion_code":null,"items_count":1,"items_quantity":2,"items":[{"object":"cart_item","url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/items/pdf-pro.test","item_id":"pdf-pro.test","cross_sell_id":null,"up_sell_id":null,"bundle_id":null,"bundle_group_id":null,"date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:19:12Z","product_id":"pdf-pro.test","cart_id":"0091307952465CafhFSTa1","name":"PDF Viewer Pro","type":"digital","quantity":2,"currency":"USD","price":99.95,"price_original":99.95,"reference_price":null,"reference_currency":null,"subtotal":199.9,"subtotal_original":199.9,"discount":0,"discount_percent":0,"tax":14.99,"tax_original":14.99,"total":214.89,"total_original":214.89,"tax_rate":0.075,"tax_code":null,"settlement_currency":"USD","settlement_price":99.95,"settlement_price_original":99.95,"settlement_subtotal":199.9,"settlement_subtotal_original":199.9,"settlement_discount":0,"settlement_tax":14.99,"settlement_tax_original":14.99,"settlement_total":214.89,"settlement_total_original":214.89,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription_plan":null,"subscription_terms":null,"meta":null}],"shipping_item":null,"customer":{"object":"customer","url":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1","customer_id":"0091307952481CuXUhvCA1","date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:21:40Z","account_id":"AB1234","test":true,"company_name":null,"name":"John Smith","email":"john@example.com","phone":null,"billing_address":{"object":"address","name":null,"address_1":null,"address_2":null,"city":null,"state_prov":null,"postal_code":"27265","country":"US","email":null,"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":null,"tax_number":null,"tax_exempt":false,"has_payments":false,"locale":"en-US","meta":null,"payment_methods":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/payment_methods","payments":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/payments","refunds":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/refunds","orders":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/orders","subscriptions":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/subscriptions","invoices":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/invoices"},"order":null,"payments":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/payments","promotions":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/promotions","options":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/options","meta":null,"related_products":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/related_products","cross_sells":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/cross_sells","up_sells":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/up_sells"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/carts/{cart_id}/logout":{"post":{"summary":"Sign the customer out of a cart","operationId":"logout_cart","description":"Takes the customer off the cart and works out tax, shipping and promotions again without them. The token is no longer bound to that customer but stays bound to the cart. Send no body. Any token type may call it; a limited token only for a bound cart. A cart with no customer is returned unchanged.","tags":["carts"],"x-limited":true,"parameters":[{"name":"cart_id","in":"path","required":true,"description":"The id of the cart.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/formatted"},{"name":"max_cross_sells","in":"query","required":false,"description":"How many cross-sell offers to return when `cross_sells` is expanded, 0 to 10. Default 3.","schema":{"type":"integer","minimum":0,"maximum":10}},{"name":"max_up_sells","in":"query","required":false,"description":"How many up-sell offers to return when `up_sells` is expanded, 0 to 10. Default 3.","schema":{"type":"integer","minimum":0,"maximum":10}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The cart, now with no customer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cart"},"example":{"object":"cart","url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1","cart_id":"0091307952465CafhFSTa1","date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:21:40Z","test":true,"account_id":"AB1234","order_id":"8352-CSGYX-348","open":true,"payment_status":null,"currency":"USD","subtotal":199.9,"subtotal_original":199.9,"shipping":0,"shipping_original":0,"discount":0,"item_discounts":0,"total_discounts":0,"total_discounts_percent":0,"tax":14.99,"tax_original":14.99,"total":214.89,"total_original":214.89,"tax_inclusive":false,"total_payments":0,"total_remaining":214.89,"discount_on_gross":false,"settlement_currency":"USD","settlement_subtotal":199.9,"settlement_subtotal_original":199.9,"settlement_shipping":0,"settlement_shipping_original":0,"settlement_discount":0,"settlement_total_discounts":0,"settlement_tax":14.99,"settlement_tax_original":14.99,"settlement_total":214.89,"settlement_total_original":214.89,"customer_ip_address":"203.0.113.44","customer_ip_country":"US","referrer":"campaign-0044","affiliate_id":null,"promotion_code":null,"items_count":1,"items_quantity":2,"items":[{"object":"cart_item","url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/items/pdf-pro.test","item_id":"pdf-pro.test","cross_sell_id":null,"up_sell_id":null,"bundle_id":null,"bundle_group_id":null,"date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:19:12Z","product_id":"pdf-pro.test","cart_id":"0091307952465CafhFSTa1","name":"PDF Viewer Pro","type":"digital","quantity":2,"currency":"USD","price":99.95,"price_original":99.95,"reference_price":null,"reference_currency":null,"subtotal":199.9,"subtotal_original":199.9,"discount":0,"discount_percent":0,"tax":14.99,"tax_original":14.99,"total":214.89,"total_original":214.89,"tax_rate":0.075,"tax_code":null,"settlement_currency":"USD","settlement_price":99.95,"settlement_price_original":99.95,"settlement_subtotal":199.9,"settlement_subtotal_original":199.9,"settlement_discount":0,"settlement_tax":14.99,"settlement_tax_original":14.99,"settlement_total":214.89,"settlement_total_original":214.89,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription_plan":null,"subscription_terms":null,"meta":null}],"shipping_item":null,"customer":{"object":"customer","url":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1","customer_id":"0091307952481CuXUhvCA1","date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:21:40Z","account_id":"AB1234","test":true,"company_name":null,"name":"John Smith","email":"john@example.com","phone":null,"billing_address":{"object":"address","name":null,"address_1":null,"address_2":null,"city":null,"state_prov":null,"postal_code":"27265","country":"US","email":null,"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":null,"tax_number":null,"tax_exempt":false,"has_payments":false,"locale":"en-US","meta":null,"payment_methods":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/payment_methods","payments":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/payments","refunds":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/refunds","orders":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/orders","subscriptions":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/subscriptions","invoices":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/invoices"},"order":null,"payments":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/payments","promotions":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/promotions","options":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/options","meta":null,"related_products":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/related_products","cross_sells":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/cross_sells","up_sells":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/up_sells"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/carts/{cart_id}/options":{"get":{"summary":"Retrieve cart options","operationId":"get_cart_options","description":"Returns what the shopper can choose and must provide to pay for the cart: payment methods (with what the browser needs to set each up), card types, shipping quotes and the required customer fields. Read it again after the items, currency or customer change. You can also get it inside the cart with `expand=options`; the old `options=true` parameter is accepted but does nothing. Any token type may call it; a limited token only for a bound cart.","tags":["carts"],"x-limited":true,"parameters":[{"name":"cart_id","in":"path","required":true,"description":"The id of the cart.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The cart options.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cart_options"},"example":{"cart_id":"0091307952465CafhFSTa1","account_id":"AB1234","test":true,"payment_methods":[{"payment_method_type":"credit_card","surcharge":0,"currency":"USD","paypal_fraudnet_source_id":null,"stripe_publishable_key":null,"stripe_account_id":null,"finix_card_form":null},{"payment_method_type":"paypal","surcharge":0,"currency":"USD"}],"card_types":["Visa","MasterCard","American Express"],"shipping_quotes":[{"shipping_method_id":"standard-us","method_id":"standard-us","description":"Standard Shipping","details":"3 to 5 business days","price":5,"price_original":5,"price_pre_tax":5,"price_pre_tax_original":5,"discount":0,"tax":0,"tax_original":0,"total":5,"tax_rate":0,"currency":"USD"}],"customer_required_fields":["name","email","billing_address.country","billing_address.postal_code"],"customer_optional_fields":["phone","company_name"],"allowed_customer_countries":["US","CA"],"require_cardholder_name":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/carts/{cart_id}/payments":{"get":{"summary":"List cart payments","operationId":"list_cart_payments","description":"Lists the payments made for a cart, failed ones included. An offset-based list. `sort_by` takes `date_created` (the default), `date_modified` or `date_completed`. Any token type may call it; a limited token only for a bound cart.","tags":["carts"],"x-limited":true,"parameters":[{"name":"cart_id","in":"path","required":true,"description":"The id of the cart.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Only payments with this status.","schema":{"type":"string","enum":["initiated","processing","pending","completed","failed","cancelled","refunded","retry"]}},{"name":"reference","in":"query","required":false,"description":"Only payments with this `reference`.","schema":{"type":"string"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"name":"sort_by","in":"query","required":false,"description":"The field to sort by.","schema":{"type":"string","enum":["date_created","date_modified","date_completed"],"default":"date_created"}},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/timezone"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The payments for the cart.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cart_payment_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/payments?offset=0&limit=10","data":[{"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}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Pay for a cart","operationId":"create_cart_payment","description":"Charges the cart total with the payment method you send, or the customer's default one. The amount and currency come from the cart, so do not send `total` or `currency` (`400`). Any token type may call it; a limited token only for a bound cart, and a limited test token only when its user may make test payments.\n\nA payment that succeeds at once closes the cart and makes the order: `status` is `completed`, or `pending` when it is only authorized. Events fire and the receipt email goes out. A payment that needs the shopper to act comes back `201` with `status` `initiated` and the next step in `response_data` (expand it): a `redirect_url` for PayPal or a 3-D Secure check, a `next_action` for a Comecero Express Payments 3-D Secure check you run on your own page, or the Stripe.js values for a `stripe` payment. When the shopper is done, get the payment and call `POST /payments/{payment_id}/commit` only while it is still `initiated` (the Comecero 3-D Secure page commits it itself). Until then the cart stays open.\n\nA declined payment is `402` with the payment in `error.meta.payment`. The same payment sent again soon after a success is `409` (code `duplicate`). A closed cart, an empty cart or a payment still being processed is `400`.","tags":["carts"],"x-limited":true,"parameters":[{"name":"cart_id","in":"path","required":true,"description":"The id of the cart.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/user_ip_address"},{"$ref":"#/components/parameters/user_agent"}],"requestBody":{"$ref":"#/components/requestBodies/payment_request"},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The payment: `completed`, `pending`, `processing` or `initiated` (waiting for the shopper).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment"},"example":{"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}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The gateway declined the payment (type `transaction_error`). The failed payment is in `error.meta.payment`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The cart, invoice or payment is not in a state that allows this, or another payment for it is still running (code `payment_in_progress`), or an earlier payment for it may have been taken but is not confirmed yet (code `payment_unconfirmed`). Do not send the payment again: read the payments of the cart or invoice first, so the shopper is never charged twice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"The gateway answered with an error (type `external_server_error`). The payment is in `error.meta.payment`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"504":{"description":"The gateway did not answer in time (type `external_server_timeout`). Read the payment before you try again: it may have gone through.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}}}},"/carts/{cart_id}/promotions":{"get":{"summary":"List cart promotions","operationId":"list_cart_promotions","description":"Lists the promotions applied to the cart: its coupon, and the cross-sell and up-sell offers of its items. An offset-based list. `sort_by` takes `date_created` (the default), `promotion_id`, `name` or `date_modified`. Any token type may call it; a limited token only for a bound cart.","tags":["carts"],"x-limited":true,"parameters":[{"name":"cart_id","in":"path","required":true,"description":"The id of the cart.","schema":{"type":"string"}},{"name":"active","in":"query","required":false,"description":"`true` for active promotions only, `false` for inactive only.","schema":{"type":"boolean"}},{"name":"q","in":"query","required":false,"description":"Search text. Matches a promotion_id exactly or part of a promotion name.","schema":{"type":"string"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"name":"sort_by","in":"query","required":false,"description":"The field to sort by. Any other value sorts by `date_created`.","schema":{"type":"string","enum":["date_created","promotion_id","name","date_modified"],"default":"date_created"}},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The promotions on the cart.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/promotion_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/promotions?offset=0&limit=10","data":[{"object":"promotion","url":"https://api.comecero.com/api/v1/promotions/0070576784690PtKDqfI","promotion_id":"0070576784690PtKDqfI","name":"Ten percent off","test":true,"account_id":"AB1234","date_created":"2026-11-02T20:13:16Z","date_modified":"2026-11-02T20:13:16Z","type":"coupon","active":true,"apply_to_recurring":false,"apply_to_recurring_count":null,"use_count":4,"expires":"2026-12-31T23:59:59Z","comments":null,"config":{"type":"order","code":"SAVE10","generator_prefix":null,"generator_secret_key":null,"discount_percent":0.1,"discount_amount":null,"product_ids":null,"exclude_product_ids":false,"max_uses_per_customer":1,"max_uses_global":null}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/carts/{cart_id}/related_products":{"get":{"summary":"List related products for a cart","operationId":"list_cart_related_products","description":"Lists up to 3 products set as related to the products in the cart. Products already in the cart are left out. One page; it takes no paging parameters. Any token type may call it; a limited token only for a bound cart.","tags":["carts"],"x-limited":true,"parameters":[{"name":"cart_id","in":"path","required":true,"description":"The id of the cart.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The related products.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cart_product_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/related_products?offset=0&limit=10","data":[{"object":"product","url":"https://api.comecero.com/api/v1/products/widget.test","product_id":"widget.test","date_created":"2026-11-02T14:36:52Z","date_modified":"2026-11-02T14:36:52Z","test":true,"account_id":"AB1234","name":"Widget","price":49.95,"currency":"USD","compare_at_price":59.95,"type":"physical","description":"A simple widget for everyday use.","headline":"The widget you will use every day","tax_code":null,"prices":[{"price":49.95,"currency":"USD"},{"price":45.95,"currency":"EUR"}],"compare_at_prices":[{"price":59.95,"currency":"USD"}],"volume_prices":[{"low":10,"high":null,"prices":[{"price":39.95,"currency":"USD"}]}],"effective_volume_prices":[{"low":1,"high":9,"price":49.95,"currency":"USD","discount_percent":0,"discount_amount":0},{"low":10,"high":null,"price":39.95,"currency":"USD","discount_percent":0.2,"discount_amount":10}],"inventory":{"in_stock":true,"quantity":120,"allow_oversells":false,"low_quantity_notification":10},"bundle_items":[],"weight":{"amount":3,"unit":"lb"},"active":true,"deleted":false,"hidden":false,"date_deleted":null,"file":null,"has_file":false,"license_service":null,"has_license_service":false,"subscription_plan":null,"subscription_terms":null,"images":[{"object":"image","url":"https://api.comecero.com/api/v1/images/0099844605810ImLAMbo73","image_id":"0099844605810ImLAMbo73","date_created":"2026-11-02T14:36:45Z","date_modified":"2026-11-02T14:36:45Z","test":true,"account_id":"AB1234","link":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/widget.png","link_small":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sm_widget.png","link_medium":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/md_widget.png","link_large":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/lg_widget.png","link_square":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sq_widget.png","filename":"widget.png"}],"video_url":null,"related_products":"https://api.comecero.com/api/v1/products/widget.test/related_products","subscription_change_products":"https://api.comecero.com/api/v1/products/widget.test/subscription_change_products","subscription_term_change_products":"https://api.comecero.com/api/v1/products/widget.test/subscription_term_change_products","meta":null,"translations":{"de":{"name":"Widget","headline":"Das Widget fur jeden Tag","description":"Ein einfaches Widget fur jeden Tag."}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/carts/{cart_id}/shipping_item":{"get":{"summary":"Retrieve the cart shipping item","operationId":"get_cart_shipping_item","description":"Returns the shipping line of the cart, made from the selected shipping method. A cart with no shipping is `404`. Any token type may call it; a limited token only for a bound cart.","tags":["carts"],"x-limited":true,"parameters":[{"name":"cart_id","in":"path","required":true,"description":"The id of the cart.","schema":{"type":"string"}},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The shipping item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/shipping_item"},"example":{"object":"cart_item","url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/items/standard-us","item_id":"standard-us","cross_sell_id":null,"up_sell_id":null,"bundle_id":null,"bundle_group_id":null,"date_created":"2026-11-07T19:21:40Z","date_modified":"2026-11-07T19:21:40Z","product_id":null,"cart_id":"0091307952465CafhFSTa1","name":"Standard Shipping","type":"shipping","quantity":1,"currency":"USD","price":5,"price_original":5,"reference_price":null,"reference_currency":null,"subtotal":5,"subtotal_original":5,"discount":0,"discount_percent":0,"tax":0,"tax_original":0,"total":5,"total_original":5,"tax_rate":0,"tax_code":"shipping","settlement_currency":"USD","settlement_price":5,"settlement_price_original":5,"settlement_subtotal":5,"settlement_subtotal_original":5,"settlement_discount":0,"settlement_tax":0,"settlement_tax_original":0,"settlement_total":5,"settlement_total_original":5,"product":null,"subscription_plan":null,"subscription_terms":null,"meta":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/carts/{cart_id}/up_sells":{"get":{"summary":"List cart up-sells","operationId":"list_cart_up_sells","description":"Returns up-sell offers for the cart: a better product in place of one in the cart, picked from your active up-sell promotions. Each offer says which product it replaces and how much more it costs. To take an offer, add its product with its `up_sell_id`; the replaced item is removed. One page. Any token type may call it; a limited token only for a bound cart.","tags":["carts"],"x-limited":true,"parameters":[{"name":"cart_id","in":"path","required":true,"description":"The id of the cart.","schema":{"type":"string"}},{"name":"max_up_sells","in":"query","required":false,"description":"How many up-sell offers to return when `up_sells` is expanded, 0 to 10. Default 3.","schema":{"type":"integer","minimum":0,"maximum":10}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The up-sell offers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cart_up_sell_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/up_sells?offset=0&limit=10","data":[{"up_sell_id":"0091307952511PtR8sQm-c3d4","product_id":"pdf-pro-plus.test","name":"PDF Viewer Pro Plus","price":119.95,"price_original":129.95,"discount":10,"discount_percent":0.08,"currency":"USD","up_sell_from_product":"https://api.comecero.com/api/v1/products/pdf-pro.test","additional_amount":40,"product":"https://api.comecero.com/api/v1/products/pdf-pro-plus.test"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/carts/{cart_id}/user_agent_payment_request/{payment_method_type}":{"get":{"summary":"Retrieve a browser payment request","operationId":"get_cart_user_agent_payment_request","description":"Returns the arguments for the browser's Payment Request API for an Apple Pay checkout on this cart: the method data, the display items, shipping options and total, and which shopper details to ask for. Only `apple_pay` is supported (`404` for another type). Google Pay is set up from the `wallet` payment option in the cart options instead. A currency with no Apple Pay gateway is `400`. Any token type may call it; a limited token only for a bound cart.","tags":["carts"],"x-limited":true,"parameters":[{"name":"cart_id","in":"path","required":true,"description":"The id of the cart.","schema":{"type":"string"}},{"name":"payment_method_type","in":"path","required":true,"description":"The payment method type. Only `apple_pay` is supported; another valid type is `404`, an unknown one `400`.","schema":{"type":"string","enum":["apple_pay"]}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The browser payment request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cart_user_agent_payment_request"},"example":{"url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/user_agent_payment_request/apple_pay","payment_url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/payments","methodData":[{"supportedMethods":"https://apple.com/apple-pay","data":{"version":1,"merchantIdentifier":"merchant.com.example.shop","merchantCapabilities":["supports3DS","supportsCredit","supportsDebit"],"supportedNetworks":["visa","masterCard","amex"],"countryCode":"US","requiredBillingContactFields":["postalAddress"]}}],"details":{"displayItems":[{"label":"PDF Viewer Pro","amount":{"currency":"USD","value":"199.90"},"pending":false},{"label":"Tax","amount":{"currency":"USD","value":"14.99"},"pending":false}],"shippingOptions":[{"id":"digital","label":"Digital","amount":{"currency":"USD","value":"0.00"},"selected":false}],"modifiers":[],"total":{"label":"Total","amount":{"currency":"USD","value":"214.89"},"pending":false}},"paymentOptions":{"requestPayerName":true,"requestPayerEmail":true,"requestPayerPhone":false,"requestShipping":true},"merchant_validation_url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/user_agent_payment_request/apple_pay/merchant_validate"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Update a browser payment request","operationId":"update_cart_user_agent_payment_request","description":"Sends a change from the Apple Pay sheet (a new shipping address or shipping option) to the cart. The cart's customer and shipping method change, tax and shipping are worked out again, and the new payment request comes back for `updateWith()`. Only `apple_pay` is supported. A closed cart is `422`. Any token type may call it; a limited token only for a bound cart.","tags":["carts"],"x-limited":true,"parameters":[{"name":"cart_id","in":"path","required":true,"description":"The id of the cart.","schema":{"type":"string"}},{"name":"payment_method_type","in":"path","required":true,"description":"The payment method type. Only `apple_pay` is supported; another valid type is `404`, an unknown one `400`.","schema":{"type":"string","enum":["apple_pay"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cart_user_agent_payment_request_update"},"examples":{"address":{"summary":"The shopper picked an address","value":{"shippingAddress":{"recipient":"John Smith","addressLine":["1 Main St"],"city":"High Point","region":"NC","postalCode":"27265","country":"US"},"shippingOption":"standard-us"}},"option":{"summary":"The shopper picked a shipping option","value":{"shippingOption":"standard-us"}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The browser payment request for the changed cart.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cart_user_agent_payment_request"},"example":{"url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/user_agent_payment_request/apple_pay","payment_url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/payments","methodData":[{"supportedMethods":"https://apple.com/apple-pay","data":{"version":1,"merchantIdentifier":"merchant.com.example.shop","merchantCapabilities":["supports3DS","supportsCredit","supportsDebit"],"supportedNetworks":["visa","masterCard","amex"],"countryCode":"US","requiredBillingContactFields":["postalAddress"]}}],"details":{"displayItems":[{"label":"PDF Viewer Pro","amount":{"currency":"USD","value":"199.90"},"pending":false},{"label":"Tax","amount":{"currency":"USD","value":"14.99"},"pending":false}],"shippingOptions":[{"id":"digital","label":"Digital","amount":{"currency":"USD","value":"0.00"},"selected":false}],"modifiers":[],"total":{"label":"Total","amount":{"currency":"USD","value":"214.89"},"pending":false}},"paymentOptions":{"requestPayerName":true,"requestPayerEmail":true,"requestPayerPhone":false,"requestShipping":true},"merchant_validation_url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/user_agent_payment_request/apple_pay/merchant_validate"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/carts/{cart_id}/user_agent_payment_request/{payment_method_type}/merchant_validate":{"post":{"summary":"Validate the Apple Pay merchant","operationId":"validate_cart_user_agent_payment_request_merchant","description":"Gets an Apple Pay merchant session for this checkout. Call it from the browser's `onmerchantvalidation` handler with the validation URL Apple gave, then pass `data` to `event.complete()`. Only `apple_pay` is supported. A closed cart is `422`. Any token type may call it; a limited token only for a bound cart.","tags":["carts"],"x-limited":true,"parameters":[{"name":"cart_id","in":"path","required":true,"description":"The id of the cart.","schema":{"type":"string"}},{"name":"payment_method_type","in":"path","required":true,"description":"The payment method type. Only `apple_pay` is supported; another valid type is `404`, an unknown one `400`.","schema":{"type":"string","enum":["apple_pay"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cart_merchant_validate_request"},"examples":{"apple_pay":{"summary":"Validate the Apple Pay merchant","value":{"validation_url":"https://apple-pay-gateway.apple.com/paymentservices/startSession"}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The Apple Pay merchant session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cart_merchant_validation"},"example":{"data":{"epochTimestamp":1793990400000,"expiresAt":1793994000000,"merchantSessionIdentifier":"SSH0000000000000000000000000000000000000000","nonce":"0a1b2c3d","merchantIdentifier":0,"domainName":"shop.example.com","displayName":"Example Shop","signature":"308006092a864886f70d0107"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/commissions":{"get":{"operationId":"list_commissions","summary":"List commissions","description":"Lists the commissions Comecero owes your account for sales it collected on its own gateway, with negative ones for refunds. The list is cursor-based and sorted by `date_type` (`date_created` by default). Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["commissions"],"parameters":[{"name":"type","in":"query","required":false,"description":"Only commissions of this type. Known issue: core currently returns no commissions when you send `type`, so leave it out (every commission is `product_sales`).","schema":{"type":"string","enum":["product_sales"]}},{"name":"accounting_id","in":"query","required":false,"description":"Only commissions in this payout period, such as `C-AB1234P261130USD`.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"An exact commission id.","schema":{"type":"string"}},{"name":"date_type","in":"query","required":false,"description":"Which date `date_start` and `date_end` filter and sort on.","schema":{"type":"string","enum":["date_created","date_modified"],"default":"date_created"}},{"$ref":"#/components/parameters/date_start"},{"$ref":"#/components/parameters/date_end"},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/after_item"},{"$ref":"#/components/parameters/before_item"},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of commissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/commission_list"},"example":{"next_page_url":null,"next_page_after_item":null,"previous_page_url":null,"previous_page_before_item":null,"data":[{"object":"commission","url":"https://api.comecero.com/api/v1/commissions/1102611073852CMr8Wd1Nh","commission_id":"1102611073852CMr8Wd1Nh","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:10Z","test":true,"total":99.95,"currency":"USD","type":"product_sales","description":null,"transaction_type":"payment","transaction":"https://api.comecero.com/api/v1/payments/1102611073840PAz3Tq9Xc","accounting_id":"C-AB1234P261130USD"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/commissions/{commission_id}":{"get":{"operationId":"get_commission","summary":"Get a commission","description":"Gets one commission. Send `expand=transaction` to get the payment or refund it is for. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["commissions"],"parameters":[{"name":"commission_id","in":"path","required":true,"description":"The commission id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The commission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/commission"},"example":{"object":"commission","url":"https://api.comecero.com/api/v1/commissions/1102611073852CMr8Wd1Nh","commission_id":"1102611073852CMr8Wd1Nh","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:10Z","test":true,"total":99.95,"currency":"USD","type":"product_sales","description":null,"transaction_type":"payment","transaction":"https://api.comecero.com/api/v1/payments/1102611073840PAz3Tq9Xc","accounting_id":"C-AB1234P261130USD"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/countries":{"get":{"summary":"List countries","operationId":"list_countries","description":"Lists every country Comecero knows, sorted by name, with its currency and what an address form needs (postal code, states). Use it to build country and state pickers.\n\nThis needs no token. Every country comes in one response, so there is no paging.","tags":["countries"],"security":[{}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"Every country.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/country_list"},"example":{"object":"list","has_more":false,"total_count":1,"data":[{"name":"Canada","code":"CA","currency_code":"CAD","currency_code_alternate":null,"default_locale":"en-CA","is_eu":false,"has_postal_code":true,"requires_state_prov":true,"state_taxes":true,"states":[{"name":"Alberta","code":"AB"}]}]}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/countries/{code}":{"get":{"summary":"Get a country","operationId":"get_country","description":"Gets one country by its two-letter code, in any case. This needs no token.","tags":["countries"],"security":[{}],"parameters":[{"name":"code","in":"path","description":"The ISO 3166-1 alpha-2 country code, such as `US` or `de`.","required":true,"schema":{"type":"string"},"example":"CA"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The country.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/country"},"example":{"name":"Canada","code":"CA","currency_code":"CAD","currency_code_alternate":null,"default_locale":"en-CA","is_eu":false,"has_postal_code":true,"requires_state_prov":true,"state_taxes":true,"states":[{"name":"Alberta","code":"AB"},{"name":"British Columbia","code":"BC"}]}}}},"404":{"description":"No country has this code. This error body is shorter than the usual one: it has only `type`, `code` and `message`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["not_found"]},"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}}}}},"example":{"error":{"type":"not_found","code":"not_found","message":"No country with code 'XX'."}}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/customers":{"get":{"operationId":"list_customers","summary":"List customers","description":"Lists the customers of your account, oldest first. Search with `q` and filter by date or by whether the customer has paid.\n\nThe list is cursor-based: follow `next_page_url`, or send `after_item` or `before_item`. It does not take `sort_by`; use `date_type` with `desc`.\n\nSecret tokens only. A limited token cannot list customers.","tags":["customers"],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/after_item"},{"$ref":"#/components/parameters/before_item"},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/date_start"},{"$ref":"#/components/parameters/date_end"},{"name":"date_type","in":"query","required":false,"description":"Which date `date_start`, `date_end` and the order of the list use.","schema":{"type":"string","enum":["date_created","date_modified"],"default":"date_created"}},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"name":"q","in":"query","required":false,"description":"Search text. Matches part of the name or company name, or the whole email, customer id or username.","schema":{"type":"string"}},{"name":"has_payments","in":"query","required":false,"description":"`true` for only customers who have made a successful payment, `false` for only those who have not.","schema":{"type":"boolean"}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of customers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/customer_list"},"example":{"next_page_url":"https://api.comecero.com/api/v1/customers?after_item=0091304300408CuoxY9Pf3","next_page_after_item":"0091304300408CuoxY9Pf3","previous_page_url":null,"previous_page_before_item":null,"current_page_url":"https://api.comecero.com/api/v1/customers?limit=1","data":[{"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":null,"billing_address":{"object":"address","name":"John Doe","address_1":"123 Main St.","address_2":null,"city":"New York","state_prov":"NY","postal_code":"10019","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":null,"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","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"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"The `after_item` or `before_item` customer does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}}},"post":{"operationId":"create_customer","summary":"Create a customer","description":"Creates a customer. Every field is optional, so you can send an empty body and fill the customer in later. Give the customer a `username` and `password` so they can sign in later (see Log in a customer).\n\nSecret and limited tokens. A customer created with a limited token is tied to that token, so it can read and update the customer. A limited token cannot set `tax_exempt`.\n\nYou cannot add cards here: save them with Add a payment method, or with a payment that has `save: true`. Sending `cards` is a `400`. No email is sent and no event fires.","x-limited":true,"tags":["customers"],"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/customer_request"},"examples":{"minimal":{"summary":"Name and email","value":{"name":"John Doe","email":"john@example.com"}},"full":{"summary":"With an address and a sign-in","value":{"name":"John Doe","email":"john@example.com","phone":"555-555-0123","billing_address":{"name":"John Doe","address_1":"123 Main St.","city":"New York","state_prov":"NY","postal_code":"10019","country":"US"},"username":"johndoe","password":"s3cret-pass"}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new customer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/customer"},"example":{"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":"123 Main St.","address_2":null,"city":"New York","state_prov":"NY","postal_code":"10019","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"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"The username is taken by another customer of the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"422":{"description":"The EU VAT number could not be checked right now. Try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}}}},"/customers/login":{"post":{"operationId":"login_customer","summary":"Log in a customer","description":"Signs a customer in with the `username` and `password` set on the customer. Three ways to call it:\n\n- With a limited token: on success that token is tied to the customer. It\n  can then read and change the customer, their payment methods, orders,\n  subscriptions and invoices, and use `me` as the customer id. No new\n  token is returned.\n\n- With no token: send `account_id` (and `test=true` for a test customer)\n  in the query. A new limited token for the customer comes back in\n  `auth`.\n\n- With a secret token: you must send the shopper's `user_ip_address` in\n  the query, and the token needs permission to create auths and update\n  customers. A new limited token for the customer comes back in `auth`.\n\n\nEvery attempt waits about half a second. After too many failed attempts the customer is locked out for 10 minutes (`401`).","x-limited":true,"tags":["customers"],"security":[{},{"bearer":[]}],"parameters":[{"name":"account_id","in":"query","required":false,"description":"The account the customer belongs to. Required when you send no token. Not allowed with a token.","schema":{"type":"string"}},{"name":"test","in":"query","required":false,"description":"`true` to sign in a test customer. Only when you send no token; with a token, its mode is used and sending `test` is a `400`.","schema":{"type":"boolean","default":false}},{"$ref":"#/components/parameters/user_ip_address"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/customer_login_request"},"examples":{"login":{"summary":"Sign a customer in","value":{"username":"johndoe","password":"s3cret-pass"}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The customer. With no token or a secret token, `auth` holds the new limited token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/customer_login"},"example":{"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":null,"billing_address":{"object":"address","name":"John Doe","address_1":"123 Main St.","address_2":null,"city":"New York","state_prov":"NY","postal_code":"10019","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","auth":{"object":"auth","url":"https://api.comecero.com/api/v1/auths/5d1f0c3e9b7a4f2e8c6d1a0b3e5f7a9c","auth_id":"5d1f0c3e9b7a4f2e8c6d1a0b3e5f7a9c","test":true,"account_id":"AB1234","account_alias":"example-shop","type":"limited","ip_address":"203.0.113.10","token":"lt_test_example_token","expires":"2026-11-03T18:20:00Z","expires_in_seconds":86400,"date_last_used":null,"comments":null,"date_created":"2026-11-02T18:20:00Z","date_modified":"2026-11-02T18:20:00Z","customer":"https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3","roles":null,"permissions":null,"effective_permissions":[]}}}}},"400":{"description":"The body is missing or not JSON, the username or password is empty, `account_id` or `test` is missing, invalid or not allowed, or a secret token was sent without `user_ip_address`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"401":{"description":"The username or password is wrong (`invalid_login`), or the customer is locked for 10 minutes after too many failed attempts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/customers/send_link":{"post":{"operationId":"send_customer_link","summary":"Email a sign-in link","description":"Emails a customer a link that signs them in to your app without a password, for example to see past orders and downloads. The customer is found by email address. When several customers of the account have that email, the newest gets the link and the email offers the others too (up to 10).\n\nThe link opens `https://<your app host>/link` and works for 4 hours. The account needs an app host in its technical settings and a notification set up for customer links, or the call fails with `422`.\n\nNo token is needed. Every input is in the query string; there is no body.","tags":["customers"],"security":[{}],"parameters":[{"name":"account_id","in":"query","required":true,"description":"The account the customer belongs to.","schema":{"type":"string"}},{"name":"app_id","in":"query","required":true,"description":"The id of an app installed on the account. The link signs the customer in to it.","schema":{"type":"string"}},{"name":"email","in":"query","required":true,"description":"The customer's email address. Must match a customer's email exactly (not case sensitive).","schema":{"type":"string","format":"email"}},{"name":"redirect_uri","in":"query","required":false,"description":"A relative path in the app to open after sign-in, for example `/orders`. A full URL with `https://` is a `400`.","schema":{"type":"string"}},{"name":"test","in":"query","required":false,"description":"`true` to look up a test customer.","schema":{"type":"boolean","default":false}},{"name":"date_start","in":"query","required":false,"description":"Only consider customers created on or after this date (ISO 8601).","schema":{"type":"string"}},{"name":"date_end","in":"query","required":false,"description":"Only consider customers created on or before this date (ISO 8601).","schema":{"type":"string"}},{"name":"date_type","in":"query","required":false,"description":"Which customer date `date_start` and `date_end` use.","schema":{"type":"string","enum":["date_created","date_modified"],"default":"date_created"}}],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The link was sent. There is no body."},"400":{"description":"A required parameter is missing or invalid, the app is not installed on the account, `redirect_uri` is not relative, or no customer has that email.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"422":{"description":"The account has no app host, or no notification is set up to send customer links.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}}}},"/customers/{customer_id}":{"get":{"operationId":"get_customer","summary":"Get a customer","description":"Gets one customer. Use `expand` to include the customer's `payment_methods`, `payments`, `refunds`, `orders`, `subscriptions`, `invoices` or `balance` in full.\n\nSecret tokens, and limited tokens tied to the customer. With a token from a customer login, send `me` as the id.","x-limited":true,"tags":["customers"],"parameters":[{"name":"customer_id","in":"path","required":true,"description":"The id of the customer. With a limited token from a customer login you can send `me` instead.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The customer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/customer"},"example":{"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":"123 Main St.","address_2":null,"city":"New York","state_prov":"NY","postal_code":"10019","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"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"update_customer","summary":"Update a customer","description":"Changes a customer. Only the fields you send change; send an address as `null` to clear it. Changing the country or VAT number can change whether tax is charged on the customer's next cart, invoice or renewal.\n\nSecret tokens, and limited tokens tied to the customer. A limited token cannot set `tax_exempt`. No email is sent and no event fires.","x-limited":true,"tags":["customers"],"parameters":[{"name":"customer_id","in":"path","required":true,"description":"The id of the customer. With a limited token from a customer login you can send `me` instead.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/customer_request"},"example":{"phone":"555-555-0199","shipping_address":{"name":"John Doe","address_1":"500 5th Ave.","city":"New York","postal_code":"10110","country":"US"}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The updated customer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/customer"},"example":{"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":"123 Main St.","address_2":null,"city":"New York","state_prov":"NY","postal_code":"10019","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"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The username is taken by another customer of the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"422":{"description":"The EU VAT number could not be checked right now. Try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}}}},"/customers/{customer_id}/balance":{"get":{"operationId":"get_customer_balance","summary":"Get a customer's balance","description":"Gets a customer's store credit. The amount can be negative, for example after a refund paid to the balance was taken back. That is expected and is covered by the next credit. A customer who never had store credit has a balance of `0` in `USD`.\n\nSend `currency` to see the amount in another currency, converted at the account's exchange rate. Send `expand=transactions` to include the transactions.\n\nSecret tokens, and limited tokens tied to the customer.","x-limited":true,"tags":["customers"],"parameters":[{"name":"customer_id","in":"path","required":true,"description":"The id of the customer. With a limited token from a customer login you can send `me` instead.","schema":{"type":"string"}},{"name":"currency","in":"query","required":false,"description":"A three-letter ISO 4217 currency code to show the amount in, for example `EUR`.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The customer's balance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/customer_balance"},"example":{"object":"customer_balance","url":"https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/balance","customer_id":"0091304300408CuoxY9Pf3","account_id":"AB1234","test":true,"amount":25,"currency":"USD","date_last_transaction":"2026-11-04T15:02:11Z","transactions":"https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/balance/transactions"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/customers/{customer_id}/balance/payments":{"post":{"operationId":"create_customer_balance_payment","summary":"Add store credit by payment","description":"Takes a payment from the customer and adds it to their store credit. This is the same as Create a payment: the body is a payment, and Comecero reads the customer from the body, not from the URL. To add the money to the balance, send `apply_to_balance: true` and the customer (`customer_id` or `customer`) in the body. The credit is added when the payment is captured, in the payment's currency converted to the balance currency.\n\nThe payment cannot use `customer_account_balance` as its payment method. Money moves and the usual payment events fire.\n\nSecret tokens, and limited tokens. The id in the URL may be `me` only with a token from a customer login.","x-limited":true,"tags":["customers"],"parameters":[{"name":"customer_id","in":"path","required":true,"description":"The id of the customer. With a limited token from a customer login you can send `me` instead.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_request"},"example":{"customer_id":"0091304300408CuoxY9Pf3","total":25,"currency":"USD","apply_to_balance":true,"payment_method":{"type":"credit_card","data":{"number":"4444555566661111","cvv":"123","exp_month":12,"exp_year":2028,"cardholder_name":"John Doe"}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment"},"example":{"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}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The payment is an exact copy of a successful payment made moments ago.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/customers/{customer_id}/balance/transactions":{"get":{"operationId":"list_customer_balance_transactions","summary":"List balance transactions","description":"Lists every change to a customer's store credit, oldest first: credit added by refunds and top-up payments, and credit spent or taken back. Each transaction shows the balance right after it.\n\nThe list is cursor-based: follow `next_page_url`, or send `after_item` or `before_item`. Filter by `date_start` and `date_end` (on `date_created`).\n\nSecret tokens, and limited tokens tied to the customer.","x-limited":true,"tags":["customers"],"parameters":[{"name":"customer_id","in":"path","required":true,"description":"The id of the customer. With a limited token from a customer login you can send `me` instead.","schema":{"type":"string"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/after_item"},{"$ref":"#/components/parameters/before_item"},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/date_start"},{"$ref":"#/components/parameters/date_end"},{"$ref":"#/components/parameters/timezone"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of balance transactions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/customer_balance_transaction_list"},"example":{"next_page_url":null,"next_page_after_item":null,"previous_page_url":null,"previous_page_before_item":null,"current_page_url":"https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/balance/transactions","data":[{"object":"customer_balance_transaction","url":"https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/balance/transactions/0093045112207CxAb12Cd3","customer_balance_transaction_id":"0093045112207CxAb12Cd3","customer_id":"0091304300408CuoxY9Pf3","account_id":"AB1234","test":true,"date_created":"2026-11-04T15:02:11Z","amount":25,"current_balance":25,"currency":"USD","transaction_amount":25,"transaction_currency":"USD","memo":null,"created_by":null,"payment":null,"refund":"https://api.comecero.com/api/v1/refunds/0093045112100ReQw34Er5"},{"object":"customer_balance_transaction","url":"https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/balance/transactions/0093046230511CxZz98Yy7","customer_balance_transaction_id":"0093046230511CxZz98Yy7","customer_id":"0091304300408CuoxY9Pf3","account_id":"AB1234","test":true,"date_created":"2026-11-05T09:41:03Z","amount":-10,"current_balance":15,"currency":"USD","transaction_amount":-10,"transaction_currency":"USD","memo":null,"created_by":null,"payment":"https://api.comecero.com/api/v1/payments/0093046230400PyMn56Bv8","refund":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/customers/{customer_id}/balance/transactions/{balance_transaction_id}":{"get":{"operationId":"get_customer_balance_transaction","summary":"Get a balance transaction","description":"Gets one change to a customer's store credit. Use `expand=payment` or `expand=refund` to include the payment or refund behind it.\n\nSecret tokens, and limited tokens tied to the customer.","x-limited":true,"tags":["customers"],"parameters":[{"name":"customer_id","in":"path","required":true,"description":"The id of the customer. With a limited token from a customer login you can send `me` instead.","schema":{"type":"string"}},{"name":"balance_transaction_id","in":"path","required":true,"description":"The id of the balance transaction (`customer_balance_transaction_id`).","schema":{"type":"string"}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The balance transaction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/customer_balance_transaction"},"example":{"object":"customer_balance_transaction","url":"https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/balance/transactions/0093045112207CxAb12Cd3","customer_balance_transaction_id":"0093045112207CxAb12Cd3","customer_id":"0091304300408CuoxY9Pf3","account_id":"AB1234","test":true,"date_created":"2026-11-04T15:02:11Z","amount":25,"current_balance":25,"currency":"USD","transaction_amount":25,"transaction_currency":"USD","memo":null,"created_by":null,"payment":null,"refund":"https://api.comecero.com/api/v1/refunds/0093045112100ReQw34Er5"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/customers/{customer_id}/invoices":{"get":{"operationId":"list_customer_invoices","summary":"List a customer's invoices","description":"Lists a customer's invoices, oldest first. The list is offset-based: follow `next_page_url` or send `offset`.\n\nSecret tokens, and limited tokens tied to the customer. A limited token never sees draft invoices, whatever `draft` says.","x-limited":true,"tags":["customers"],"parameters":[{"name":"customer_id","in":"path","required":true,"description":"The id of the customer. With a limited token from a customer login you can send `me` instead.","schema":{"type":"string"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/desc"},{"name":"sort_by","in":"query","required":false,"description":"The date to sort by.","schema":{"type":"string","default":"date_created","enum":["date_created","date_modified","date_completed"]}},{"name":"q","in":"query","required":false,"description":"An invoice id. Only that invoice is returned.","schema":{"type":"string"}},{"name":"open","in":"query","required":false,"description":"`true` for only open invoices, `false` for only closed ones.","schema":{"type":"boolean"}},{"name":"draft","in":"query","required":false,"description":"`true` for only drafts, `false` for only sent invoices. Secret tokens only.","schema":{"type":"boolean"}},{"name":"payment_status","in":"query","required":false,"description":"Only invoices with this payment status.","schema":{"type":"string","enum":["unpaid","scheduled","initiated","processing","pending","completed","failed","cancelled","refunded","retry"]}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of the customer's invoices.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoice_list_offset"},"example":{"total_items":0,"total_pages":0,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/invoices","data":[]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/customers/{customer_id}/orders":{"get":{"operationId":"list_customer_orders","summary":"List a customer's orders","description":"Lists a customer's orders, oldest first. The list is offset-based: follow `next_page_url` or send `offset`.\n\nSecret tokens, and limited tokens tied to the customer. This is how a signed-in customer sees their order history.","x-limited":true,"tags":["customers"],"parameters":[{"name":"customer_id","in":"path","required":true,"description":"The id of the customer. With a limited token from a customer login you can send `me` instead.","schema":{"type":"string"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/desc"},{"name":"sort_by","in":"query","required":false,"description":"The date to sort by.","schema":{"type":"string","default":"date_created","enum":["date_created","date_modified","date_completed"]}},{"name":"q","in":"query","required":false,"description":"An order id. Only that order is returned.","schema":{"type":"string"}},{"name":"payment_status","in":"query","required":false,"description":"Only orders with this payment status.","schema":{"type":"string","enum":["unpaid","scheduled","initiated","processing","pending","completed","failed","cancelled","refunded","retry"]}},{"name":"fulfilled","in":"query","required":false,"description":"`true` for only fulfilled orders, `false` for only those not yet fulfilled.","schema":{"type":"boolean"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of the customer's orders.","content":{"application/json":{"schema":{"type":"object","title":"customer_order_list","description":"An offset-based list of orders.","properties":{"total_items":{"type":"integer","description":"The number of orders in the whole list."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The page number of this page."},"next_page_url":{"type":["string","null"],"description":"The URL of the next page, or `null` on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or `null`."},"previous_page_url":{"type":["string","null"],"description":"The URL of the previous page, or `null` on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or `null`."},"current_page_url":{"type":"string","description":"The URL of this page."},"data":{"type":"array","description":"The orders on this page.","items":{"$ref":"#/components/schemas/order"}}},"required":["total_items","total_pages","current_page","next_page_url","next_page_offset","previous_page_url","previous_page_offset","current_page_url","data"]},"example":{"total_items":0,"total_pages":0,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/orders","data":[]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/customers/{customer_id}/payment_methods":{"get":{"operationId":"list_customer_payment_methods","summary":"List a customer's payment methods","description":"Lists the payment methods saved to a customer, oldest first. Every method comes back on one page: `limit`, `offset` and `sort_by` are not used here.\n\nCard and bank numbers are never returned, only masks, the last four digits and the brand.\n\nSecret tokens, and limited tokens tied to the customer.","x-limited":true,"tags":["customers"],"parameters":[{"name":"customer_id","in":"path","required":true,"description":"The id of the customer. With a limited token from a customer login you can send `me` instead.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The customer's payment methods.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_method_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/payment_methods","data":[{"url":"https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/payment_methods/0092503470929PmEP0ivO4","object":"payment_method","payment_method_id":"0092503470929PmEP0ivO4","date_created":"2026-11-02T18:20:31Z","date_modified":"2026-11-02T18:20:31Z","test":true,"type":"credit_card","data":{"object":"credit_card","mask":"4***********1111","fingerprint":"2321657x8123834dc21ea08f","exp_month":12,"exp_year":28,"cardholder_name":"John Doe","ending":"1111","type":"Visa","label":"Visa 1111","billing_address":{"object":"address","name":"John Doe","address_1":"123 Main St.","address_2":null,"city":"New York","state_prov":"NY","postal_code":"10019","country":"US","email":null,"meta":null}},"is_default":true,"date_last_used":"2026-11-02T18:20:31Z"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"create_customer_payment_method","summary":"Add a payment method","description":"Saves a card or US bank account to a customer. Comecero first checks it with a $0 payment at the gateway (in a currency guessed from the customer's location); if the check fails, nothing is saved and the call fails. The card number is vaulted and the security code is dropped.\n\nThe customer's first payment method becomes the default. Send `is_default: true` to make a later one the default.\n\nIf the account does not allow saved cards, this only works for a customer who already has a payment method on file (`409` otherwise). The same card or account twice is a `409`.\n\nSecret tokens, and limited tokens tied to the customer. Only a secret token can skip the check with `validate: false`.","x-limited":true,"tags":["customers"],"parameters":[{"name":"customer_id","in":"path","required":true,"description":"The id of the customer. With a limited token from a customer login you can send `me` instead.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_method_create_request"},"examples":{"card":{"summary":"Save a card","value":{"type":"credit_card","data":{"number":"4444555566661111","cvv":"123","exp_month":12,"exp_year":2030,"cardholder_name":"John Doe"}}},"default_with_address":{"summary":"Save a card as the default, with its billing address","value":{"type":"credit_card","data":{"number":"4444555566661111","cvv":"123","exp_month":12,"exp_year":2028,"cardholder_name":"John Doe","billing_address":{"name":"John Doe","address_1":"123 Main St.","city":"New York","state_prov":"NY","postal_code":"10019","country":"US"}},"is_default":true}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The saved payment method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_method"},"example":{"url":"https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/payment_methods/0092503470929PmEP0ivO4","object":"payment_method","payment_method_id":"0092503470929PmEP0ivO4","date_created":"2026-11-02T18:20:31Z","date_modified":"2026-11-02T18:20:31Z","test":true,"type":"credit_card","data":{"object":"credit_card","mask":"4***********1111","fingerprint":"2321657x8123834dc21ea08f","exp_month":12,"exp_year":28,"cardholder_name":"John Doe","ending":"1111","type":"Visa","label":"Visa 1111","billing_address":{"object":"address","name":"John Doe","address_1":"123 Main St.","address_2":null,"city":"New York","state_prov":"NY","postal_code":"10019","country":"US","email":null,"meta":null}},"is_default":true,"date_last_used":"2026-11-02T18:20:31Z"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The gateway declined the $0 check. Nothing was saved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The payment method is already saved to the customer, or the account does not allow saving payment methods.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}}}},"/customers/{customer_id}/payment_methods/{payment_method_id}":{"get":{"operationId":"get_customer_payment_method","summary":"Get a payment method","description":"Gets one payment method saved to a customer.\n\nSecret tokens, and limited tokens tied to the customer.","x-limited":true,"tags":["customers"],"parameters":[{"name":"customer_id","in":"path","required":true,"description":"The id of the customer. With a limited token from a customer login you can send `me` instead.","schema":{"type":"string"}},{"name":"payment_method_id","in":"path","required":true,"description":"The id of the payment method.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The payment method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_method"},"example":{"url":"https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/payment_methods/0092503470929PmEP0ivO4","object":"payment_method","payment_method_id":"0092503470929PmEP0ivO4","date_created":"2026-11-02T18:20:31Z","date_modified":"2026-11-02T18:20:31Z","test":true,"type":"credit_card","data":{"object":"credit_card","mask":"4***********1111","fingerprint":"2321657x8123834dc21ea08f","exp_month":12,"exp_year":28,"cardholder_name":"John Doe","ending":"1111","type":"Visa","label":"Visa 1111","billing_address":{"object":"address","name":"John Doe","address_1":"123 Main St.","address_2":null,"city":"New York","state_prov":"NY","postal_code":"10019","country":"US","email":null,"meta":null}},"is_default":true,"date_last_used":"2026-11-02T18:20:31Z"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"update_customer_payment_method","summary":"Update a payment method","description":"Changes a saved payment method. For a card you can change the expiry, cardholder name, label and billing address. A new expiry is also passed to the gateways that keep a copy of the card. The card number cannot change: add the new card instead. Send `is_default: true` to make this the default; the customer's other methods stop being the default.\n\nSecret tokens, and limited tokens tied to the customer.","x-limited":true,"tags":["customers"],"parameters":[{"name":"customer_id","in":"path","required":true,"description":"The id of the customer. With a limited token from a customer login you can send `me` instead.","schema":{"type":"string"}},{"name":"payment_method_id","in":"path","required":true,"description":"The id of the payment method.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_method_update_request"},"examples":{"make_default":{"summary":"Make it the default","value":{"is_default":true}},"new_expiry":{"summary":"New expiry date","value":{"is_default":true,"data":{"exp_month":3,"exp_year":2030}}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The updated payment method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_method"},"example":{"url":"https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/payment_methods/0092503470929PmEP0ivO4","object":"payment_method","payment_method_id":"0092503470929PmEP0ivO4","date_created":"2026-11-02T18:20:31Z","date_modified":"2026-11-02T18:20:31Z","test":true,"type":"credit_card","data":{"object":"credit_card","mask":"4***********1111","fingerprint":"2321657x8123834dc21ea08f","exp_month":12,"exp_year":28,"cardholder_name":"John Doe","ending":"1111","type":"Visa","label":"Visa 1111","billing_address":{"object":"address","name":"John Doe","address_1":"123 Main St.","address_2":null,"city":"New York","state_prov":"NY","postal_code":"10019","country":"US","email":null,"meta":null}},"is_default":true,"date_last_used":"2026-11-02T18:20:31Z"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"operationId":"delete_customer_payment_method","summary":"Delete a payment method","description":"Deletes a saved payment method. For a card, the number is also removed from the vault. This cannot be undone.\n\nA customer with an active or trial subscription must keep at least one payment method, so deleting the last one is a `409`. Cancel the subscriptions first.\n\nSecret tokens, and limited tokens tied to the customer.","x-limited":true,"tags":["customers"],"parameters":[{"name":"customer_id","in":"path","required":true,"description":"The id of the customer. With a limited token from a customer login you can send `me` instead.","schema":{"type":"string"}},{"name":"payment_method_id","in":"path","required":true,"description":"The id of the payment method.","schema":{"type":"string"}}],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The payment method was deleted. There is no body."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"It is the last payment method of a customer with an active or trial subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}}}},"/customers/{customer_id}/payments":{"get":{"operationId":"list_customer_payments","summary":"List a customer's payments","description":"Lists the payments made by a customer, oldest first. The list is offset-based: follow `next_page_url` or send `offset`.\n\nSecret tokens, and limited tokens tied to the customer (for example after Log in a customer).","x-limited":true,"tags":["customers"],"parameters":[{"name":"customer_id","in":"path","required":true,"description":"The id of the customer. With a limited token from a customer login you can send `me` instead.","schema":{"type":"string"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/desc"},{"name":"sort_by","in":"query","required":false,"description":"The date to sort by.","schema":{"type":"string","default":"date_created","enum":["date_created","date_modified","date_completed"]}},{"name":"status","in":"query","required":false,"description":"Only payments with this status.","schema":{"type":"string","enum":["unpaid","scheduled","initiated","processing","pending","completed","failed","cancelled","refunded","retry"]}},{"name":"reference","in":"query","required":false,"description":"Only payments with this `reference`.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of the customer's payments.","content":{"application/json":{"schema":{"type":"object","title":"customer_payment_list","description":"An offset-based list of payments.","properties":{"total_items":{"type":"integer","description":"The number of payments in the whole list."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The page number of this page."},"next_page_url":{"type":["string","null"],"description":"The URL of the next page, or `null` on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or `null`."},"previous_page_url":{"type":["string","null"],"description":"The URL of the previous page, or `null` on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or `null`."},"current_page_url":{"type":"string","description":"The URL of this page."},"data":{"type":"array","description":"The payments on this page.","items":{"$ref":"#/components/schemas/payment"}}},"required":["total_items","total_pages","current_page","next_page_url","next_page_offset","previous_page_url","previous_page_offset","current_page_url","data"]},"example":{"total_items":0,"total_pages":0,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/payments","data":[]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/customers/{customer_id}/refunds":{"get":{"operationId":"list_customer_refunds","summary":"List a customer's refunds","description":"Lists the refunds and chargebacks on a customer's payments, oldest first. The list is offset-based: follow `next_page_url` or send `offset`.\n\nSecret tokens, and limited tokens tied to the customer.","x-limited":true,"tags":["customers"],"parameters":[{"name":"customer_id","in":"path","required":true,"description":"The id of the customer. With a limited token from a customer login you can send `me` instead.","schema":{"type":"string"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/desc"},{"name":"sort_by","in":"query","required":false,"description":"The date to sort by.","schema":{"type":"string","default":"date_created","enum":["date_created","date_modified","date_completed"]}},{"name":"status","in":"query","required":false,"description":"Only refunds with this status, for example `completed` or `failed`.","schema":{"type":"string","enum":["unpaid","scheduled","initiated","processing","pending","completed","failed","cancelled","refunded","retry"]}},{"name":"is_chargeback","in":"query","required":false,"description":"`true` for only chargebacks, `false` for only refunds you made.","schema":{"type":"boolean"}},{"name":"reference","in":"query","required":false,"description":"Only refunds with this `reference`.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of the customer's refunds.","content":{"application/json":{"schema":{"type":"object","title":"customer_refund_list","description":"An offset-based list of refunds.","properties":{"total_items":{"type":"integer","description":"The number of refunds in the whole list."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The page number of this page."},"next_page_url":{"type":["string","null"],"description":"The URL of the next page, or `null` on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or `null`."},"previous_page_url":{"type":["string","null"],"description":"The URL of the previous page, or `null` on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or `null`."},"current_page_url":{"type":"string","description":"The URL of this page."},"data":{"type":"array","description":"The refunds on this page.","items":{"$ref":"#/components/schemas/refund"}}},"required":["total_items","total_pages","current_page","next_page_url","next_page_offset","previous_page_url","previous_page_offset","current_page_url","data"]},"example":{"total_items":0,"total_pages":0,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/refunds","data":[]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/customers/{customer_id}/subscriptions":{"get":{"operationId":"list_customer_subscriptions","summary":"List a customer's subscriptions","description":"Lists a customer's subscriptions, oldest first. The list is offset-based: follow `next_page_url` or send `offset`.\n\nSecret tokens, and limited tokens tied to the customer.","x-limited":true,"tags":["customers"],"parameters":[{"name":"customer_id","in":"path","required":true,"description":"The id of the customer. With a limited token from a customer login you can send `me` instead.","schema":{"type":"string"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/desc"},{"name":"sort_by","in":"query","required":false,"description":"The date to sort by.","schema":{"type":"string","default":"date_created","enum":["date_created","date_modified","date_ended","date_current_period_start","date_current_period_end"]}},{"name":"q","in":"query","required":false,"description":"A subscription id. Only that subscription is returned.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Only subscriptions with this status.","schema":{"type":"string","enum":["active","trial","cancelled","completed"]}},{"name":"in_grace_period","in":"query","required":false,"description":"`true` for only subscriptions in their grace period after a failed renewal.","schema":{"type":"boolean"}},{"name":"terminated","in":"query","required":false,"description":"`true` for only ended subscriptions (`cancelled` or `completed`), `false` for only running ones (`active` or `trial`).","schema":{"type":"boolean"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of the customer's subscriptions.","content":{"application/json":{"schema":{"type":"object","title":"customer_subscription_list","description":"An offset-based list of subscriptions.","properties":{"total_items":{"type":"integer","description":"The number of subscriptions in the whole list."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The page number of this page."},"next_page_url":{"type":["string","null"],"description":"The URL of the next page, or `null` on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or `null`."},"previous_page_url":{"type":["string","null"],"description":"The URL of the previous page, or `null` on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or `null`."},"current_page_url":{"type":"string","description":"The URL of this page."},"data":{"type":"array","description":"The subscriptions on this page.","items":{"$ref":"#/components/schemas/subscription"}}},"required":["total_items","total_pages","current_page","next_page_url","next_page_offset","previous_page_url","previous_page_offset","current_page_url","data"]},"example":{"total_items":0,"total_pages":0,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/subscriptions","data":[]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"create_customer_subscription","summary":"Create a subscription","description":"Starts a subscription for a customer without a cart or invoice. The customer must already have a saved payment method.\n\nSecret tokens only. A limited token cannot create subscriptions.","tags":["customers"],"parameters":[{"name":"customer_id","in":"path","required":true,"description":"The id of the customer. With a limited token from a customer login you can send `me` instead.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_request"},"examples":{"subscription":{"summary":"Start a subscription","value":{"subscription_plan_id":"0093472113202Spzs4AV8C","currency":"USD","items":[{"product_id":"widget-pro.test","quantity":1}]}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription"},"example":{"object":"subscription","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_id":"0093799318129SuLByRPW8","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-11-02T15:21:31Z","test":true,"account_id":"AB1234","status":"active","in_grace_period":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"billing_count":2,"end_at_billing_count":null,"currency":"USD","items":[{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}],"shipping_method_id":null,"date_trial_start":null,"date_trial_end":null,"date_current_period_start":"2026-11-02T15:21:28Z","date_current_period_end":"2026-12-02T15:21:28Z","date_next_renewal_notification":"2026-11-29T15:21:28Z","date_cancelled":null,"cancellation_reason":null,"cancel_at_current_period_end":false,"date_ended":null,"add_at_current_period_end":[],"subscription_plan":"https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C","customer":"https://api.comecero.com/api/v1/customers/0093799288003CuGOip8X9","invoices":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/invoices","history":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/history","meta":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"The customer has no saved payment method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}}}},"/downloads":{"get":{"summary":"List downloads","operationId":"list_downloads","description":"Returns your download links, oldest first unless you send `desc=true`. Secret and trusted tokens may call it.","tags":["downloads"],"parameters":[{"$ref":"#/components/parameters/after_item"},{"$ref":"#/components/parameters/before_item"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/date_start"},{"$ref":"#/components/parameters/date_end"},{"name":"date_type","in":"query","description":"Which date `date_start` and `date_end` filter on. The default is `date_created`.","schema":{"type":"string","enum":["date_created","date_modified"]}},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"name":"q","in":"query","description":"A download id. Returns only that download.","schema":{"type":"string"}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of downloads.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/download_list"},"example":{"next_page_url":null,"next_page_after_item":null,"previous_page_url":null,"previous_page_before_item":null,"data":[{"object":"download","url":"https://api.comecero.com/api/v1/downloads/0142130710600DoT3ka9Lm","download_id":"0142130710600DoT3ka9Lm","date_created":"2026-11-02T00:45:12Z","date_modified":"2026-11-02T00:45:12Z","test":true,"account_id":"AB1234","file":"https://api.comecero.com/api/v1/files/0095012700001FiQ2xT7Ab","order":"https://api.comecero.com/api/v1/orders/6622-NXKHE-858","product":"https://api.comecero.com/api/v1/products/widget-pro.test","link":"https://cdn.comecero.net/sd/0142130710600DoT3ka9Lm/1/3fa9c2d1/widget-pro-setup.zip","link_short":"https://cdn.comecero.net/sd/0142130710600DoT3ka9Lm/1/3fa9c2d1/dl","filename":"widget-pro-setup.zip","bytes":24518301,"expired":false,"expires":"2026-11-09T00:45:12Z","expires_in_clicks":10,"clicks":1}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/downloads/{download_id}":{"get":{"summary":"Get a download","operationId":"get_download","description":"Returns one download link. A limited token may read it only when the download is bound to the token, such as a download on the signed-in customer's order; it does not get the limits or the file. Secret, trusted and limited tokens may call it.","tags":["downloads"],"x-limited":true,"parameters":[{"name":"download_id","in":"path","required":true,"description":"The download id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The download.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/download"},"example":{"object":"download","url":"https://api.comecero.com/api/v1/downloads/0142130710600DoT3ka9Lm","download_id":"0142130710600DoT3ka9Lm","date_created":"2026-11-02T00:45:12Z","date_modified":"2026-11-02T00:45:12Z","test":true,"account_id":"AB1234","file":"https://api.comecero.com/api/v1/files/0095012700001FiQ2xT7Ab","order":"https://api.comecero.com/api/v1/orders/6622-NXKHE-858","product":"https://api.comecero.com/api/v1/products/widget-pro.test","link":"https://cdn.comecero.net/sd/0142130710600DoT3ka9Lm/1/3fa9c2d1/widget-pro-setup.zip","link_short":"https://cdn.comecero.net/sd/0142130710600DoT3ka9Lm/1/3fa9c2d1/dl","filename":"widget-pro-setup.zip","bytes":24518301,"expired":false,"expires":"2026-11-09T00:45:12Z","expires_in_clicks":10,"clicks":1}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Update a download","operationId":"update_download","description":"Changes the limits of a download link, for example to give a customer more clicks or more time. Send only the fields you want to change. To start the limits over from the file's defaults, use the reset action. Secret and trusted tokens may call it.","tags":["downloads"],"parameters":[{"name":"download_id","in":"path","required":true,"description":"The download id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"description":"The fields to change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/download_request"},"example":{"expires_in_clicks":20}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The updated download.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/download"},"example":{"object":"download","url":"https://api.comecero.com/api/v1/downloads/0142130710600DoT3ka9Lm","download_id":"0142130710600DoT3ka9Lm","date_created":"2026-11-02T00:45:12Z","date_modified":"2026-11-02T00:45:12Z","test":true,"account_id":"AB1234","file":"https://api.comecero.com/api/v1/files/0095012700001FiQ2xT7Ab","order":"https://api.comecero.com/api/v1/orders/6622-NXKHE-858","product":"https://api.comecero.com/api/v1/products/widget-pro.test","link":"https://cdn.comecero.net/sd/0142130710600DoT3ka9Lm/1/3fa9c2d1/widget-pro-setup.zip","link_short":"https://cdn.comecero.net/sd/0142130710600DoT3ka9Lm/1/3fa9c2d1/dl","filename":"widget-pro-setup.zip","bytes":24518301,"expired":false,"expires":"2026-11-09T00:45:12Z","expires_in_clicks":10,"clicks":1}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/downloads/{download_id}/kill":{"post":{"summary":"Stop a download","operationId":"kill_download","description":"Stops a download link at once: it is set to have expired yesterday with no clicks allowed, so `expired` becomes true. Use it after a refund or when a link was shared. You can turn it back on with the reset action. No request body. Secret and trusted tokens may call it.","tags":["downloads"],"parameters":[{"name":"download_id","in":"path","required":true,"description":"The download id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The download, no longer working.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/download"},"example":{"object":"download","url":"https://api.comecero.com/api/v1/downloads/0142130710600DoT3ka9Lm","download_id":"0142130710600DoT3ka9Lm","date_created":"2026-11-02T00:45:12Z","date_modified":"2026-11-02T00:45:12Z","test":true,"account_id":"AB1234","file":"https://api.comecero.com/api/v1/files/0095012700001FiQ2xT7Ab","order":"https://api.comecero.com/api/v1/orders/6622-NXKHE-858","product":"https://api.comecero.com/api/v1/products/widget-pro.test","link":"https://cdn.comecero.net/sd/0142130710600DoT3ka9Lm/1/3fa9c2d1/widget-pro-setup.zip","link_short":"https://cdn.comecero.net/sd/0142130710600DoT3ka9Lm/1/3fa9c2d1/dl","filename":"widget-pro-setup.zip","bytes":24518301,"expired":false,"expires":"2026-11-09T00:45:12Z","expires_in_clicks":10,"clicks":1}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/downloads/{download_id}/reset":{"post":{"summary":"Reset a download","operationId":"reset_download","description":"Starts a download link over: clicks go back to 0, and the expiry and click limit are set again from the file's `expires_in_days` and `expires_in_clicks`, counted from now. Use it when a customer could not finish a download in time. No request body. Secret and trusted tokens may call it.","tags":["downloads"],"parameters":[{"name":"download_id","in":"path","required":true,"description":"The download id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The download, working again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/download"},"example":{"object":"download","url":"https://api.comecero.com/api/v1/downloads/0142130710600DoT3ka9Lm","download_id":"0142130710600DoT3ka9Lm","date_created":"2026-11-02T00:45:12Z","date_modified":"2026-11-02T00:45:12Z","test":true,"account_id":"AB1234","file":"https://api.comecero.com/api/v1/files/0095012700001FiQ2xT7Ab","order":"https://api.comecero.com/api/v1/orders/6622-NXKHE-858","product":"https://api.comecero.com/api/v1/products/widget-pro.test","link":"https://cdn.comecero.net/sd/0142130710600DoT3ka9Lm/1/3fa9c2d1/widget-pro-setup.zip","link_short":"https://cdn.comecero.net/sd/0142130710600DoT3ka9Lm/1/3fa9c2d1/dl","filename":"widget-pro-setup.zip","bytes":24518301,"expired":false,"expires":"2026-11-09T00:45:12Z","expires_in_clicks":10,"clicks":1}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/event_subscriptions":{"get":{"operationId":"list_event_subscriptions","summary":"List event subscriptions","description":"Lists your event subscriptions (webhooks). Subscriptions made by an installed app are not listed. The list is offset-based. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["event_subscriptions"],"parameters":[{"name":"active","in":"query","required":false,"description":"`true` for active subscriptions only, `false` for inactive ones only.","schema":{"type":"boolean"}},{"name":"q","in":"query","required":false,"description":"An exact event subscription id, or an event type such as `order:created`.","schema":{"type":"string"}},{"name":"sort_by","in":"query","required":false,"description":"The field to sort by. Any other value uses the default.","schema":{"type":"string","enum":["date_created","date_modified","event_type"],"default":"date_created"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of event subscriptions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/event_subscription_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/event_subscriptions","data":[{"object":"event_subscription","url":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","event_subscription_id":"1102610913420ES4f9QmLp","date_created":"2026-11-07T14:20:03Z","date_modified":"2026-11-07T14:20:03Z","test":true,"active":true,"account_id":"AB1234","event_type":"order:created","destination":"https://example.com/webhooks/comecero","format":"json","method":"http","timezone":null,"signature_key":null,"expand":"customer","show":null,"hide":null,"http_authorization_username":null,"http_authorization_password":null,"custom_header_name":null,"custom_header_value":null,"environment_variables":{},"comments":"Order sync"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"create_event_subscription","summary":"Create an event subscription","description":"Adds a webhook: from now on, each event of `event_type` is sent to `destination` by HTTP POST or email. Send `active: true`, because a new subscription is inactive by default. It only receives events of the mode of your token (test or live). Making one fires the `event_subscription:created` event. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["event_subscriptions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event_subscription_request"},{"required":["event_type","method","format","destination"]}]},"examples":{"minimal":{"summary":"Send order:created to your server","value":{"event_type":"order:created","method":"http","format":"json","destination":"https://example.com/webhooks/comecero","active":true}},"full":{"summary":"With expand and environment variables","value":{"event_type":"order:created","active":true,"method":"http","format":"json","destination":"https://example.com/webhooks/comecero","expand":"customer","environment_variables":{"store":"main"},"comments":"Order sync"}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new event subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/event_subscription"},"example":{"object":"event_subscription","url":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","event_subscription_id":"1102610913420ES4f9QmLp","date_created":"2026-11-07T14:20:03Z","date_modified":"2026-11-07T14:20:03Z","test":true,"active":true,"account_id":"AB1234","event_type":"order:created","destination":"https://example.com/webhooks/comecero","format":"json","method":"http","timezone":null,"signature_key":null,"expand":"customer","show":null,"hide":null,"http_authorization_username":null,"http_authorization_password":null,"custom_header_name":null,"custom_header_value":null,"environment_variables":{"store":"main"},"comments":"Order sync"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/event_subscriptions/{event_subscription_id}":{"get":{"operationId":"get_event_subscription","summary":"Get an event subscription","description":"Gets one event subscription, including its `signature_key` and HTTP authorization details. One made by an installed app answers `403`. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["event_subscriptions"],"parameters":[{"name":"event_subscription_id","in":"path","required":true,"description":"The event subscription id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The event subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/event_subscription"},"example":{"object":"event_subscription","url":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","event_subscription_id":"1102610913420ES4f9QmLp","date_created":"2026-11-07T14:20:03Z","date_modified":"2026-11-07T14:20:03Z","test":true,"active":true,"account_id":"AB1234","event_type":"order:created","destination":"https://example.com/webhooks/comecero","format":"json","method":"http","timezone":null,"signature_key":null,"expand":"customer","show":null,"hide":null,"http_authorization_username":null,"http_authorization_password":null,"custom_header_name":null,"custom_header_value":null,"environment_variables":{"store":"main"},"comments":"Order sync"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"update_event_subscription","summary":"Update an event subscription","description":"Changes the fields you send and leaves the others as they are. Send `active: false` to pause deliveries. Events already made keep the data they were made with, but are sent with the subscription's current destination and settings. Fires the `event_subscription:modified` event. Answers `201`, not `200`. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["event_subscriptions"],"parameters":[{"name":"event_subscription_id","in":"path","required":true,"description":"The event subscription id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/event_subscription_request"},"example":{"active":false}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The updated event subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/event_subscription"},"example":{"object":"event_subscription","url":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","event_subscription_id":"1102610913420ES4f9QmLp","date_created":"2026-11-07T14:20:03Z","date_modified":"2026-11-07T14:20:03Z","test":true,"active":true,"account_id":"AB1234","event_type":"order:created","destination":"https://example.com/webhooks/comecero","format":"json","method":"http","timezone":null,"signature_key":null,"expand":"customer","show":null,"hide":null,"http_authorization_username":null,"http_authorization_password":null,"custom_header_name":null,"custom_header_value":null,"environment_variables":{"store":"main"},"comments":"Order sync"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"operationId":"delete_event_subscription","summary":"Delete an event subscription","description":"Deletes the event subscription. No new events are made for it. Fires the `event_subscription:deleted` event. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["event_subscriptions"],"parameters":[{"name":"event_subscription_id","in":"path","required":true,"description":"The event subscription id.","schema":{"type":"string"}}],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The event subscription was deleted. There is no body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/event_subscriptions/{event_subscription_id}/test/{event_test_template_id}":{"post":{"operationId":"test_event_subscription","summary":"Send a test event","description":"Sends one sample event to the subscription's destination now and says whether it got through. The sample `data` comes from an event test template: a saved example payload for one event type, either one of Comecero's or one made in the dashboard (Developer, Event Subscriptions). The template's event type must match the subscription's `event_type` (`400`). The event is signed and shaped like a real one (`show` and `hide` apply; `expand` does not, since the sample is sent as saved), but it is not saved, so it is not in `/events` and is never retried. It is sent even when the subscription is inactive. No body is needed. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["event_subscriptions"],"parameters":[{"name":"event_subscription_id","in":"path","required":true,"description":"The event subscription id.","schema":{"type":"string"}},{"name":"event_test_template_id","in":"path","required":true,"description":"The id of the event test template whose sample payload to send.","schema":{"type":"string"}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The result of the attempt. A `200` means the attempt was made: read `success`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/event_subscription_test_result"},"example":{"success":false,"error":"There was a problem contacting the remote server: HTTP Status Code: 404, Response Content (preview of first 500 characters): Not Found","event_id":"1102611204410EVn3Rk8Wd","event_type":"order:created"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/events":{"get":{"operationId":"list_events","summary":"List events","description":"Lists the events made for your event subscriptions, one per subscription per occurrence. With no `status`, only `delivered` events are listed: send `status=retry` or `status=failed` to find deliveries that did not get through. Events are kept for 30 days after their last change, and for 7 days once delivered or in test mode. The list is cursor-based and sorted by `date_created`. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["events"],"parameters":[{"name":"status","in":"query","required":false,"description":"Only events with this delivery status. The default is `delivered`.","schema":{"type":"string","enum":["queued","delivered","retry","failed"],"default":"delivered"}},{"name":"q","in":"query","required":false,"description":"An exact event id. Only that event is returned, and only when it also matches `status`. Send `status` with it, because an event is not found by `q` alone. Anything that is not an event id returns an empty list.","schema":{"type":"string"}},{"name":"debug","in":"query","required":false,"description":"When `true`, each event also has `retry_count`, `date_last_delivery_attempt`, `date_next_delivery_attempt` and `debug` (why the last attempt failed).","schema":{"type":"boolean","default":false}},{"$ref":"#/components/parameters/date_start"},{"$ref":"#/components/parameters/date_end"},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/after_item"},{"$ref":"#/components/parameters/before_item"},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of events.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/event_list"},"example":{"next_page_url":null,"next_page_after_item":null,"previous_page_url":null,"previous_page_before_item":null,"data":[{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"order:created","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"failed","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-08T21:02:44Z","environment_variables":{},"data":{"object":"order","order_id":"7393-GMRFY-954","total":99.95,"currency":"USD"}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/events/{event_id}":{"get":{"operationId":"get_event","summary":"Get an event","description":"Gets one event: its delivery status and the `data` that was or will be sent. Send `debug=true` to see why the last attempt failed. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["events"],"parameters":[{"name":"event_id","in":"path","required":true,"description":"The event id.","schema":{"type":"string"}},{"name":"debug","in":"query","required":false,"description":"When `true`, the event also has `retry_count`, `date_last_delivery_attempt`, `date_next_delivery_attempt` and `debug`.","schema":{"type":"boolean","default":false}},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The event.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/event"},"example":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"order:created","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"retry","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:34:12Z","environment_variables":{},"data":{"object":"order","order_id":"7393-GMRFY-954","total":99.95,"currency":"USD"},"retry_count":1,"date_last_delivery_attempt":"2026-11-07T14:34:12Z","date_next_delivery_attempt":"2026-11-07T14:36:12Z","debug":"There was a problem contacting the remote server: HTTP Status Code: 503, Response Content (preview of first 500 characters): Service Unavailable"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"operationId":"delete_event","summary":"Delete an event","description":"Deletes an event so it is no longer listed. An event that was waiting for a retry is not sent again. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["events"],"parameters":[{"name":"event_id","in":"path","required":true,"description":"The event id.","schema":{"type":"string"}}],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The event was deleted. There is no body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/events/{event_id}/retry":{"post":{"operationId":"retry_event","summary":"Send an event again","description":"Sends the event to its event subscription now, with the same `event_id` and `data`, and answers with the event after the attempt. Check `status`: `delivered` if your server answered 2xx, otherwise `failed`. A failed manual attempt does not start automatic retries, but an event already waiting for a retry keeps its place in that queue. It uses the event subscription's current destination and settings. No body is needed. Events are kept for 30 days after their last change, and for 7 days once delivered or in test mode; after that the event is gone (`404`). Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["events"],"parameters":[{"name":"event_id","in":"path","required":true,"description":"The event id.","schema":{"type":"string"}},{"name":"debug","in":"query","required":false,"description":"When `true`, the answer includes `debug` with why the attempt failed.","schema":{"type":"boolean","default":false}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The event after the attempt. A `200` means the attempt was made, not that it got through: read `status`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/event"},"example":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"order:created","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T15:01:30Z","environment_variables":{},"data":{"object":"order","order_id":"7393-GMRFY-954","total":99.95,"currency":"USD"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/fees":{"get":{"operationId":"list_fees","summary":"List fees","description":"Lists the fees Comecero charged your account. The list is cursor-based and sorted by `date_type` (`date_created` by default). Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["fees"],"parameters":[{"name":"type","in":"query","required":false,"description":"Only fees of this type. Known issue: core currently returns no fees when you send `type`, so filter the list yourself for now.","schema":{"type":"string","enum":["payment_completed","refund_completed","auth","zero_auth","capture","void","decline","chargeback","fx_conversion","international_card","payout","platform_monthly","platform_annual","support_annual","miscellaneous"]}},{"name":"accounting_id","in":"query","required":false,"description":"Only fees in this billing period, such as `C-AB1234R261130USD`.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"An exact fee id.","schema":{"type":"string"}},{"name":"date_type","in":"query","required":false,"description":"Which date `date_start` and `date_end` filter and sort on.","schema":{"type":"string","enum":["date_created","date_modified"],"default":"date_created"}},{"$ref":"#/components/parameters/date_start"},{"$ref":"#/components/parameters/date_end"},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/after_item"},{"$ref":"#/components/parameters/before_item"},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of fees.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/fee_list"},"example":{"next_page_url":"https://api.comecero.com/api/v1/fees?after_item=1102611073850FEp6Vb2Qs&limit=1","next_page_after_item":"1102611073850FEp6Vb2Qs","previous_page_url":null,"previous_page_before_item":null,"data":[{"object":"fee","url":"https://api.comecero.com/api/v1/fees/1102611073850FEp6Vb2Qs","fee_id":"1102611073850FEp6Vb2Qs","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:10Z","test":true,"account_id":"AB1234","fixed_amount":0.3,"percentage":2.9,"percentage_amount":2.9,"total":3.2,"currency":"USD","type":"payment_completed","category":"transaction","collected":false,"description":"Payment completed","transaction_type":"payment","transaction":"https://api.comecero.com/api/v1/payments/1102611073840PAz3Tq9Xc","contract":null,"accounting_id":"C-AB1234R261130USD"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/fees/{fee_id}":{"get":{"operationId":"get_fee","summary":"Get a fee","description":"Gets one fee. Send `expand=transaction` to get the payment or refund it is on. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["fees"],"parameters":[{"name":"fee_id","in":"path","required":true,"description":"The fee id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The fee.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/fee"},"example":{"object":"fee","url":"https://api.comecero.com/api/v1/fees/1102611073850FEp6Vb2Qs","fee_id":"1102611073850FEp6Vb2Qs","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:10Z","test":true,"account_id":"AB1234","fixed_amount":0.3,"percentage":2.9,"percentage_amount":2.9,"total":3.2,"currency":"USD","type":"payment_completed","category":"transaction","collected":false,"description":"Payment completed","transaction_type":"payment","transaction":"https://api.comecero.com/api/v1/payments/1102611073840PAz3Tq9Xc","contract":null,"accounting_id":"C-AB1234R261130USD"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/files":{"get":{"summary":"List files","operationId":"list_files","description":"Returns your files, oldest first unless you choose another `sort_by`. Secret and trusted tokens may call it.","tags":["files"],"parameters":[{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/limit"},{"name":"sort_by","in":"query","description":"The field to sort by. The default is `date_created`.","schema":{"type":"string","enum":["date_created","date_modified","name","filename"]}},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"name":"q","in":"query","description":"Search text. An exact file id returns that file; otherwise files whose name or file name contains the text (any case) are returned.","schema":{"type":"string"}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of files.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/file_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/files?offset=0","data":[{"object":"file","url":"https://api.comecero.com/api/v1/files/0095012700001FiQ2xT7Ab","file_id":"0095012700001FiQ2xT7Ab","date_created":"2026-11-01T10:12:40Z","date_modified":"2026-11-01T10:12:40Z","test":true,"account_id":"AB1234","name":"Widget Pro installer","description":null,"filename":"widget-pro-setup.zip","bytes":24518301,"version":"2.1","expires_in_days":7,"expires_in_clicks":10}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Upload a file","operationId":"create_file","description":"Adds a file to sell as a download. The body must be `multipart/form-data`: send the file in a part named `file` (up to 200 MB), or send `file_url` for Comecero to fetch it (up to 500 MB live, 200 MB test). A JSON body is refused with `400`. Secret and trusted tokens may call it.","tags":["files"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"description":"The file and its settings.","content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/file_request"},"encoding":{"file":{"contentType":"application/octet-stream"}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new file.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/file"},"example":{"object":"file","url":"https://api.comecero.com/api/v1/files/0095012700001FiQ2xT7Ab","file_id":"0095012700001FiQ2xT7Ab","date_created":"2026-11-01T10:12:40Z","date_modified":"2026-11-01T10:12:40Z","test":true,"account_id":"AB1234","name":"Widget Pro installer","description":null,"filename":"widget-pro-setup.zip","bytes":24518301,"version":"2.1","expires_in_days":7,"expires_in_clicks":10}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"413":{"description":"The request body is larger than 200 MB."},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/files/{file_id}":{"get":{"summary":"Get a file","operationId":"get_file","description":"Returns one file. Secret and trusted tokens may call it.","tags":["files"],"parameters":[{"name":"file_id","in":"path","required":true,"description":"The file id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The file.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/file"},"example":{"object":"file","url":"https://api.comecero.com/api/v1/files/0095012700001FiQ2xT7Ab","file_id":"0095012700001FiQ2xT7Ab","date_created":"2026-11-01T10:12:40Z","date_modified":"2026-11-01T10:12:40Z","test":true,"account_id":"AB1234","name":"Widget Pro installer","description":null,"filename":"widget-pro-setup.zip","bytes":24518301,"version":"2.1","expires_in_days":7,"expires_in_clicks":10}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Update a file","operationId":"update_file","description":"Changes a file's settings, or replaces the file itself. The body must be `multipart/form-data`, like the upload. Send only the fields you want to change; empty fields are ignored, so a name or description cannot be cleared. A new `file` or `file_url` replaces the stored file. Secret and trusted tokens may call it.","tags":["files"],"parameters":[{"name":"file_id","in":"path","required":true,"description":"The file id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"description":"The fields to change.","content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/file_request"}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The updated file.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/file"},"example":{"object":"file","url":"https://api.comecero.com/api/v1/files/0095012700001FiQ2xT7Ab","file_id":"0095012700001FiQ2xT7Ab","date_created":"2026-11-01T10:12:40Z","date_modified":"2026-11-01T10:12:40Z","test":true,"account_id":"AB1234","name":"Widget Pro installer","description":null,"filename":"widget-pro-setup.zip","bytes":24518301,"version":"2.1","expires_in_days":7,"expires_in_clicks":10}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"description":"The request body is larger than 200 MB."},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"summary":"Delete a file","operationId":"delete_file","description":"Deletes a file and removes it from storage for good. Download links to it stop working. It is not checked whether products still use it, so remove it from your products first. Secret and trusted tokens may call it.","tags":["files"],"parameters":[{"name":"file_id","in":"path","required":true,"description":"The file id.","schema":{"type":"string"}}],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The file is deleted. No body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/files/{file_id}/downloads":{"post":{"summary":"Create a download","operationId":"create_download","description":"Makes a new download link to a file, for example to send a customer a file by hand. Comecero makes these on its own for each order item whose product has a file. The link's limits come from the file unless you send your own. The body is JSON and may be an empty object. The token needs the create permission on downloads. Secret and trusted tokens may call it.","tags":["downloads"],"parameters":[{"name":"file_id","in":"path","required":true,"description":"The file id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"description":"The limits of the new link. Send `{}` for the file's defaults.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/download_request"},"examples":{"file_limits":{"summary":"Use the file's own limits","value":{}},"own_limits":{"summary":"Set an expiry date and a click limit","value":{"expires":"2026-11-30T23:59:59Z","expires_in_clicks":5}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new download.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/download"},"example":{"object":"download","url":"https://api.comecero.com/api/v1/downloads/0142130710600DoT3ka9Lm","download_id":"0142130710600DoT3ka9Lm","date_created":"2026-11-02T00:45:12Z","date_modified":"2026-11-02T00:45:12Z","test":true,"account_id":"AB1234","file":"https://api.comecero.com/api/v1/files/0095012700001FiQ2xT7Ab","order":"https://api.comecero.com/api/v1/orders/6622-NXKHE-858","product":"https://api.comecero.com/api/v1/products/widget-pro.test","link":"https://cdn.comecero.net/sd/0142130710600DoT3ka9Lm/1/3fa9c2d1/widget-pro-setup.zip","link_short":"https://cdn.comecero.net/sd/0142130710600DoT3ka9Lm/1/3fa9c2d1/dl","filename":"widget-pro-setup.zip","bytes":24518301,"expired":false,"expires":"2026-11-09T00:45:12Z","expires_in_clicks":10,"clicks":1}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/fx/amount":{"get":{"summary":"Convert an amount","operationId":"convert_amount","description":"Converts an amount from one currency to another at today's rate, with the same rules your shop uses for prices (your markup and rounding in Settings, Pricing). Pass a `cart_id` or `invoice_id` to use the rate saved on that cart or invoice instead of today's.\n\nSecret and trusted tokens may call this. No permission is needed. Limited tokens are refused (`403`): use `GET /fx/product` in the browser.","tags":["foreign_exchange"],"parameters":[{"name":"amount","in":"query","description":"The amount to convert, in `from_currency`. Must be more than 0.","required":true,"schema":{"type":"number","exclusiveMinimum":0},"example":20},{"name":"from_currency","in":"query","description":"The ISO 4217 code of the currency of `amount`.","required":true,"schema":{"type":"string"},"example":"USD"},{"name":"to_currency","in":"query","description":"The ISO 4217 code of the currency to convert to.","required":true,"schema":{"type":"string"},"example":"EUR"},{"name":"cart_id","in":"query","description":"Use the exchange rate saved on this cart.","required":false,"schema":{"type":"string"}},{"name":"invoice_id","in":"query","description":"Use the exchange rate saved on this invoice.","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The converted amount.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/fx_amount"},"example":{"amount":18.4,"currency":"EUR"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/fx/product":{"get":{"summary":"Get a product price in a currency","operationId":"get_product_price","description":"Gets a product's price in one currency. When you set a price in that currency, you get it. Otherwise your default price is converted at today's rate with your markup and rounding. Pass a `cart_id` or `invoice_id` to use the rate saved on that cart or invoice.\n\nAny token may call this, including a limited token. No permission is needed.","tags":["foreign_exchange"],"x-limited":true,"parameters":[{"name":"product_id","in":"query","description":"The product to price.","required":true,"schema":{"type":"string"},"example":"widget"},{"name":"currency","in":"query","description":"The ISO 4217 code of the currency to price it in.","required":true,"schema":{"type":"string"},"example":"EUR"},{"name":"quantity","in":"query","description":"The quantity, so a volume price applies. The default is 1.","required":false,"schema":{"type":"number","default":1}},{"name":"cart_id","in":"query","description":"Use the exchange rate saved on this cart.","required":false,"schema":{"type":"string"}},{"name":"invoice_id","in":"query","description":"Use the exchange rate saved on this invoice.","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The product's price in the currency.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/fx_price"},"example":{"price":45.95,"currency":"EUR"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/gateways":{"get":{"summary":"List gateways","operationId":"list_gateways","description":"Lists the gateways of your account in the mode of the token you call with. The list is offset-based.\n\nSecret and trusted tokens may call this with the `gateways` read permission.","tags":["gateways"],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"name":"sort_by","in":"query","description":"The field to sort by. The default is `name`.","required":false,"schema":{"type":"string","enum":["name","date_created","date_modified","gateway_id"],"default":"name"}},{"$ref":"#/components/parameters/desc"},{"name":"active","in":"query","description":"`true` for active gateways only, `false` for inactive ones only.","required":false,"schema":{"type":"boolean"}},{"name":"q","in":"query","description":"A `gateway_id`. Returns only that gateway.","required":false,"schema":{"type":"string"}},{"name":"show_sensitive","in":"query","description":"When `true`, each gateway also has `fields`, the provider settings you saved. Treat them as secrets.","required":false,"schema":{"type":"boolean","default":false}},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/timezone"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"An offset-based list of gateways.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/gateway_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/gateways","data":[{"object":"gateway","url":"https://api.comecero.com/api/v1/gateways/0070576784690GtKDqfI7c","gateway_id":"0070576784690GtKDqfI7c","test":true,"name":"Test Gateway","provider_id":"test","date_created":"2026-10-01T14:36:52Z","date_modified":"2026-10-01T14:36:52Z","account_id":"AB1234","payment_method_types":["credit_card"],"currencies":["USD","EUR"],"card_types":["visa","mastercard"],"supports_void":true,"supports_general_credit":false,"active":true,"weight":1,"comments":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Add a gateway","operationId":"create_gateway","description":"Connects a payment provider to your account, in the mode of the token you call with. Call `GET /gateways/options` first to see the providers and the settings each one needs. A new gateway is inactive unless you send `active: true`. Fires the `gateway:created` event.\n\nSecret and trusted tokens may call this with the `gateways` create permission.","tags":["gateways"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/gateway_request"},"examples":{"minimal":{"summary":"A test gateway for cards in USD","value":{"provider_id":"test","payment_method_types":["credit_card"],"currencies":["USD"],"active":true}},"full":{"summary":"With currencies and card types","value":{"provider_id":"test","payment_method_types":["credit_card"],"currencies":["USD","EUR"],"card_types":["visa","mastercard","american_express"],"active":true}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new gateway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/gateway"},"example":{"object":"gateway","url":"https://api.comecero.com/api/v1/gateways/0070576784690GtKDqfI7c","gateway_id":"0070576784690GtKDqfI7c","test":true,"name":"Test Gateway","provider_id":"test","date_created":"2026-10-01T14:36:52Z","date_modified":"2026-10-01T14:36:52Z","account_id":"AB1234","payment_method_types":["credit_card"],"currencies":["USD","EUR"],"card_types":["visa","mastercard","american_express"],"supports_void":true,"supports_general_credit":false,"active":true,"weight":1,"comments":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/gateways/options":{"get":{"summary":"List gateway options","operationId":"get_gateway_options","description":"Lists what you can choose from when you add a gateway: the providers for the mode of your token, the settings each one needs, the currencies and the card brands.\n\nSecret and trusted tokens may call this with the `gateways` read permission.","tags":["gateways"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The gateway options.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/gateway_options"},"example":{"account_id":"AB1234","test":true,"gateway_configs":[{"provider_id":"test","name":"Test Gateway","test":true,"payment_method_types":["credit_card"],"fields":[]}],"currencies":[{"code":"EUR","name":"Euro"},{"code":"USD","name":"US Dollar"}],"card_types":["american_express","discover","mastercard","visa"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/gateways/{gateway_id}":{"parameters":[{"name":"gateway_id","in":"path","description":"The gateway's `gateway_id`.","required":true,"schema":{"type":"string"},"example":"0070576784690GtKDqfI7c"}],"get":{"summary":"Get a gateway","operationId":"get_gateway","description":"Gets one gateway. A gateway of the other mode is not found (`404`).\n\nSecret and trusted tokens may call this with the `gateways` read permission.","tags":["gateways"],"parameters":[{"name":"show_sensitive","in":"query","description":"When `true`, the gateway also has `fields`, the provider settings you saved. Treat them as secrets.","required":false,"schema":{"type":"boolean","default":false}},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/timezone"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The gateway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/gateway"},"example":{"object":"gateway","url":"https://api.comecero.com/api/v1/gateways/0070576784690GtKDqfI7c","gateway_id":"0070576784690GtKDqfI7c","test":true,"name":"Test Gateway","provider_id":"test","date_created":"2026-10-01T14:36:52Z","date_modified":"2026-10-01T14:36:52Z","account_id":"AB1234","payment_method_types":["credit_card"],"currencies":["USD","EUR"],"card_types":["visa","mastercard","american_express"],"supports_void":true,"supports_general_credit":false,"active":true,"weight":1,"comments":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Update a gateway","operationId":"update_gateway","description":"Changes a gateway's currencies, card brands, settings, weight, notes, or switches it on or off. Only the fields you send change. Fires the `gateway:modified` event.\n\nSome gateways cannot be changed this way. Gateways that Comecero set up for you keep their settings, currencies and card brands (`400`), and may stay off while their set-up finishes or payments are on hold (`422`).\n\nSecret and trusted tokens may call this with the `gateways` update permission.","tags":["gateways"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/gateway_update_request"},"examples":{"pause":{"summary":"Turn the gateway off","value":{"active":false,"comments":"Paused while we change providers."}},"currencies":{"summary":"Change the currencies","value":{"currencies":["USD","EUR","GBP"]}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The updated gateway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/gateway"},"example":{"object":"gateway","url":"https://api.comecero.com/api/v1/gateways/0070576784690GtKDqfI7c","gateway_id":"0070576784690GtKDqfI7c","test":true,"name":"Test Gateway","provider_id":"test","date_created":"2026-10-01T14:36:52Z","date_modified":"2026-10-01T14:36:52Z","account_id":"AB1234","payment_method_types":["credit_card"],"currencies":["USD","EUR"],"card_types":["visa","mastercard","american_express"],"supports_void":true,"supports_general_credit":false,"active":true,"weight":1,"comments":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"summary":"Delete a gateway","operationId":"delete_gateway","description":"Removes a gateway. A live gateway that has taken payments cannot be deleted (`409`): set `active` to `false` instead. Test gateways can always be deleted.\n\nSecret and trusted tokens may call this with the `gateways` delete permission.","tags":["gateways"],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The gateway is deleted. No body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/images":{"get":{"summary":"List images","operationId":"list_images","description":"Returns your images, oldest first unless you choose another `sort_by`. Secret and trusted tokens may call it.","tags":["images"],"parameters":[{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/limit"},{"name":"sort_by","in":"query","description":"The field to sort by. The default is `date_created`.","schema":{"type":"string","enum":["date_created","date_modified","filename"]}},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"name":"q","in":"query","description":"Search text. An exact image id returns that image; otherwise images whose file name contains the text (any case) are returned.","schema":{"type":"string"}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of images.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/image_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/images?offset=0","data":[{"object":"image","url":"https://api.comecero.com/api/v1/images/0099844605810ImLAMbo73","image_id":"0099844605810ImLAMbo73","date_created":"2026-11-02T14:36:45Z","date_modified":"2026-11-02T14:36:45Z","test":true,"account_id":"AB1234","link":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/widget.png","link_small":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sm_widget.png","link_medium":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/md_widget.png","link_large":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/lg_widget.png","link_square":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sq_widget.png","filename":"widget.png"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Upload an image","operationId":"create_image","description":"Uploads an image and makes small, medium, large and square copies of it on the CDN. The body must be `multipart/form-data` with the image in a part named `file`; a JSON body is refused with `400`. There is no way to upload an image from a URL. Use the `image_id` in a product's `image_ids`. Images cannot be changed after upload; upload a new one instead. Secret and trusted tokens may call it.","tags":["images"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"description":"The image.","content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/image_request"},"encoding":{"file":{"contentType":"image/png, image/jpeg, image/gif, image/x-icon"}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new image.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/image"},"example":{"object":"image","url":"https://api.comecero.com/api/v1/images/0099844605810ImLAMbo73","image_id":"0099844605810ImLAMbo73","date_created":"2026-11-02T14:36:45Z","date_modified":"2026-11-02T14:36:45Z","test":true,"account_id":"AB1234","link":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/widget.png","link_small":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sm_widget.png","link_medium":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/md_widget.png","link_large":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/lg_widget.png","link_square":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sq_widget.png","filename":"widget.png"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/images/{image_id}":{"get":{"summary":"Get an image","operationId":"get_image","description":"Returns one image. Secret and trusted tokens may call it.","tags":["images"],"parameters":[{"name":"image_id","in":"path","required":true,"description":"The image id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The image.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/image"},"example":{"object":"image","url":"https://api.comecero.com/api/v1/images/0099844605810ImLAMbo73","image_id":"0099844605810ImLAMbo73","date_created":"2026-11-02T14:36:45Z","date_modified":"2026-11-02T14:36:45Z","test":true,"account_id":"AB1234","link":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/widget.png","link_small":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sm_widget.png","link_medium":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/md_widget.png","link_large":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/lg_widget.png","link_square":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sq_widget.png","filename":"widget.png"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"summary":"Delete an image","operationId":"delete_image","description":"Deletes an image and its copies from the CDN for good. Products that list it in `image_ids` keep the id, but it no longer appears in their `images`. Secret and trusted tokens may call it.","tags":["images"],"parameters":[{"name":"image_id","in":"path","required":true,"description":"The image id.","schema":{"type":"string"}}],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The image is deleted. No body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/invoices":{"get":{"summary":"List invoices","operationId":"list_invoices","description":"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.","tags":["invoices"],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/after_item"},{"$ref":"#/components/parameters/before_item"},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/date_start"},{"$ref":"#/components/parameters/date_end"},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"name":"date_type","in":"query","required":false,"description":"The date that `date_start` and `date_end` filter on and the list is sorted by. Defaults to `date_created`.","schema":{"type":"string","enum":["date_created","date_modified","date_due","date_completed"]}},{"name":"q","in":"query","required":false,"description":"Search text. Matches the invoice id or the customer's email exactly, or part of the customer's name or company name.","schema":{"type":"string"}},{"name":"open","in":"query","required":false,"description":"`true` for open invoices only, `false` for closed ones only.","schema":{"type":"boolean"}},{"name":"draft","in":"query","required":false,"description":"`true` for drafts only, `false` for published invoices only.","schema":{"type":"boolean"}},{"name":"payment_status","in":"query","required":false,"description":"Only invoices with this payment status.","schema":{"type":"string","enum":["unpaid","scheduled","initiated","processing","pending","completed","failed","cancelled","refunded","retry"]}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A cursor-based list of invoices.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoice_list"},"example":{"next_page_url":"https://api.comecero.com/api/v1/invoices?after_item=4827-KTPMW-639&limit=1","next_page_after_item":"4827-KTPMW-639","previous_page_url":null,"previous_page_before_item":null,"data":[{"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,"shipping":0,"discount":0,"tax":0,"total":950,"total_payments":0,"total_remaining":950,"autopay":false,"autopay_at":null,"draft":false,"items_count":1,"items_quantity":10,"shipping_item":null,"customer":null,"order":null,"payments":"https://api.comecero.com/api/v1/invoices/4827-KTPMW-639/payments","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":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Create an invoice","operationId":"create_invoice","description":"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.","tags":["invoices"],"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/user_ip_address"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoice_request"},"examples":{"minimal":{"summary":"A draft with one line","value":{"currency":"USD","customer":{"name":"John Doe","email":"john@example.com"},"items":[{"name":"Consulting, 2 hours","type":"service","quantity":2,"reference_price":120}]}},"full":{"summary":"Published, with a due date and address","value":{"currency":"USD","date_due":"2026-11-30","draft":false,"customer":{"name":"John Doe","email":"john@example.com","billing_address":{"name":"John Doe","address_1":"100 Main Street","city":"Springfield","state_prov":"IL","postal_code":"62701","country":"US"}},"items":[{"name":"Website setup, 10 hours","type":"service","quantity":10,"reference_price":95}],"meta":{"project":"Q4-site"}}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new invoice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoice"},"example":{"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"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/invoices/{invoice_id}":{"parameters":[{"name":"invoice_id","in":"path","required":true,"description":"The invoice id.","schema":{"type":"string"}}],"get":{"summary":"Get an invoice","operationId":"get_invoice","description":"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.","x-limited":true,"tags":["invoices"],"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/timezone"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The invoice, or its PDF when you ask for `application/pdf`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoice"},"example":{"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"}}},"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Update an invoice","operationId":"update_invoice","description":"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.","x-limited":true,"tags":["invoices"],"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/user_ip_address"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoice_request"},"example":{"draft":false,"date_due":"2026-11-30"}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The updated invoice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoice"},"example":{"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"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"summary":"Delete an invoice","operationId":"delete_invoice","description":"Deletes an open invoice for good. You cannot delete a closed invoice, a subscription renewal invoice, or one with a completed or pending payment (refund or cancel those payments first). No event fires. Takes a secret or trusted token.","tags":["invoices"],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The invoice was deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/invoices/{invoice_id}/items":{"parameters":[{"name":"invoice_id","in":"path","required":true,"description":"The invoice id.","schema":{"type":"string"}}],"get":{"summary":"List invoice items","operationId":"list_invoice_items","description":"Returns the items on an invoice. The list is offset-based and, unless you send `limit`, returns every item on one page. Takes a secret, trusted or limited token. A limited token must be bound to the invoice and cannot see a draft.","x-limited":true,"tags":["invoices"],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/desc"},{"name":"sort_by","in":"query","required":false,"description":"The field to sort by. Defaults to `date_created`.","schema":{"type":"string","enum":["date_created","date_modified","product_id","item_id"]}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"An offset-based list of invoice items.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoice_item_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/invoices/4827-KTPMW-639/items","data":[{"object":"invoice_item","url":"https://api.comecero.com/api/v1/invoices/4827-KTPMW-639/items/1","item_id":"1","invoice_id":"4827-KTPMW-639","product_id":null,"name":"Website setup, 10 hours","type":"service","quantity":10,"currency":"USD","price":95,"subtotal":950,"tax":0,"total":950,"product":null,"meta":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Add an invoice item","operationId":"create_invoice_item","description":"Adds one item to an open, unpaid invoice. Send a `product_id` for a catalog product, or a `name`, `type` and `reference_price` for a custom item. Adding a product that is already on the invoice replaces that line. Adding a bundle product adds the bundle plus one zero-priced item per product in it, and the response is then a list of all those items. Shipping and promotions are worked out again. You cannot add items once the invoice is closed, paid, scheduled for automatic payment or has a payment in process. Takes a secret or trusted token. Limited tokens may not change items (`403`).","tags":["invoices"],"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoice_item_request"},"examples":{"product":{"summary":"Add a product","value":{"product_id":"widget-pro.test","quantity":1}},"custom":{"summary":"Add a custom line","value":{"name":"Website setup, 10 hours","type":"service","quantity":10,"reference_price":95,"reference_currency":"USD"}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new item. For a bundle product, an offset-based list of the bundle item and its parts.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/invoice_item"},{"$ref":"#/components/schemas/invoice_item_list"}]},"example":{"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,"settlement_currency":"USD","settlement_price":95,"settlement_price_original":95,"settlement_subtotal":950,"settlement_subtotal_original":950,"settlement_discount":0,"settlement_tax":0,"settlement_tax_original":0,"settlement_total":950,"settlement_total_original":950,"product":null,"subscription_plan":null,"subscription_terms":null,"meta":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"summary":"Delete all invoice items","operationId":"delete_invoice_items","description":"Removes every item from an open, unpaid invoice. Shipping and promotions are worked out again. A published invoice with no items cannot be paid. Takes a secret or trusted token.","tags":["invoices"],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"All items were removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/invoices/{invoice_id}/items/{item_id}":{"parameters":[{"name":"invoice_id","in":"path","required":true,"description":"The invoice id.","schema":{"type":"string"}},{"name":"item_id","in":"path","required":true,"description":"The item id. For a product it is the `product_id`.","schema":{"type":"string"}}],"get":{"summary":"Get an invoice item","operationId":"get_invoice_item","description":"Returns one item on an invoice. Takes a secret, trusted or limited token. A limited token must be bound to the invoice and cannot see a draft.","x-limited":true,"tags":["invoices"],"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The invoice item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoice_item"},"example":{"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,"settlement_currency":"USD","settlement_price":95,"settlement_price_original":95,"settlement_subtotal":950,"settlement_subtotal_original":950,"settlement_discount":0,"settlement_tax":0,"settlement_tax_original":0,"settlement_total":950,"settlement_total_original":950,"product":null,"subscription_plan":null,"subscription_terms":null,"meta":null}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Update an invoice item","operationId":"update_invoice_item","description":"Changes one item on an open, unpaid invoice. You can change `quantity`, `reference_price`, `reference_currency` and `meta` on any item, and also `name`, `type`, `tax_code` and `subscription_plan_id` on a custom item. Items that are part of a bundle cannot be changed: delete the bundle and add it again. Shipping and promotions are worked out again. Takes a secret or trusted token. Limited tokens may not change items (`403`).","tags":["invoices"],"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoice_item_request"},"example":{"quantity":12}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The updated item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoice_item"},"example":{"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,"settlement_currency":"USD","settlement_price":95,"settlement_price_original":95,"settlement_subtotal":950,"settlement_subtotal_original":950,"settlement_discount":0,"settlement_tax":0,"settlement_tax_original":0,"settlement_total":950,"settlement_total_original":950,"product":null,"subscription_plan":null,"subscription_terms":null,"meta":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"summary":"Delete an invoice item","operationId":"delete_invoice_item","description":"Removes one item from an open, unpaid invoice. If the item is part of a bundle, the whole bundle is removed. Shipping and promotions are worked out again. Takes a secret or trusted token.","tags":["invoices"],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The item was removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/invoices/{invoice_id}/links":{"parameters":[{"name":"invoice_id","in":"path","required":true,"description":"The invoice id.","schema":{"type":"string"}}],"post":{"summary":"Create a payment link","operationId":"create_invoice_link","description":"Makes a new link the customer can open to see and pay an open invoice, and returns it. Nothing is emailed: use it to send the link yourself. Each call makes a new link; links expire after 30 days. The link is built on the host of the app installed for invoice payments, or else the first app host in your technical settings. Returns `422` when the invoice is closed or there is no host. Takes a secret, trusted or limited token. A limited token must be bound to the invoice and cannot see a draft.","x-limited":true,"tags":["invoices"],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The payment link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoice_link"},"example":{"link_url":"https://shop.example.com/link?id=in-7f3c2a91b04e4d6c9a1e"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/invoices/{invoice_id}/notifications":{"parameters":[{"name":"invoice_id","in":"path","required":true,"description":"The invoice id.","schema":{"type":"string"}}],"get":{"summary":"List invoice notifications","operationId":"list_invoice_notifications","description":"Returns the notifications (emails) sent about an invoice, such as the payment link sent to the customer. The list is offset-based. Takes a secret, trusted or limited token. A limited token must be bound to the invoice and cannot see a draft.","x-limited":true,"tags":["invoices"],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/desc"},{"name":"sort_by","in":"query","required":false,"description":"The field to sort by. Defaults to `date_created`.","schema":{"type":"string","enum":["date_created","date_modified"]}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"An offset-based list of notifications.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoice_notification_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/invoices/4827-KTPMW-639/notifications?offset=0&limit=10","data":[{"object":"notification","url":"https://api.comecero.com/api/v1/notifications/1102611073905NOq2Lx7Pv","notification_id":"1102611073905NOq2Lx7Pv","test":true,"account_id":"AB1234","type":"order:confirmation","method":"email","from":"notification@comecero.com","from_name":"Example Shop","reply_to":"support@example.com","bcc":null,"destination":"john@example.com","subject":"Your Order Confirmation","notification_subscription":"https://api.comecero.com/api/v1/notification_subscriptions/1102500112233NSd4Kw9Tz","customer":"https://api.comecero.com/api/v1/customers/1102611073801CUa8Hn2Lq","status":"delivered","date_created":"2026-11-07T14:32:12Z","date_modified":"2026-11-07T14:32:14Z","data":{"order":{"order_id":"7393-GMRFY-954","total":99.95,"currency":"USD"}},"body":"<html><body><h1>Thanks for your order</h1></body></html>"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/invoices/{invoice_id}/options":{"parameters":[{"name":"invoice_id","in":"path","required":true,"description":"The invoice id.","schema":{"type":"string"}}],"get":{"summary":"Get invoice payment options","operationId":"get_invoice_options","description":"Returns how the customer can pay this invoice: the payment methods and card types your gateways take in the invoice currency, shipping choices for the customer's country, and the customer fields still needed. Call it before you show a payment form. Takes a secret, trusted or limited token. A limited token must be bound to the invoice and cannot see a draft.","x-limited":true,"tags":["invoices"],"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The payment options.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoice_options"},"example":{"invoice_id":"4827-KTPMW-639","account_id":"AB1234","test":true,"payment_methods":[{"payment_method_type":"credit_card","surcharge":0,"currency":null},{"payment_method_type":"paypal","surcharge":0,"currency":null}],"card_types":["visa","mastercard","amex"],"shipping_quotes":[],"customer_required_fields":["name","email","billing_address.country"],"customer_optional_fields":["billing_address.postal_code"],"allowed_customer_countries":["US","CA","GB"],"require_cardholder_name":false}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/invoices/{invoice_id}/payments":{"parameters":[{"name":"invoice_id","in":"path","required":true,"description":"The invoice id.","schema":{"type":"string"}}],"get":{"summary":"List invoice payments","operationId":"list_invoice_payments","description":"Returns the payments made against an invoice, including failed attempts. The list is offset-based. Takes a secret, trusted or limited token. A limited token must be bound to the invoice and cannot see a draft.","x-limited":true,"tags":["invoices"],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/desc"},{"name":"sort_by","in":"query","required":false,"description":"The field to sort by. Defaults to `date_created`.","schema":{"type":"string","enum":["date_created","date_modified","date_completed"]}},{"name":"status","in":"query","required":false,"description":"Only payments with this status.","schema":{"type":"string","enum":["initiated","processing","pending","completed","failed","cancelled","refunded","retry"]}},{"name":"reference","in":"query","required":false,"description":"Only payments with this gateway reference.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"An offset-based list of payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoice_payment_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/invoices/4827-KTPMW-639/payments?offset=0&limit=10","data":[{"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}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Pay an invoice","operationId":"create_invoice_payment","description":"Charges a payment against a published, open invoice. Send a `payment_method` (or a saved `payment_method_id`). Do not send `currency`: it comes from the invoice. Leave out `total` to pay what is left. Send a smaller `total` to pay part of it; the total of all payments cannot pass the invoice total. Money moves. When the invoice is paid in full it closes, becomes an order with the same id, and `invoice:paid` fires. `invoice:payment_completed` fires, with `order:payment_completed`, when the completed payments cover the total and none is `pending`. Some payment methods (such as PayPal) return a payment that waits for the customer to approve it. Takes a secret, trusted or limited token. A limited token must be bound to the invoice, and a limited test token needs a user who may make test transactions.","x-limited":true,"tags":["invoices"],"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/user_ip_address"},{"$ref":"#/components/parameters/user_agent"}],"requestBody":{"$ref":"#/components/requestBodies/payment_request"},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment"},"example":{"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}}}},"400":{"description":"Invalid input, or the gateway rejected the request. When a payment was attempted, the failed payment is in `error.meta.payment`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The payment was declined. The failed payment is in `error.meta.payment`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The same payment was just made successfully (the earlier payment's id is in `error.meta.payment_id`), another payment for the invoice is still running (code `payment_in_progress`), or an earlier one may have been taken but is not confirmed yet (code `payment_unconfirmed`). Do not send the payment again: read the invoice's payments first, so the customer is never charged twice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"The gateway or processor returned an error. The failed payment is in `error.meta.payment`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"504":{"description":"The gateway or processor timed out. The failed payment is in `error.meta.payment`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}}}},"/invoices/{invoice_id}/promotions":{"parameters":[{"name":"invoice_id","in":"path","required":true,"description":"The invoice id.","schema":{"type":"string"}}],"get":{"summary":"List invoice promotions","operationId":"list_invoice_promotions","description":"Returns the promotions applied to an invoice: its coupon, and any cross-sell or up-sell offers its items came from. The list is offset-based. Takes a secret, trusted or limited token. A limited token must be bound to the invoice and cannot see a draft.","x-limited":true,"tags":["invoices"],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/desc"},{"name":"sort_by","in":"query","required":false,"description":"The field to sort by. Defaults to `date_created`.","schema":{"type":"string","enum":["date_created","date_modified","promotion_id","name"]}},{"name":"active","in":"query","required":false,"description":"`true` for active promotions only, `false` for inactive ones only.","schema":{"type":"boolean"}},{"name":"q","in":"query","required":false,"description":"Search text. Matches the promotion id exactly or part of the name.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"An offset-based list of promotions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoice_promotion_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/invoices/4827-KTPMW-639/promotions?offset=0&limit=10","data":[{"object":"promotion","url":"https://api.comecero.com/api/v1/promotions/0070576784690PtKDqfI","promotion_id":"0070576784690PtKDqfI","name":"Ten percent off","test":true,"account_id":"AB1234","date_created":"2026-11-02T20:13:16Z","date_modified":"2026-11-02T20:13:16Z","type":"coupon","active":true,"apply_to_recurring":false,"apply_to_recurring_count":null,"use_count":4,"expires":"2026-12-31T23:59:59Z","comments":null,"config":{"type":"order","code":"SAVE10","generator_prefix":null,"generator_secret_key":null,"discount_percent":0.1,"discount_amount":null,"product_ids":null,"exclude_product_ids":false,"max_uses_per_customer":1,"max_uses_global":null}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/invoices/{invoice_id}/refunds":{"parameters":[{"name":"invoice_id","in":"path","required":true,"description":"The invoice id.","schema":{"type":"string"}}],"get":{"summary":"List invoice refunds","operationId":"list_invoice_refunds","description":"Returns the refunds and chargebacks of the payments made against an invoice. The list is offset-based. Takes a secret, trusted or limited token. A limited token must be bound to the invoice and cannot see a draft.","x-limited":true,"tags":["invoices"],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/desc"},{"name":"sort_by","in":"query","required":false,"description":"The field to sort by. Defaults to `date_created`.","schema":{"type":"string","enum":["date_created","date_modified","date_completed"]}},{"name":"status","in":"query","required":false,"description":"Only refunds with this status.","schema":{"type":"string","enum":["pending","completed","failed","cancelled"]}},{"name":"is_chargeback","in":"query","required":false,"description":"`true` for chargebacks only, `false` for refunds only.","schema":{"type":"boolean"}},{"name":"reference","in":"query","required":false,"description":"Only refunds with this gateway reference.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"An offset-based list of refunds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoice_refund_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/invoices/4827-KTPMW-639/refunds?offset=0&limit=10","data":[{"object":"refund","url":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5","refund_id":"0090374314462Rec3PffZ5","account_id":"AB1234","success":true,"status":"completed","reference":null,"date_created":"2026-11-03T10:12:40Z","date_modified":"2026-11-03T10:12:41Z","date_completed":"2026-11-03T10:12:41Z","test":true,"currency":"USD","subtotal":49.95,"shipping":0,"tax":0,"total":49.95,"reason":"Customer request","apply_to_balance":false,"is_chargeback":false,"record_only":false,"record_only_memo":null,"response_code":"OK","response_message":"OK","gateway_transaction_id":"re_test_3PffZ5","gateway_error_code":null,"gateway_error_message":null,"gateway":"https://api.comecero.com/api/v1/gateways/0089584408915Gtf5AsdJ8","comments":null,"payment_method":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/payment_method","settlement_currency":"USD","settlement_subtotal":49.95,"settlement_shipping":0,"settlement_tax":0,"settlement_total":49.95,"fx_rate":1,"reporting_currency":"USD","reporting_subtotal":49.95,"reporting_shipping":0,"reporting_tax":0,"reporting_total":49.95,"reporting_fx_rate":1,"items":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/items","customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","order":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954","payment":"https://api.comecero.com/api/v1/payments/0093717991362PyRYN1qc6","invoice":null,"fees":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fees","fee_summary":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fee_summary","commissions":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/commissions","meta":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/invoices/{invoice_id}/retry":{"parameters":[{"name":"invoice_id","in":"path","required":true,"description":"The invoice id.","schema":{"type":"string"}}],"post":{"summary":"Retry an invoice payment","operationId":"retry_invoice_payment","description":"Charges the customer's saved payment method again for an invoice whose automatic payment failed (`payment_status` is `failed` or `retry`). Money moves. For a subscription renewal invoice, the subscription must be active. If a manual attempt was declined in the last 3 hours, you must wait (`422`). You also get `422` while another payment of the invoice is in process. Takes a secret or trusted token.","tags":["invoices"],"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The payment that was made.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment"},"example":{"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}}}},"400":{"description":"Invalid input, or the gateway rejected the request. When a payment was attempted, the failed payment is in `error.meta.payment`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The payment was declined. The failed payment is in `error.meta.payment`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The same payment was just made successfully. The earlier payment's id is in `error.meta.payment_id`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"The gateway or processor returned an error. The failed payment is in `error.meta.payment`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"504":{"description":"The gateway or processor timed out. The failed payment is in `error.meta.payment`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}}}},"/invoices/{invoice_id}/send":{"parameters":[{"name":"invoice_id","in":"path","required":true,"description":"The invoice id.","schema":{"type":"string"}}],"post":{"summary":"Send an invoice","operationId":"send_invoice","description":"Emails the customer a new payment link for an open invoice, through your notification subscription for invoice links. The invoice itself does not change and no event fires. Returns `422` when the invoice is closed, when you have no notification subscription for invoice links, or when the account has no app host to build the link on. Takes a secret, trusted or limited token. A limited token must be bound to the invoice and cannot send a draft.","x-limited":true,"tags":["invoices"],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The email was queued."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/invoices/{invoice_id}/shipping_item":{"parameters":[{"name":"invoice_id","in":"path","required":true,"description":"The invoice id.","schema":{"type":"string"}}],"get":{"summary":"Get the invoice shipping item","operationId":"get_invoice_shipping_item","description":"Returns the shipping line of an invoice. Returns `404` when the invoice has no shipping. Takes a secret, trusted or limited token. A limited token must be bound to the invoice and cannot see a draft.","x-limited":true,"tags":["invoices"],"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The shipping item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoice_item"},"example":{"object":"invoice_item","url":"https://api.comecero.com/api/v1/invoices/4827-KTPMW-639/items/2","item_id":"2","invoice_id":"4827-KTPMW-639","product_id":null,"name":"Standard Shipping","type":"shipping","quantity":1,"currency":"USD","price":5,"price_original":5,"subtotal":5,"discount":0,"tax":0,"total":5,"product":null,"subscription_plan":null,"subscription_terms":null,"meta":null}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/license_requests":{"get":{"summary":"List license requests","operationId":"list_license_requests","description":"Returns the calls made to your license services, by status. Only `failed` requests are returned unless you send another `status`, so the default list is the one to watch for problems. Oldest first unless you send `desc=true`. Secret and trusted tokens may call it.","tags":["license_requests"],"parameters":[{"$ref":"#/components/parameters/after_item"},{"$ref":"#/components/parameters/before_item"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/desc"},{"name":"date_start","in":"query","description":"Only requests created on or after this date (ISO 8601).","schema":{"type":"string"}},{"name":"date_end","in":"query","description":"Only requests created on or before this date (ISO 8601).","schema":{"type":"string"}},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"name":"status","in":"query","description":"Only requests with this status. The default is `failed`.","schema":{"type":"string","default":"failed","enum":["queued","completed","retry","failed"]}},{"name":"q","in":"query","description":"A license request id. Returns only that request, and only when its status matches `status`.","schema":{"type":"string"}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of license requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/license_request_list"},"example":{"next_page_url":null,"next_page_after_item":null,"previous_page_url":null,"previous_page_before_item":null,"data":[{"object":"license_request","url":"https://api.comecero.com/api/v1/license_requests/0142130710483Lruow24Z6","license_request_id":"0142130710483Lruow24Z6","date_created":"2026-11-02T00:45:10Z","date_modified":"2026-11-05T00:45:10Z","test":true,"account_id":"AB1234","status":"failed","product_id":"widget-pro.test","license":null,"license_service":"https://api.comecero.com/api/v1/license_services/0095012789659LsuOeAWLC","order":{"object":"order","url":"https://api.comecero.com/api/v1/orders/6622-NXKHE-858","order_id":"6622-NXKHE-858","test":true}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/license_requests/{license_request_id}":{"get":{"summary":"Get a license request","operationId":"get_license_request","description":"Returns one license request. Send `debug=true` to see the retry details and why the last attempt failed. Secret and trusted tokens may call it.","tags":["license_requests"],"parameters":[{"name":"license_request_id","in":"path","required":true,"description":"The license request id.","schema":{"type":"string"}},{"name":"debug","in":"query","description":"When true, the response adds `retry_count`, the attempt dates and `last_failure_meta`.","schema":{"type":"boolean"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The license request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/license_request"},"example":{"object":"license_request","url":"https://api.comecero.com/api/v1/license_requests/0142130710483Lruow24Z6","license_request_id":"0142130710483Lruow24Z6","date_created":"2026-11-02T00:45:10Z","date_modified":"2026-11-02T01:15:10Z","test":true,"account_id":"AB1234","status":"retry","product_id":"widget-pro.test","license":null,"license_service":"https://api.comecero.com/api/v1/license_services/0095012789659LsuOeAWLC","order":{"object":"order","url":"https://api.comecero.com/api/v1/orders/6622-NXKHE-858","order_id":"6622-NXKHE-858","test":true},"retry_count":2,"date_last_request_attempt":"2026-11-02T01:15:10Z","date_next_request_attempt":"2026-11-02T02:15:10Z","last_failure_meta":"HTTP 500, Response Content (preview of first 500 characters): Internal Server Error"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"summary":"Delete a license request","operationId":"delete_license_request","description":"Deletes a license request for good, so it no longer shows in the list. A license already issued from it is kept. Use it to clear a failed request you have dealt with another way. Secret and trusted tokens may call it.","tags":["license_requests"],"parameters":[{"name":"license_request_id","in":"path","required":true,"description":"The license request id.","schema":{"type":"string"}}],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The license request is deleted. No body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/license_requests/{license_request_id}/retry":{"post":{"summary":"Retry a license request","operationId":"retry_license_request","description":"Runs a license request again now, failed or not. On success a new license is saved and added to the order item, and automatic retries stop. A failure is not returned as an error: the call still answers `200`, so check `status` in the response (with `debug=true` for the reason). No request body. Secret and trusted tokens may call it.","tags":["license_requests"],"parameters":[{"name":"license_request_id","in":"path","required":true,"description":"The license request id.","schema":{"type":"string"}},{"name":"debug","in":"query","description":"When true, the response adds `retry_count`, the attempt dates and `last_failure_meta`.","schema":{"type":"boolean"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The license request after the attempt.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/license_request"},"example":{"object":"license_request","url":"https://api.comecero.com/api/v1/license_requests/0142130710483Lruow24Z6","license_request_id":"0142130710483Lruow24Z6","date_created":"2026-11-02T00:45:10Z","date_modified":"2026-11-07T15:02:44Z","test":true,"account_id":"AB1234","status":"completed","product_id":"widget-pro.test","license":"https://api.comecero.com/api/v1/licenses/0142130710581LiRr8sT2c","license_service":"https://api.comecero.com/api/v1/license_services/0095012789659LsuOeAWLC","order":{"object":"order","url":"https://api.comecero.com/api/v1/orders/6622-NXKHE-858","order_id":"6622-NXKHE-858","test":true}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/license_services":{"get":{"summary":"List license services","operationId":"list_license_services","description":"Returns your license services, oldest first unless you choose another `sort_by`. For `list` services, only the first 15 keys of a long list come back here; read the service itself for all of them. Secret and trusted tokens may call it.","tags":["license_services"],"parameters":[{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/limit"},{"name":"sort_by","in":"query","description":"The field to sort by. The default is `date_created`.","schema":{"type":"string","enum":["date_created","date_modified","name"]}},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"name":"q","in":"query","description":"Search text. An exact license service id returns that service; otherwise services whose name contains the text (any case) are returned.","schema":{"type":"string"}},{"name":"type","in":"query","description":"Only services of this type.","schema":{"type":"string","enum":["remote_url","list"]}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of license services.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/license_service_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/license_services?offset=0","data":[{"object":"license_service","url":"https://api.comecero.com/api/v1/license_services/0095012789659LsuOeAWLC","license_service_id":"0095012789659LsuOeAWLC","date_created":"2026-11-02T16:26:29Z","date_modified":"2026-11-02T16:45:25Z","test":true,"account_id":"AB1234","name":"Widget Pro keys","label":"License Code","description":null,"instructions":null,"type":"list","expand":null,"show":null,"hide":null,"configuration":{"license_count":2,"per_quantity":false,"remove_after_use":true,"notify_at_count":100,"licenses":["AAAA-BBBB-CCCC-0001","AAAA-BBBB-CCCC-0002"]}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Create a license service","operationId":"create_license_service","description":"Creates a license service. Link it to a product with the product's `license_service_id`, and every sale of that product gets a license key from it. Secret and trusted tokens may call it.","tags":["license_services"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"description":"The new license service.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/license_service_request"},{"required":["name","label","type","configuration"]}]},"examples":{"list":{"summary":"A list of keys you upload","value":{"name":"Widget Pro keys","label":"License Code","type":"list","instructions":"Open Widget Pro, choose Help, then Enter License, and paste the code.","configuration":{"licenses":["AAAA-BBBB-CCCC-0001","AAAA-BBBB-CCCC-0002"],"per_quantity":false,"notify_at_count":10}}},"remote_url":{"summary":"Keys from your own server","value":{"name":"Widget Pro key server","label":"License Code","type":"remote_url","configuration":{"url":"https://example.com/licenses/generate","format":"json"}}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new license service.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/license_service"},"example":{"object":"license_service","url":"https://api.comecero.com/api/v1/license_services/0095012789659LsuOeAWLC","license_service_id":"0095012789659LsuOeAWLC","date_created":"2026-11-02T16:26:29Z","date_modified":"2026-11-02T16:45:25Z","test":true,"account_id":"AB1234","name":"Widget Pro keys","label":"License Code","description":null,"instructions":"Open Widget Pro, choose Help, then Enter License, and paste the code.","type":"remote_url","expand":null,"show":null,"hide":null,"configuration":{"url":"https://licenses.example.com/issue","format":"json","http_authorization_username":null,"http_authorization_password":null,"custom_header_name":null,"custom_header_value":null}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/license_services/{license_service_id}":{"get":{"summary":"Get a license service","operationId":"get_license_service","description":"Returns one license service, with every key of a `list` service. Secret and trusted tokens may call it.","tags":["license_services"],"parameters":[{"name":"license_service_id","in":"path","required":true,"description":"The license service id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The license service.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/license_service"},"example":{"object":"license_service","url":"https://api.comecero.com/api/v1/license_services/0095012789659LsuOeAWLC","license_service_id":"0095012789659LsuOeAWLC","date_created":"2026-11-02T16:26:29Z","date_modified":"2026-11-02T16:45:25Z","test":true,"account_id":"AB1234","name":"Widget Pro keys","label":"License Code","description":null,"instructions":"Open Widget Pro, choose Help, then Enter License, and paste the code.","type":"remote_url","expand":null,"show":null,"hide":null,"configuration":{"url":"https://licenses.example.com/issue","format":"json","http_authorization_username":null,"http_authorization_password":null,"custom_header_name":null,"custom_header_value":null}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Update a license service","operationId":"update_license_service","description":"Changes a license service. Send only the fields you want to change. Inside `configuration`, only the fields you send change, but `licenses` replaces the whole key list. Changing `type` drops the settings of the old type. Secret and trusted tokens may call it.","tags":["license_services"],"parameters":[{"name":"license_service_id","in":"path","required":true,"description":"The license service id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"description":"The fields to change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/license_service_request"},"example":{"configuration":{"remove_after_use":false}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The updated license service.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/license_service"},"example":{"object":"license_service","url":"https://api.comecero.com/api/v1/license_services/0095012789659LsuOeAWLC","license_service_id":"0095012789659LsuOeAWLC","date_created":"2026-11-02T16:26:29Z","date_modified":"2026-11-02T16:45:25Z","test":true,"account_id":"AB1234","name":"Widget Pro keys","label":"License Code","description":null,"instructions":"Open Widget Pro, choose Help, then Enter License, and paste the code.","type":"remote_url","expand":null,"show":null,"hide":null,"configuration":{"url":"https://licenses.example.com/issue","format":"json","http_authorization_username":null,"http_authorization_password":null,"custom_header_name":null,"custom_header_value":null}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"summary":"Delete a license service","operationId":"delete_license_service","description":"Deletes a license service for good. It is not checked whether products still use it, so remove it from your products first. Licenses already issued are kept. Secret and trusted tokens may call it.","tags":["license_services"],"parameters":[{"name":"license_service_id","in":"path","required":true,"description":"The license service id.","schema":{"type":"string"}}],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The license service is deleted. No body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/licenses":{"get":{"summary":"List licenses","operationId":"list_licenses","description":"Returns the license keys issued for your orders, oldest first unless you send `desc=true`. Secret and trusted tokens may call it.","tags":["licenses"],"parameters":[{"$ref":"#/components/parameters/after_item"},{"$ref":"#/components/parameters/before_item"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/date_start"},{"$ref":"#/components/parameters/date_end"},{"name":"date_type","in":"query","description":"Which date `date_start` and `date_end` filter on. The default is `date_created`.","schema":{"type":"string","enum":["date_created","date_modified"]}},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"name":"q","in":"query","description":"A license id. Returns only that license.","schema":{"type":"string"}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of licenses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/license_list"},"example":{"next_page_url":null,"next_page_after_item":null,"previous_page_url":null,"previous_page_before_item":null,"data":[{"object":"license","url":"https://api.comecero.com/api/v1/licenses/0142130710581LiRr8sT2c","license_id":"0142130710581LiRr8sT2c","date_created":"2026-11-02T00:45:11Z","date_modified":"2026-11-02T00:45:11Z","test":true,"item_id":"widget-pro.test","account_id":"AB1234","label":"License Code","license_service":"https://api.comecero.com/api/v1/license_services/0095012789659LsuOeAWLC","order":"https://api.comecero.com/api/v1/orders/6622-NXKHE-858","product":"https://api.comecero.com/api/v1/products/widget-pro.test","text":"AAAA-BBBB-CCCC-0001","html":"AAAA-BBBB-CCCC-0001","instructions":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Create a license","operationId":"create_license","description":"Gets a new license key from a license service for one item of an order, saves it and adds it to the order item. Use it to issue a key by hand. A license request is recorded either way. For a `remote_url` service your server is called during this request, and its failure is returned as `502`. Send `save: false` to fetch a key without saving it. Secret and trusted tokens may call it.","tags":["licenses"],"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"description":"Which service, order and item the key is for.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/license_create_request"},"examples":{"minimal":{"summary":"Assign a key to an order","value":{"license_service_id":"0095012789659LsuOeAWLC","order_id":"7393-GMRFY-954","product_id":"widget-pro.test"}},"full":{"summary":"With the account","value":{"license_service_id":"0095012789659LsuOeAWLC","order_id":"6622-NXKHE-858","product_id":"widget-pro.test","account_id":"AB1234"}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new license.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/license"},"example":{"object":"license","url":"https://api.comecero.com/api/v1/licenses/0142130710581LiRr8sT2c","license_id":"0142130710581LiRr8sT2c","date_created":"2026-11-02T00:45:11Z","date_modified":"2026-11-02T00:45:11Z","test":true,"item_id":"widget-pro.test","account_id":"AB1234","label":"License Code","license_service":"https://api.comecero.com/api/v1/license_services/0095012789659LsuOeAWLC","order":"https://api.comecero.com/api/v1/orders/6622-NXKHE-858","product":"https://api.comecero.com/api/v1/products/widget-pro.test","text":"AAAA-BBBB-CCCC-0001","html":"AAAA-BBBB-CCCC-0001","instructions":"Open Widget Pro, choose Help, then Enter License, and paste the code."}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"Your license server did not return a key. The error says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}}}},"/licenses/{license_id}":{"get":{"summary":"Get a license","operationId":"get_license","description":"Returns one license key. A limited token may read it only when the license is bound to the token, such as a license on the signed-in customer's order. Secret, trusted and limited tokens may call it.","tags":["licenses"],"x-limited":true,"parameters":[{"name":"license_id","in":"path","required":true,"description":"The license id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The license.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/license"},"example":{"object":"license","url":"https://api.comecero.com/api/v1/licenses/0142130710581LiRr8sT2c","license_id":"0142130710581LiRr8sT2c","date_created":"2026-11-02T00:45:11Z","date_modified":"2026-11-02T00:45:11Z","test":true,"item_id":"widget-pro.test","account_id":"AB1234","label":"License Code","license_service":"https://api.comecero.com/api/v1/license_services/0095012789659LsuOeAWLC","order":"https://api.comecero.com/api/v1/orders/6622-NXKHE-858","product":"https://api.comecero.com/api/v1/products/widget-pro.test","text":"AAAA-BBBB-CCCC-0001","html":"AAAA-BBBB-CCCC-0001","instructions":"Open Widget Pro, choose Help, then Enter License, and paste the code."}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/notification_subscriptions":{"get":{"operationId":"list_notification_subscriptions","summary":"List notification subscriptions","description":"Lists your notification subscriptions: which customer emails are on, and how each is sent. The list is offset-based. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["notification_subscriptions"],"parameters":[{"name":"active","in":"query","required":false,"description":"`true` for active subscriptions only, `false` for inactive ones only.","schema":{"type":"boolean"}},{"name":"q","in":"query","required":false,"description":"An exact notification subscription id, or a type such as `order:confirmation`.","schema":{"type":"string"}},{"name":"sort_by","in":"query","required":false,"description":"The field to sort by. Any other value uses the default.","schema":{"type":"string","enum":["date_created","date_modified","type"],"default":"date_created"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of notification subscriptions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/notification_subscription_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/notification_subscriptions","data":[{"object":"notification_subscription","url":"https://api.comecero.com/api/v1/notification_subscriptions/1102500112233NSd4Kw9Tz","notification_subscription_id":"1102500112233NSd4Kw9Tz","date_created":"2026-10-01T09:00:00Z","date_modified":"2026-10-01T09:00:00Z","test":true,"type":"shipment:confirmation","active":true,"account_id":"AB1234","method":"email","from":null,"from_name":"Example Shop","reply_to":"support@example.com","bcc":null,"subject":"Your order {{order.order_id}} has shipped","template":null,"comments":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"create_notification_subscription","summary":"Create a notification subscription","description":"Turns on one kind of customer email, such as the shipment confirmation. Send `active: true`, because a new subscription is inactive by default. Only one subscription per type may be active (`409`). A `from` address that is not verified is refused (`422`). Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["notification_subscriptions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/notification_subscription_request"},{"required":["type","method"]}]},"examples":{"minimal":{"summary":"Turn on the order confirmation email","value":{"type":"order:confirmation","method":"email","active":true}},"full":{"summary":"Shipment email with your own sender and subject","value":{"type":"shipment:confirmation","method":"email","active":true,"from_name":"Example Shop","reply_to":"support@example.com","subject":"Your order {{order.order_id}} has shipped"}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new notification subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/notification_subscription"},"example":{"object":"notification_subscription","url":"https://api.comecero.com/api/v1/notification_subscriptions/1102500112233NSd4Kw9Tz","notification_subscription_id":"1102500112233NSd4Kw9Tz","date_created":"2026-10-01T09:00:00Z","date_modified":"2026-10-01T09:00:00Z","test":true,"type":"shipment:confirmation","active":true,"account_id":"AB1234","method":"email","from":null,"from_name":"Example Shop","reply_to":"support@example.com","bcc":null,"subject":"Your order {{order.order_id}} has shipped","template":null,"comments":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/notification_subscriptions/{notification_subscription_id}":{"get":{"operationId":"get_notification_subscription","summary":"Get a notification subscription","description":"Gets one notification subscription. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["notification_subscriptions"],"parameters":[{"name":"notification_subscription_id","in":"path","required":true,"description":"The notification subscription id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The notification subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/notification_subscription"},"example":{"object":"notification_subscription","url":"https://api.comecero.com/api/v1/notification_subscriptions/1102500112233NSd4Kw9Tz","notification_subscription_id":"1102500112233NSd4Kw9Tz","date_created":"2026-10-01T09:00:00Z","date_modified":"2026-10-01T09:00:00Z","test":true,"type":"shipment:confirmation","active":true,"account_id":"AB1234","method":"email","from":null,"from_name":"Example Shop","reply_to":"support@example.com","bcc":null,"subject":"Your order {{order.order_id}} has shipped","template":null,"comments":null}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"update_notification_subscription","summary":"Update a notification subscription","description":"Changes the fields you send and leaves the others as they are. An empty string clears a field. Send `template_id: null` to go back to the built-in template. When you send `active: true` together with `type`, also send `notification_subscription_id` in the body, or the check for a second active subscription of that type counts this one and answers `409`. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["notification_subscriptions"],"parameters":[{"name":"notification_subscription_id","in":"path","required":true,"description":"The notification subscription id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/notification_subscription_request"},"example":{"subject":"Your package is on its way"}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The updated notification subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/notification_subscription"},"example":{"object":"notification_subscription","url":"https://api.comecero.com/api/v1/notification_subscriptions/1102500112233NSd4Kw9Tz","notification_subscription_id":"1102500112233NSd4Kw9Tz","date_created":"2026-10-01T09:00:00Z","date_modified":"2026-10-01T09:00:00Z","test":true,"type":"shipment:confirmation","active":true,"account_id":"AB1234","method":"email","from":null,"from_name":"Example Shop","reply_to":"support@example.com","bcc":null,"subject":"Your order {{order.order_id}} has shipped","template":null,"comments":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"operationId":"delete_notification_subscription","summary":"Delete a notification subscription","description":"Deletes the notification subscription, so that kind of email is no longer sent. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["notification_subscriptions"],"parameters":[{"name":"notification_subscription_id","in":"path","required":true,"description":"The notification subscription id.","schema":{"type":"string"}}],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The notification subscription was deleted. There is no body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/notifications":{"get":{"operationId":"list_notifications","summary":"List notifications","description":"Lists the customer emails Comecero sent or is trying to send. With no `status`, only `delivered` ones are listed. In the list, `body` is left out; get one notification to read it. Notifications are kept for 120 days (15 in test mode). The list is cursor-based and sorted by `date_created`. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["notifications"],"parameters":[{"name":"status","in":"query","required":false,"description":"Only notifications with this status. The default is `delivered`.","schema":{"type":"string","enum":["queued","delivered","retry","failed"],"default":"delivered"}},{"name":"q","in":"query","required":false,"description":"An exact notification id. It is found only when it also matches `status`, so send `status` with it. Anything that is not a notification id returns an empty list.","schema":{"type":"string"}},{"$ref":"#/components/parameters/date_start"},{"$ref":"#/components/parameters/date_end"},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/after_item"},{"$ref":"#/components/parameters/before_item"},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of notifications.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/notification_list"},"example":{"next_page_url":null,"next_page_after_item":null,"previous_page_url":null,"previous_page_before_item":null,"data":[{"object":"notification","url":"https://api.comecero.com/api/v1/notifications/1102611073905NOq2Lx7Pv","notification_id":"1102611073905NOq2Lx7Pv","test":true,"account_id":"AB1234","type":"order:confirmation","method":"email","from":"notification@comecero.com","from_name":"Example Shop","reply_to":"support@example.com","bcc":null,"destination":"john@example.com","subject":"Your Order Confirmation","notification_subscription":"https://api.comecero.com/api/v1/notification_subscriptions/1102500112233NSd4Kw9Tz","customer":"https://api.comecero.com/api/v1/customers/1102611073801CUa8Hn2Lq","status":"delivered","date_created":"2026-11-07T14:32:12Z","date_modified":"2026-11-07T14:32:14Z","data":{"order":{"order_id":"7393-GMRFY-954"}},"body":"To obtain the notification body, access this resource directly."}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"send_notification","summary":"Send an email","description":"Builds an email from one of your templates and your `data`, and sends it now to one address. Use it for emails Comecero has no notification type for. It is not saved: the answer has no `notification_id` and the email is not listed later, and a failed send is not retried. Only a live account may call it (`422` before your account is live). The `from` address must be one of your verified notification addresses. Answers `200`, not `201`. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["notifications"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/notification_request"},"examples":{"email":{"summary":"Send an email from a template","value":{"method":"email","destination":"john@example.com","from":"orders@example.com","from_name":"Example Shop","reply_to":"support@example.com","subject":"Your download is ready","template_id":"1102500900112TEm5Jc3Rw","data":{"customer":{"first_name":"John"},"download_url":"https://example.com/downloads/abc123"}}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The email that was sent. `url`, `notification_id`, `type`, `data`, `notification_subscription` and `customer` are `null`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/notification"},"example":{"object":"notification","url":null,"notification_id":null,"test":false,"account_id":"AB1234","type":null,"method":"email","from":"orders@example.com","from_name":"Example Shop","reply_to":"support@example.com","bcc":null,"destination":"john@example.com","subject":"Your download is ready","notification_subscription":null,"customer":null,"status":"delivered","date_created":"2026-11-07T15:10:00Z","date_modified":"2026-11-07T15:10:00Z","data":null,"body":"<p>Hi John, your download is ready: https://example.com/downloads/abc123</p>"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/notifications/{notification_id}":{"get":{"operationId":"get_notification","summary":"Get a notification","description":"Gets one notification, with the `body` that was sent. Send `debug=true` to see retry details and why the last attempt failed. Secret, trusted and limited tokens may call it. A limited token only sees notifications to the customer it is bound to (`403` otherwise).","tags":["notifications"],"x-limited":true,"parameters":[{"name":"notification_id","in":"path","required":true,"description":"The notification id.","schema":{"type":"string"}},{"name":"debug","in":"query","required":false,"description":"When `true`, the notification also has `retry_count`, `date_last_delivery_attempt`, `date_next_delivery_attempt` and `last_failure_meta`.","schema":{"type":"boolean","default":false}},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The notification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/notification"},"example":{"object":"notification","url":"https://api.comecero.com/api/v1/notifications/1102611073905NOq2Lx7Pv","notification_id":"1102611073905NOq2Lx7Pv","test":true,"account_id":"AB1234","type":"order:confirmation","method":"email","from":"notification@comecero.com","from_name":"Example Shop","reply_to":"support@example.com","bcc":null,"destination":"john@example.com","subject":"Your Order Confirmation","notification_subscription":"https://api.comecero.com/api/v1/notification_subscriptions/1102500112233NSd4Kw9Tz","customer":"https://api.comecero.com/api/v1/customers/1102611073801CUa8Hn2Lq","status":"delivered","date_created":"2026-11-07T14:32:12Z","date_modified":"2026-11-07T14:32:14Z","data":{"order":{"order_id":"7393-GMRFY-954","total":99.95,"currency":"USD"}},"body":"<html><body><h1>Thanks for your order</h1></body></html>"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/notifications/{notification_id}/resend":{"post":{"operationId":"resend_notification","summary":"Resend a notification","description":"Sends the notification again now, to its original recipients or to one `destination` you send. An order confirmation is rebuilt first, so it has the order's current license keys; while a key is still pending it cannot be sent (`422`) and goes out by itself once the key arrives. When the send fails the answer is `422` with the reason, the notification is marked `failed`, and it is not retried. Secret, trusted and limited tokens may call it. A limited token may only resend notifications to the customer it is bound to (`403` otherwise).","tags":["notifications"],"x-limited":true,"parameters":[{"name":"notification_id","in":"path","required":true,"description":"The notification id.","schema":{"type":"string"}},{"name":"debug","in":"query","required":false,"description":"When `true`, the answer includes retry details.","schema":{"type":"boolean","default":false}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","title":"notification_resend_request","properties":{"destination":{"type":"string","format":"email","description":"One email address to send to instead of the original recipients. Leave the body out to resend to them."}}},"example":{"destination":"john@example.com"}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The notification after it was sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/notification"},"example":{"object":"notification","url":"https://api.comecero.com/api/v1/notifications/1102611073905NOq2Lx7Pv","notification_id":"1102611073905NOq2Lx7Pv","test":true,"account_id":"AB1234","type":"order:confirmation","method":"email","from":"notification@comecero.com","from_name":"Example Shop","reply_to":"support@example.com","bcc":null,"destination":"john@example.com","subject":"Your Order Confirmation","notification_subscription":"https://api.comecero.com/api/v1/notification_subscriptions/1102500112233NSd4Kw9Tz","customer":"https://api.comecero.com/api/v1/customers/1102611073801CUa8Hn2Lq","status":"delivered","date_created":"2026-11-07T14:32:12Z","date_modified":"2026-11-07T14:32:14Z","data":{"order":{"order_id":"7393-GMRFY-954","total":99.95,"currency":"USD"}},"body":"<html><body><h1>Thanks for your order</h1></body></html>"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/orders":{"get":{"operationId":"list_orders","summary":"List orders","description":"Lists your orders, oldest first unless you send `desc=true`. There is no way to create an order directly: the API makes one when a payment on a cart or an invoice succeeds or is authorized.\n\nThe list is cursor-based: use `after_item` and `before_item` (or the `next_page_url` and `previous_page_url` in the response). It is ordered by the date named in `date_type` (`date_created` by default; `date_modified` and `date_completed` also work). `sort_by` is ignored.\n\nNeeds a secret or trusted token. Limited tokens get `403`; a customer reads their own orders with `GET /customers/{customer_id}/orders`.","tags":["orders"],"parameters":[{"name":"payment_status","in":"query","description":"Only orders with this payment status.","required":false,"schema":{"type":"string","enum":["pending","completed","cancelled","refunded"]}},{"name":"fulfilled","in":"query","description":"Only fulfilled (`true`) or not fulfilled (`false`) orders.","required":false,"schema":{"type":"boolean"}},{"name":"q","in":"query","description":"Search. Matches the exact order id or customer email, or part of the customer's name or company name.","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/date_start"},{"$ref":"#/components/parameters/date_end"},{"$ref":"#/components/parameters/date_type"},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/after_item"},{"$ref":"#/components/parameters/before_item"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A cursor-based page of orders.","content":{"application/json":{"schema":{"title":"order_list","allOf":[{"$ref":"#/components/schemas/list_cursor"},{"type":"object","properties":{"data":{"type":"array","description":"The orders on this page.","items":{"$ref":"#/components/schemas/order"}}}}]},"example":{"next_page_url":"https://api.comecero.com/api/v1/orders?after_item=7393-GMRFY-954&payment_status=completed","next_page_after_item":"7393-GMRFY-954","previous_page_url":null,"previous_page_before_item":null,"current_page_url":"https://api.comecero.com/api/v1/orders?payment_status=completed","data":[{"object":"order","url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954","order_id":"7393-GMRFY-954","date_created":"2026-11-02T16:46:16Z","date_modified":"2026-11-02T16:46:38Z","test":true,"account_id":"AB1234","payment_status":"completed","fulfilled":true,"currency":"USD","subtotal":49.95,"subtotal_original":49.95,"shipping":0,"shipping_original":0,"discount":0,"item_discounts":0,"total_discounts":0,"total_discounts_percent":0,"tax":0,"tax_original":0,"total":49.95,"total_original":49.95,"tax_inclusive":false,"discount_on_gross":false,"settlement_currency":"USD","settlement_subtotal":49.95,"settlement_subtotal_original":49.95,"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":49.95,"settlement_total_original":49.95,"customer_ip_address":"203.0.113.24","customer_ip_country":"US","referrer":null,"affiliate_id":null,"promotion_code":null,"items_count":1,"items_quantity":1,"items":[{"object":"order_item","url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/items/1","item_id":"1","date_created":"2026-11-02T16:46:16Z","date_modified":"2026-11-02T16:46:16Z","product_id":"pdf-pro.test","order_id":"7393-GMRFY-954","name":"PDF Viewer Pro","type":"digital","quantity":1,"currency":"USD","price":49.95,"price_original":49.95,"subtotal":49.95,"subtotal_original":49.95,"discount":0,"discount_percent":0,"tax":0,"tax_original":0,"total":49.95,"total_original":49.95,"tax_rate":0,"fulfilled":true,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription":null,"subscription_terms":null,"shipments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/items/1/shipments","license":null,"download":"https://api.comecero.com/api/v1/downloads/0093717990011DlR4kQp2a","meta":null}],"shipping_item":null,"customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","cart":"https://api.comecero.com/api/v1/carts/0093717976083CaO5bXdLA","payments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/payments","payment":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/payments","subscription":null,"refunds":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/refunds","fee_summary":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/fee_summary","invoice":null,"promotions":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/promotions","shipments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/shipments","meta":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/orders/{order_id}":{"get":{"operationId":"get_order","summary":"Get an order","description":"Returns one order with its items.\n\n**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`.\n\nSecret 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.","tags":["orders"],"x-limited":true,"parameters":[{"name":"order_id","in":"path","description":"The order id, for example `7393-GMRFY-954`.","required":true,"schema":{"type":"string"}},{"name":"Accept","in":"header","description":"Send `application/pdf` to get a PDF receipt instead of JSON.","required":false,"schema":{"type":"string","enum":["application/json","application/pdf"]}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/timezone"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The order, as JSON or as a PDF.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/order"},"example":{"object":"order","url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954","order_id":"7393-GMRFY-954","date_created":"2026-11-02T16:46:16Z","date_modified":"2026-11-02T16:46:38Z","test":true,"account_id":"AB1234","payment_status":"completed","fulfilled":true,"currency":"USD","subtotal":49.95,"subtotal_original":49.95,"shipping":0,"shipping_original":0,"discount":0,"item_discounts":0,"total_discounts":0,"total_discounts_percent":0,"tax":0,"tax_original":0,"total":49.95,"total_original":49.95,"tax_inclusive":false,"discount_on_gross":false,"settlement_currency":"USD","settlement_subtotal":49.95,"settlement_subtotal_original":49.95,"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":49.95,"settlement_total_original":49.95,"customer_ip_address":"203.0.113.24","customer_ip_country":"US","referrer":null,"affiliate_id":null,"promotion_code":null,"items_count":1,"items_quantity":1,"items":[{"object":"order_item","url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/items/1","item_id":"1","cross_sell_id":null,"up_sell_id":null,"bundle_id":null,"bundle_group_id":null,"date_created":"2026-11-02T16:46:16Z","date_modified":"2026-11-02T16:46:16Z","product_id":"pdf-pro.test","order_id":"7393-GMRFY-954","name":"PDF Viewer Pro","type":"digital","quantity":1,"currency":"USD","price":49.95,"price_original":49.95,"reference_price":49.95,"reference_currency":"USD","subtotal":49.95,"subtotal_original":49.95,"discount":0,"discount_percent":0,"tax":0,"tax_original":0,"total":49.95,"total_original":49.95,"tax_rate":0,"tax_code":null,"settlement_currency":"USD","settlement_price":49.95,"settlement_price_original":49.95,"settlement_subtotal":49.95,"settlement_subtotal_original":49.95,"settlement_discount":0,"settlement_tax":0,"settlement_tax_original":0,"settlement_total":49.95,"settlement_total_original":49.95,"fulfilled":true,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription":null,"subscription_terms":null,"shipments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/items/1/shipments","license":null,"download":"https://api.comecero.com/api/v1/downloads/0093717990011DlR4kQp2a","meta":null}],"shipping_item":null,"customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","cart":"https://api.comecero.com/api/v1/carts/0093717976083CaO5bXdLA","payments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/payments","payment":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/payments","subscription":null,"refunds":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/refunds","fee_summary":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/fee_summary","invoice":null,"promotions":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/promotions","shipments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/shipments","meta":null}},"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/orders/{order_id}/capture":{"post":{"operationId":"capture_order","summary":"Capture an order","description":"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.\n\nReturns `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`.\n\nNeeds a secret or trusted token that may create or update payments. A token without that permission gets `401`, not `403`.","tags":["orders"],"parameters":[{"name":"order_id","in":"path","description":"The order id.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"}],"requestBody":{"required":false,"description":"Optional. Leave it out (no body, not `{}`) to capture everything authorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/order_capture_request"},"examples":{"part":{"summary":"Capture one item and shipping","value":{"items":[{"item_id":"1","quantity":1}],"shipping":5}},"amount":{"summary":"Capture an amount","value":{"total":50}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The capture was made for at least one payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/order_payment_list"},"example":{"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}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The payment provider refused the capture.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"No payment on the order is pending, or the amount is more than was authorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"The payment provider returned an error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"504":{"description":"The payment provider did not answer in time.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}}}},"/orders/{order_id}/fee_summary":{"get":{"operationId":"get_order_fee_summary","summary":"Get an order's fee summary","description":"Returns the Comecero fees on the order: the fees of all its payments and their refunds, added up per currency.\n\nNeeds a secret or trusted token that may read fees. Limited tokens are refused. A token without the fees permission gets `401`, not `403`.","tags":["orders"],"parameters":[{"name":"order_id","in":"path","description":"The order id.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The fee summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/order_fee_summary"},"example":{"object":"fee_summary","url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/fee_summary","fixed_amount":0.3,"percentage_amount":2.25,"total":2.55,"currency":"USD","totals":[{"currency":"USD","fixed_amount":0.3,"percentage_amount":2.25,"total":2.55}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/orders/{order_id}/items":{"get":{"operationId":"list_order_items","summary":"List an order's items","description":"Lists the lines on an order. Offset-based (`offset`, `limit`). With no `limit`, every item comes back on one page. `sort_by` takes `date_created` (default), `date_modified`, `product_id` or `item_id`.\n\nA limited token may call this for an order of its own customer.","tags":["orders"],"x-limited":true,"parameters":[{"name":"order_id","in":"path","description":"The order id.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/desc"},{"name":"sort_by","in":"query","description":"The field to sort by.","required":false,"schema":{"type":"string","default":"date_created","enum":["date_created","date_modified","product_id","item_id"]}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"An offset-based page of order items.","content":{"application/json":{"schema":{"title":"order_item_list","allOf":[{"$ref":"#/components/schemas/list_offset"},{"type":"object","properties":{"data":{"type":"array","description":"The items on this page.","items":{"$ref":"#/components/schemas/order_item"}}}}]},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/items","data":[{"object":"order_item","url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/items/1","item_id":"1","date_created":"2026-11-02T16:46:16Z","date_modified":"2026-11-02T16:46:16Z","product_id":"pdf-pro.test","order_id":"7393-GMRFY-954","name":"PDF Viewer Pro","type":"digital","quantity":1,"currency":"USD","price":49.95,"price_original":49.95,"subtotal":49.95,"subtotal_original":49.95,"discount":0,"discount_percent":0,"tax":0,"tax_original":0,"total":49.95,"total_original":49.95,"tax_rate":0,"fulfilled":true,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription":null,"subscription_terms":null,"shipments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/items/1/shipments","license":null,"download":"https://api.comecero.com/api/v1/downloads/0093717990011DlR4kQp2a","meta":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/orders/{order_id}/items/{item_id}":{"get":{"operationId":"get_order_item","summary":"Get an order item","description":"Returns one line of an order. A limited token may call this for an order of its own customer.","tags":["orders"],"x-limited":true,"parameters":[{"name":"order_id","in":"path","description":"The order id.","required":true,"schema":{"type":"string"}},{"name":"item_id","in":"path","description":"The item id within the order.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The order item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/order_item"},"example":{"object":"order_item","url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/items/1","item_id":"1","cross_sell_id":null,"up_sell_id":null,"bundle_id":null,"bundle_group_id":null,"date_created":"2026-11-02T16:46:16Z","date_modified":"2026-11-02T16:46:16Z","product_id":"pdf-pro.test","order_id":"7393-GMRFY-954","name":"PDF Viewer Pro","type":"digital","quantity":1,"currency":"USD","price":49.95,"price_original":49.95,"reference_price":49.95,"reference_currency":"USD","subtotal":49.95,"subtotal_original":49.95,"discount":0,"discount_percent":0,"tax":0,"tax_original":0,"total":49.95,"total_original":49.95,"tax_rate":0,"tax_code":null,"settlement_currency":"USD","settlement_price":49.95,"settlement_price_original":49.95,"settlement_subtotal":49.95,"settlement_subtotal_original":49.95,"settlement_discount":0,"settlement_tax":0,"settlement_tax_original":0,"settlement_total":49.95,"settlement_total_original":49.95,"fulfilled":true,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription":null,"subscription_terms":null,"shipments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/items/1/shipments","license":null,"download":"https://api.comecero.com/api/v1/downloads/0093717990011DlR4kQp2a","meta":null}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"update_order_item","summary":"Update an order item","description":"Changes `fulfilled` or `meta` on one line of an order. Use it to mark a digital or service item delivered when you fulfil it yourself. When the last open item is marked fulfilled, the order becomes fulfilled, any pending (authorized) payment is captured (money moves) and the `order:fulfilled` event fires. For physical goods, create a shipment instead: it marks items fulfilled for you.\n\nNeeds a secret or trusted token. Limited tokens get `403`.","tags":["orders"],"parameters":[{"name":"order_id","in":"path","description":"The order id.","required":true,"schema":{"type":"string"}},{"name":"item_id","in":"path","description":"The item id within the order.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/order_item_request"},"examples":{"fulfilled":{"summary":"Mark the item fulfilled","value":{"fulfilled":true}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The updated order item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/order_item"},"example":{"object":"order_item","url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/items/1","item_id":"1","cross_sell_id":null,"up_sell_id":null,"bundle_id":null,"bundle_group_id":null,"date_created":"2026-11-02T16:46:16Z","date_modified":"2026-11-02T16:46:16Z","product_id":"pdf-pro.test","order_id":"7393-GMRFY-954","name":"PDF Viewer Pro","type":"digital","quantity":1,"currency":"USD","price":49.95,"price_original":49.95,"reference_price":49.95,"reference_currency":"USD","subtotal":49.95,"subtotal_original":49.95,"discount":0,"discount_percent":0,"tax":0,"tax_original":0,"total":49.95,"total_original":49.95,"tax_rate":0,"tax_code":null,"settlement_currency":"USD","settlement_price":49.95,"settlement_price_original":49.95,"settlement_subtotal":49.95,"settlement_subtotal_original":49.95,"settlement_discount":0,"settlement_tax":0,"settlement_tax_original":0,"settlement_total":49.95,"settlement_total_original":49.95,"fulfilled":true,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription":null,"subscription_terms":null,"shipments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/items/1/shipments","license":null,"download":"https://api.comecero.com/api/v1/downloads/0093717990011DlR4kQp2a","meta":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/orders/{order_id}/items/{item_id}/shipments":{"get":{"operationId":"list_order_item_shipments","summary":"List an item's shipments","description":"Lists the shipments of an order that contain this item. Offset-based (`offset`, `limit`). `sort_by` takes `date_created` (default) or `date_modified`.\n\nA limited token may call this for an order of its own customer.","tags":["orders"],"x-limited":true,"parameters":[{"name":"order_id","in":"path","description":"The order id.","required":true,"schema":{"type":"string"}},{"name":"item_id","in":"path","description":"The item id within the order.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/desc"},{"name":"sort_by","in":"query","description":"The field to sort by.","required":false,"schema":{"type":"string","default":"date_created","enum":["date_created","date_modified"]}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"An offset-based page of shipments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/shipment_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/orders/2979-KXVST-674/items/1/shipments","data":[{"object":"shipment","url":"https://api.comecero.com/api/v1/shipments/0093718200417ShQ2xN8kL","shipment_id":"0093718200417ShQ2xN8kL","date_created":"2026-11-04T09:30:00Z","date_modified":"2026-11-04T09:30:00Z","date_shipped":"2026-11-04T09:30:00Z","test":true,"account_id":"AB1234","items":[{"object":"shipment_item","item_id":"1","product_id":"lens-cloth.test","name":"Lens cleaning cloth","quantity":2,"product":"https://api.comecero.com/api/v1/products/lens-cloth.test"}],"order":"https://api.comecero.com/api/v1/orders/2979-KXVST-674","courier":"UPS","tracking_number":"1Z999AA10123456784","tracking_url":"http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784","notifications":"https://api.comecero.com/api/v1/shipments/0093718200417ShQ2xN8kL/notifications","meta":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/orders/{order_id}/notifications":{"get":{"operationId":"list_order_notifications","summary":"List an order's notifications","description":"Lists the emails sent to the customer about this order, such as the order receipt. Offset-based (`offset`, `limit`). `sort_by` takes `date_created` (default) or `date_modified`.\n\nA limited token may call this for an order of its own customer.","tags":["orders"],"x-limited":true,"parameters":[{"name":"order_id","in":"path","description":"The order id.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/desc"},{"name":"sort_by","in":"query","description":"The field to sort by.","required":false,"schema":{"type":"string","default":"date_created","enum":["date_created","date_modified"]}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"An offset-based page of notifications.","content":{"application/json":{"schema":{"title":"notification_list","allOf":[{"$ref":"#/components/schemas/list_offset"},{"type":"object","properties":{"data":{"type":"array","description":"The notifications on this page.","items":{"$ref":"#/components/schemas/notification"}}}}]},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/notifications","data":[{"object":"notification","url":"https://api.comecero.com/api/v1/notifications/0093717991410NtM2fKc8a","notification_id":"0093717991410NtM2fKc8a","test":true,"account_id":"AB1234","type":"order:confirmation","method":"email","from":"notification@comecero.com","from_name":"Example Shop","reply_to":"support@example.com","bcc":null,"destination":"john@example.com","subject":"Your Order Confirmation","customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","status":"delivered","date_created":"2026-11-03T10:12:45Z","date_modified":"2026-11-03T10:12:47Z"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/orders/{order_id}/payments":{"get":{"operationId":"list_order_payments","summary":"List an order's payments","description":"Lists every payment made on the order, including failed ones. Most orders have one payment; an order paid partly with store credit, or a renewal retried after a decline, can have more. Offset-based (`offset`, `limit`). `sort_by` takes `date_created` (default) or `date_modified`.\n\nA limited token may call this for an order of its own customer.","tags":["orders"],"x-limited":true,"parameters":[{"name":"order_id","in":"path","description":"The order id.","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","description":"Only payments with this status.","required":false,"schema":{"type":"string","enum":["initiated","processing","pending","completed","failed","cancelled","refunded"]}},{"name":"reference","in":"query","description":"Only payments with this exact `reference`.","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/desc"},{"name":"sort_by","in":"query","description":"The field to sort by.","required":false,"schema":{"type":"string","default":"date_created","enum":["date_created","date_modified"]}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"An offset-based page of payments.","content":{"application/json":{"schema":{"title":"payment_offset_list","allOf":[{"$ref":"#/components/schemas/list_offset"},{"type":"object","properties":{"data":{"type":"array","description":"The payments on this page.","items":{"$ref":"#/components/schemas/payment"}}}}]},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/payments","data":[{"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}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/orders/{order_id}/promotions":{"get":{"operationId":"list_order_promotions","summary":"List an order's promotions","description":"Lists the promotions used on the order: the coupon, and any cross-sell or up-sell offers the items came from. Offset-based (`offset`, `limit`). `sort_by` takes `date_created` (default), `date_modified`, `promotion_id` or `name`.\n\nA limited token may call this for an order of its own customer.","tags":["orders"],"x-limited":true,"parameters":[{"name":"order_id","in":"path","description":"The order id.","required":true,"schema":{"type":"string"}},{"name":"active","in":"query","description":"Only active (`true`) or inactive (`false`) promotions.","required":false,"schema":{"type":"boolean"}},{"name":"q","in":"query","description":"Search by exact promotion id or part of the name.","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/desc"},{"name":"sort_by","in":"query","description":"The field to sort by.","required":false,"schema":{"type":"string","default":"date_created","enum":["date_created","date_modified","promotion_id","name"]}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"An offset-based page of promotions.","content":{"application/json":{"schema":{"title":"promotion_list","allOf":[{"$ref":"#/components/schemas/list_offset"},{"type":"object","properties":{"data":{"type":"array","description":"The promotions on this page.","items":{"$ref":"#/components/schemas/promotion"}}}}]},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/promotions","data":[{"object":"promotion","url":"https://api.comecero.com/api/v1/promotions/0070576784690PtKDqfI","promotion_id":"0070576784690PtKDqfI","name":"Ten percent off","test":true,"account_id":"AB1234","date_created":"2026-11-02T20:13:16Z","date_modified":"2026-11-02T20:13:16Z","type":"coupon","active":true,"apply_to_recurring":false,"apply_to_recurring_count":null,"use_count":4,"expires":"2026-12-31T23:59:59Z","comments":null,"config":{"type":"order","code":"SAVE10","generator_prefix":null,"generator_secret_key":null,"discount_percent":0.1,"discount_amount":null,"product_ids":null,"exclude_product_ids":false,"max_uses_per_customer":1,"max_uses_global":null}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/orders/{order_id}/refunds":{"get":{"operationId":"list_order_refunds","summary":"List an order's refunds","description":"Lists the refunds on an order, including failed and pending ones and chargebacks. Offset-based (`offset`, `limit`). `sort_by` takes `date_created` (default), `date_modified` or `date_completed`.\n\nA limited token may call this for an order of its own customer.","tags":["orders"],"x-limited":true,"parameters":[{"name":"order_id","in":"path","description":"The order id.","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","description":"Only refunds with this status.","required":false,"schema":{"type":"string","enum":["pending","completed","failed"]}},{"name":"is_chargeback","in":"query","description":"Only chargebacks (`true`) or only refunds (`false`).","required":false,"schema":{"type":"boolean"}},{"name":"reference","in":"query","description":"Only refunds with this exact `reference`.","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/desc"},{"name":"sort_by","in":"query","description":"The field to sort by.","required":false,"schema":{"type":"string","default":"date_created","enum":["date_created","date_modified","date_completed"]}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"An offset-based page of refunds.","content":{"application/json":{"schema":{"title":"refund_offset_list","allOf":[{"$ref":"#/components/schemas/list_offset"},{"type":"object","properties":{"data":{"type":"array","description":"The refunds on this page.","items":{"$ref":"#/components/schemas/refund"}}}}]},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/refunds","data":[{"object":"refund","url":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5","refund_id":"0090374314462Rec3PffZ5","account_id":"AB1234","success":true,"status":"completed","reference":null,"date_created":"2026-11-03T10:12:40Z","date_modified":"2026-11-03T10:12:41Z","date_completed":"2026-11-03T10:12:41Z","test":true,"currency":"USD","subtotal":49.95,"shipping":0,"tax":0,"total":49.95,"reason":"Customer request","apply_to_balance":false,"is_chargeback":false,"record_only":false,"record_only_memo":null,"response_code":"OK","response_message":"OK","gateway_transaction_id":"re_test_3PffZ5","gateway_error_code":null,"gateway_error_message":null,"gateway":"https://api.comecero.com/api/v1/gateways/0089584408915Gtf5AsdJ8","comments":null,"payment_method":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/payment_method","settlement_currency":"USD","settlement_subtotal":49.95,"settlement_shipping":0,"settlement_tax":0,"settlement_total":49.95,"fx_rate":1,"reporting_currency":"USD","reporting_subtotal":49.95,"reporting_shipping":0,"reporting_tax":0,"reporting_total":49.95,"reporting_fx_rate":1,"items":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/items","customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","order":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954","payment":"https://api.comecero.com/api/v1/payments/0093717991362PyRYN1qc6","invoice":null,"fees":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fees","fee_summary":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fee_summary","commissions":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/commissions","meta":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"refund_order","summary":"Refund an order","description":"Gives money back to the customer. Money moves.\n\n**An empty body is a full refund.** Send no body (or `{}`) to refund everything on the order that has not been refunded yet. For a partial refund send one of `total`, `tax`, `items` or `shipping` (`items` and `shipping` may go together); the API works out the rest.\n\nAn order can have more than one payment. The refund is spread over them, largest payment first and store credit payments last, so the response is a `refund_list` with one refund per payment used, not a single refund. Each refund has its own `success` and `status`; a refund can stay `pending` until the payment provider confirms it. When every refund fails, the API answers with an error instead and puts the `refund_list` in the error's `meta.refund_list`. The order's `payment_status` becomes `refunded` once the whole amount is refunded. For each refund, `refund:created_success` fires when it completes (later, for a pending one) and the customer gets the refund email; `refund:created_failure` fires when it fails. A chargeback sends no email and cancels the subscription the order belongs to.\n\nTo refund one payment of an order, or to record a chargeback on an order with more than one payment, use `POST /payments/{payment_id}/refunds`.\n\nNeeds a secret or trusted token. Limited tokens get `403`.","tags":["refunds"],"parameters":[{"name":"order_id","in":"path","description":"The order id.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"}],"requestBody":{"$ref":"#/components/requestBodies/refund_request"},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"At least one refund succeeded or is pending. Check `failure_count` for refunds that failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/refund_list"},"example":{"object":"refund_list","url":"https://api.comecero.com/api/v1/refund_list/0090374314470RlA8kWm3T","refund_list_id":"0090374314470RlA8kWm3T","test":true,"account_id":"AB1234","currency":"USD","subtotal":49.95,"shipping":0,"tax":0,"total":49.95,"success_count":1,"failure_count":0,"refunds":[{"object":"refund","url":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5","refund_id":"0090374314462Rec3PffZ5","account_id":"AB1234","success":true,"status":"completed","reference":null,"date_created":"2026-11-03T10:12:40Z","date_modified":"2026-11-03T10:12:41Z","date_completed":"2026-11-03T10:12:41Z","test":true,"currency":"USD","subtotal":49.95,"shipping":0,"tax":0,"total":49.95,"reason":"Customer request","apply_to_balance":false,"is_chargeback":false,"record_only":false,"record_only_memo":null,"response_code":"OK","response_message":"OK","gateway_transaction_id":"re_test_3PffZ5","gateway_error_code":null,"gateway_error_message":null,"gateway":"https://api.comecero.com/api/v1/gateways/0089584408915Gtf5AsdJ8","comments":null,"payment_method":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/payment_method","settlement_currency":"USD","settlement_subtotal":49.95,"settlement_shipping":0,"settlement_tax":0,"settlement_total":49.95,"fx_rate":1,"reporting_currency":"USD","reporting_subtotal":49.95,"reporting_shipping":0,"reporting_tax":0,"reporting_total":49.95,"reporting_fx_rate":1,"items":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/items","customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","order":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954","payment":"https://api.comecero.com/api/v1/payments/0093717991362PyRYN1qc6","invoice":null,"fees":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fees","fee_summary":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fee_summary","commissions":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/commissions","meta":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The payment provider refused the refund. The `refund_list` is in `meta.refund_list`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"The refund cannot be made in this state, for example a live refund while the account is not live yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"The payment provider returned an error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"504":{"description":"The payment provider did not answer in time.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}}}},"/orders/{order_id}/shipments":{"get":{"operationId":"list_order_shipments","summary":"List an order's shipments","description":"Lists the shipments made for an order. Offset-based (`offset`, `limit`). `sort_by` takes `date_created` (default) or `date_modified`.\n\nA limited token may call this for an order of its own customer.","tags":["orders"],"x-limited":true,"parameters":[{"name":"order_id","in":"path","description":"The order id.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/desc"},{"name":"sort_by","in":"query","description":"The field to sort by.","required":false,"schema":{"type":"string","default":"date_created","enum":["date_created","date_modified"]}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"An offset-based page of shipments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/shipment_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/orders/2979-KXVST-674/shipments","data":[{"object":"shipment","url":"https://api.comecero.com/api/v1/shipments/0093718200417ShQ2xN8kL","shipment_id":"0093718200417ShQ2xN8kL","date_created":"2026-11-04T09:30:00Z","date_modified":"2026-11-04T09:30:00Z","date_shipped":"2026-11-04T09:30:00Z","test":true,"account_id":"AB1234","items":[{"object":"shipment_item","item_id":"1","product_id":"lens-cloth.test","name":"Lens cleaning cloth","quantity":2,"product":"https://api.comecero.com/api/v1/products/lens-cloth.test"}],"order":"https://api.comecero.com/api/v1/orders/2979-KXVST-674","courier":"UPS","tracking_number":"1Z999AA10123456784","tracking_url":"http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784","notifications":"https://api.comecero.com/api/v1/shipments/0093718200417ShQ2xN8kL/notifications","meta":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"create_order_shipment","summary":"Create a shipment","description":"Records a parcel sent for the order: the items and quantities in it, and the carrier and tracking number. Each item is marked fulfilled once all of its units have shipped. When that makes the whole order fulfilled, any pending (authorized) payment is captured (money moves) and the `order:fulfilled` event fires. The `shipment:created` event fires and the customer is sent the shipment email.\n\nNeeds a secret or trusted token. Limited tokens get `403`.","tags":["shipments"],"parameters":[{"name":"order_id","in":"path","description":"The order id.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/shipment_request"},"examples":{"shipment":{"summary":"Ship two units with tracking","value":{"items":[{"item_id":"1","quantity":2}],"courier":"UPS","tracking_number":"1Z999AA10123456784"}},"with_url":{"summary":"With the ship date and tracking link","value":{"items":[{"item_id":"1","quantity":1}],"date_shipped":"2026-11-07T16:00:00Z","courier":"FedEx","tracking_number":"771234567890","tracking_url":"https://www.fedex.com/fedextrack/?trknbr=771234567890"}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new shipment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/shipment"},"example":{"object":"shipment","url":"https://api.comecero.com/api/v1/shipments/0093718200417ShQ2xN8kL","shipment_id":"0093718200417ShQ2xN8kL","date_created":"2026-11-04T09:30:00Z","date_modified":"2026-11-04T09:30:00Z","date_shipped":"2026-11-04T09:30:00Z","test":true,"account_id":"AB1234","items":[{"object":"shipment_item","item_id":"1","product_id":"lens-cloth.test","name":"Lens cleaning cloth","quantity":2,"product":"https://api.comecero.com/api/v1/products/lens-cloth.test"}],"order":"https://api.comecero.com/api/v1/orders/2979-KXVST-674","courier":"UPS","tracking_number":"1Z999AA10123456784","tracking_url":"http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784","notifications":"https://api.comecero.com/api/v1/shipments/0093718200417ShQ2xN8kL/notifications","meta":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/orders/{order_id}/void":{"post":{"operationId":"void_order","summary":"Void an order","description":"Cancels the authorization on every pending payment of the order, so the customer is never charged. The order's `payment_status` becomes `cancelled`. Only works while at least one payment is still pending (not captured); to give money back after capture, refund the order. No body is read.\n\nReturns `201` with a `payment_list` holding each payment and its result. When every void fails, the API answers with an error instead and puts the `payment_list` in the error's `meta.payment_list`.\n\nNeeds a secret or trusted token that may create or update payments. A token without that permission gets `401`, not `403`.","tags":["orders"],"parameters":[{"name":"order_id","in":"path","description":"The order id.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"}],"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The void was made for at least one payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/order_payment_list"},"example":{"object":"payment_list","url":"https://api.comecero.com/api/v1/payment_list/0093718312099PlQ8sZr2m","payment_list_id":"0093718312099PlQ8sZr2m","test":true,"account_id":"AB1234","currency":"USD","subtotal":0,"shipping":0,"tax":0,"total":0,"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":"cancelled","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}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The payment provider refused the void.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"No payment on the order is pending.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"The payment provider returned an error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"504":{"description":"The payment provider did not answer in time.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}}}},"/payment_list/{payment_list_id}":{"get":{"summary":"Retrieve a payment list","operationId":"get_payment_list","description":"Returns a group of payments acted on together, such as the captures or voids made when you capture or void an order. Secret and trusted tokens only; a limited token gets `403`. An unknown id returns an empty list, not `404`.","tags":["payments"],"x-limited":false,"parameters":[{"name":"payment_list_id","in":"path","required":true,"description":"The id of the payment list.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The payment list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_list"},"example":{"object":"payment_list","url":"https://api.comecero.com/api/v1/payment_list/0091310055812aB3kQ9","payment_list_id":"0091310055812aB3kQ9","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":[]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/payments":{"get":{"summary":"List all payments","operationId":"list_payments","description":"Lists the payments of your account, failed ones included. A cursor-based list: page with `after_item` and `before_item`. It has no `sort_by`. Secret and trusted tokens only; a limited token gets `403`. Inside the list, `refunds`, `fees`, `commissions` and `failed_gateway_attempts` are always URLs.","tags":["payments"],"x-limited":false,"parameters":[{"name":"status","in":"query","required":false,"description":"Only payments with this status.","schema":{"type":"string","enum":["initiated","processing","pending","completed","failed","cancelled","refunded","retry"]}},{"name":"reference","in":"query","required":false,"description":"Only payments with this `reference`.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Search text. Matches the payment_id, the reference or the customer's email exactly, or part of the customer's name or company name.","schema":{"type":"string"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/after_item"},{"$ref":"#/components/parameters/before_item"},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/date_start"},{"$ref":"#/components/parameters/date_end"},{"$ref":"#/components/parameters/date_type"},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_cursor_list"},"example":{"next_page_url":"https://api.comecero.com/api/v1/payments?after_item=0090460891496PyrYzd9DC","next_page_after_item":"0090460891496PyrYzd9DC","previous_page_url":null,"previous_page_before_item":null,"data":[]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Create a payment","operationId":"create_payment","description":"Charges a customer an amount you set, with no cart or invoice. Send `currency` and one of `total`, `subtotal` or `shipping`; amounts cannot be negative. To pay for a cart or an invoice, use `POST /carts/{cart_id}/payments` or `POST /invoices/{invoice_id}/payments` instead. An account on the reseller model can only use this to add to a customer's balance (`apply_to_balance`). A live payment needs a live account (`422`).\n\nAny token type may call it. A limited token is bound to the payment it makes, and a limited test token only works when its user may make test payments. `capture` is ignored for a limited token.\n\nThe answer is `201` with `status` `completed`, `pending` (authorized only), `processing` or `initiated` (the shopper must act: see `response_data`, then commit it while it is still `initiated`). A declined payment is `402` with the payment in `error.meta.payment`. The same payment sent again soon after a success is `409` (code `duplicate`).","tags":["payments"],"x-limited":true,"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/user_ip_address"},{"$ref":"#/components/parameters/user_agent"}],"requestBody":{"$ref":"#/components/requestBodies/payment_request"},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment"},"example":{"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}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The gateway declined the payment (type `transaction_error`). The failed payment is in `error.meta.payment`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The cart, invoice or payment is not in a state that allows this, or another payment for it is still running (code `payment_in_progress`), or an earlier payment for it may have been taken but is not confirmed yet (code `payment_unconfirmed`). Do not send the payment again: read the payments of the cart or invoice first, so the shopper is never charged twice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"The gateway answered with an error (type `external_server_error`). The payment is in `error.meta.payment`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"504":{"description":"The gateway did not answer in time (type `external_server_timeout`). Read the payment before you try again: it may have gone through.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}}}},"/payments/options":{"get":{"summary":"Retrieve payment options","operationId":"get_payment_options","description":"Returns what a shopper can pay with on your account for a payment with no cart or invoice: your currencies, the best currency for the caller's location, the payment methods and card types in a currency, and the customer fields to collect. For a cart, use `GET /carts/{cart_id}/options` instead. Any token type may call it.","tags":["payments"],"x-limited":true,"parameters":[{"name":"currency","in":"query","required":false,"description":"The ISO 4217 currency to list payment methods for. Must be one your account takes (`400` otherwise). Defaults to your default payment currency.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/user_ip_address"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The payment options.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_options"},"example":{"account_id":"AB1234","test":true,"currencies":[{"code":"USD","name":"US Dollar"},{"code":"EUR","name":"Euro"}],"customer_default_currency":"USD","customer_default_country":"US","payment_methods":[{"payment_method_type":"credit_card","surcharge":0,"currency":"USD","paypal_fraudnet_source_id":null,"stripe_publishable_key":null,"stripe_account_id":null,"finix_card_form":null}],"card_types":["Visa","MasterCard"],"customer_required_fields":["name","email","billing_address.country"],"customer_optional_fields":["phone"],"allowed_customer_countries":["US","CA"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/payments/{payment_id}":{"get":{"summary":"Retrieve a payment","operationId":"get_payment","description":"Returns a payment. Read it to see where an `initiated` or `processing` payment is. Any token type may call it; a limited token only for a payment it is bound to, and without the gateway and settlement fields.","tags":["payments"],"x-limited":true,"parameters":[{"name":"payment_id","in":"path","required":true,"description":"The id of the payment.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/timezone"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment"},"example":{"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}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Update a payment","operationId":"update_payment","description":"Changes the `description`, `reference` or `meta` of a payment. Nothing else can change, and no money moves. Any token type may call it; a limited token only for a payment it is bound to.","tags":["payments"],"x-limited":true,"parameters":[{"name":"payment_id","in":"path","required":true,"description":"The id of the payment.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_update_request"},"examples":{"reference":{"summary":"Set your reference","value":{"reference":"PO-20261107-01"}},"meta":{"summary":"Store your own data","value":{"description":"Order from the phone line","meta":{"crm_id":"C-1042"}}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The changed payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment"},"example":{"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}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/payments/{payment_id}/capture":{"post":{"summary":"Capture a payment","operationId":"capture_payment","description":"Takes the money of a `pending` (authorized) payment. To capture it all, send no body at all: a JSON body without `total` (even `{}`) captures nothing and records a refund of the whole payment. Send a `total` to capture less; the rest is recorded as a refund. The payment becomes `completed` and its order is updated. Only card, PayPal, Amazon Pay, Apple Pay, Comecero Express Payments and wallet payments can be captured. A payment that is not `pending` is `422`. Secret and trusted tokens that may create or update payments only; anything else gets `401`.","tags":["payments"],"x-limited":false,"parameters":[{"name":"payment_id","in":"path","required":true,"description":"The id of the payment.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_capture_request"},"examples":{"part":{"summary":"Capture less","value":{"total":150}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The captured payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment"},"example":{"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}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The gateway declined the payment (type `transaction_error`). The failed payment is in `error.meta.payment`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"The gateway answered with an error (type `external_server_error`). The payment is in `error.meta.payment`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"504":{"description":"The gateway did not answer in time (type `external_server_timeout`). Read the payment before you try again: it may have gone through.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}}}},"/payments/{payment_id}/commissions":{"get":{"summary":"List payment commissions","operationId":"list_payment_commissions","description":"Lists the commissions earned on a payment. An offset-based list. `sort_by` takes `date_created` (the default) or `date_modified`. Secret and trusted tokens that may read commissions only; a limited token gets `403`.","tags":["payments"],"x-limited":false,"parameters":[{"name":"payment_id","in":"path","required":true,"description":"The id of the payment.","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"Only commissions of this type.","schema":{"type":"string","enum":["product_sales"]}},{"name":"accounting_id","in":"query","required":false,"description":"Read and checked, but not used to filter.","schema":{"type":"string"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"name":"sort_by","in":"query","required":false,"description":"The field to sort by.","schema":{"type":"string","enum":["date_created","date_modified"],"default":"date_created"}},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The commissions on the payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_commission_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC/commissions?offset=0&limit=10","data":[{"object":"commission","url":"https://api.comecero.com/api/v1/commissions/1102611073852CMr8Wd1Nh","commission_id":"1102611073852CMr8Wd1Nh","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:10Z","test":true,"total":99.95,"currency":"USD","type":"product_sales","description":null,"transaction_type":"payment","transaction":"https://api.comecero.com/api/v1/payments/1102611073840PAz3Tq9Xc","accounting_id":"C-AB1234P261130USD"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/payments/{payment_id}/commit":{"post":{"summary":"Commit a payment","operationId":"commit_payment","description":"Finishes an `initiated` payment once the shopper has done their step: approved at PayPal or Amazon Pay, passed a 3-D Secure check, or confirmed in Stripe.js. The amounts are worked out again from the cart or invoice first, so a changed shipping or tax is charged. On success the cart or invoice closes, the order is made, events fire and the receipt goes out.\n\nIf a PayPal total went up too much since approval, the payment stays `initiated` with a new `response_data.redirect_url` for the buyer to approve again. Two commits at once (the shopper's browser and the provider's webhook) run one after the other, and the second gets the first one's result. A payment that is already `pending` comes back as it is. A `completed` or `cancelled` payment is `422`. The Comecero-hosted 3-D Secure page commits the payment itself, so get the payment first and commit only while it is `initiated`.\n\nAny token type may call it, a limited token too, for any payment of the account: a shopper may come back in another browser. A limited token that is not bound to the payment gets only `object`, `payment_id`, `success`, `status`, `payment_method.type` and `response_data.redirect_url`. A token that may not create or update payments gets `401`. The body is optional.","tags":["payments"],"x-limited":true,"parameters":[{"name":"payment_id","in":"path","required":true,"description":"The id of the payment.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_commit_request"},"examples":{"commit":{"summary":"Finish the payment","value":{}},"authorize_only":{"summary":"Finish it without capturing","value":{"capture":false}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The committed payment, usually `completed` or `pending`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment"},"example":{"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}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The gateway declined the payment (type `transaction_error`). The failed payment is in `error.meta.payment`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"The gateway answered with an error (type `external_server_error`). The payment is in `error.meta.payment`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"504":{"description":"The gateway did not answer in time (type `external_server_timeout`). Read the payment before you try again: it may have gone through.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}}}},"/payments/{payment_id}/fee_summary":{"get":{"summary":"Retrieve a payment fee summary","operationId":"get_payment_fee_summary","description":"Returns the fees on a payment added up, fixed and percentage apart, per currency. Secret and trusted tokens that may read fees only; any other token gets `401`.","tags":["payments"],"x-limited":false,"parameters":[{"name":"payment_id","in":"path","required":true,"description":"The id of the payment.","schema":{"type":"string"}},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The fee summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_fee_summary"},"example":{"object":"fee_summary","url":"https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC/fee_summary","fixed_amount":0.3,"percentage_amount":6.23,"total":6.53,"currency":"USD","totals":[{"currency":"USD","fixed_amount":0.3,"percentage_amount":6.23,"total":6.53}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/payments/{payment_id}/fees":{"get":{"summary":"List payment fees","operationId":"list_payment_fees","description":"Lists the fees charged on a payment. An offset-based list. `sort_by` takes `date_created` (the default) or `date_modified`. Secret and trusted tokens that may read fees only; a limited token gets `403`.","tags":["payments"],"x-limited":false,"parameters":[{"name":"payment_id","in":"path","required":true,"description":"The id of the payment.","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"Only fees of this type.","schema":{"type":"string","enum":["payment_completed","refund_completed","auth","zero_auth","capture","void","decline","chargeback","fx_conversion","international_card","payout"]}},{"name":"accounting_id","in":"query","required":false,"description":"Read and checked, but not used to filter.","schema":{"type":"string"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"name":"sort_by","in":"query","required":false,"description":"The field to sort by.","schema":{"type":"string","enum":["date_created","date_modified"],"default":"date_created"}},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The fees on the payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_fee_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC/fees?offset=0&limit=10","data":[{"object":"fee","url":"https://api.comecero.com/api/v1/fees/1102611073850FEp6Vb2Qs","fee_id":"1102611073850FEp6Vb2Qs","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:10Z","test":true,"account_id":"AB1234","fixed_amount":0.3,"percentage":2.9,"percentage_amount":2.9,"total":3.2,"currency":"USD","type":"payment_completed","category":"transaction","collected":false,"description":"Payment completed","transaction_type":"payment","transaction":"https://api.comecero.com/api/v1/payments/1102611073840PAz3Tq9Xc","contract":null,"accounting_id":"C-AB1234R261130USD"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/payments/{payment_id}/notifications":{"get":{"summary":"List payment notifications","operationId":"list_payment_notifications","description":"Lists the emails and other notifications sent for a payment, such as the receipt. An offset-based list. `sort_by` takes `date_created` (the default) or `date_modified`. Any token type may call it; a limited token only for a payment it is bound to.","tags":["payments"],"x-limited":true,"parameters":[{"name":"payment_id","in":"path","required":true,"description":"The id of the payment.","schema":{"type":"string"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"name":"sort_by","in":"query","required":false,"description":"The field to sort by.","schema":{"type":"string","enum":["date_created","date_modified"],"default":"date_created"}},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The notifications for the payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_notification_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC/notifications?offset=0&limit=10","data":[{"object":"notification","url":"https://api.comecero.com/api/v1/notifications/1102611073905NOq2Lx7Pv","notification_id":"1102611073905NOq2Lx7Pv","test":true,"account_id":"AB1234","type":"order:confirmation","method":"email","from":"notification@comecero.com","from_name":"Example Shop","reply_to":"support@example.com","bcc":null,"destination":"john@example.com","subject":"Your Order Confirmation","notification_subscription":"https://api.comecero.com/api/v1/notification_subscriptions/1102500112233NSd4Kw9Tz","customer":"https://api.comecero.com/api/v1/customers/1102611073801CUa8Hn2Lq","status":"delivered","date_created":"2026-11-07T14:32:12Z","date_modified":"2026-11-07T14:32:14Z","data":{"order":{"order_id":"7393-GMRFY-954","total":99.95,"currency":"USD"}},"body":"<html><body><h1>Thanks for your order</h1></body></html>"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/payments/{payment_id}/payment_method":{"get":{"summary":"Retrieve a payment's payment method","operationId":"get_payment_payment_method","description":"Returns the payment method used for the payment, with card details masked. Any token type may call it; a limited token only for a payment it is bound to.","tags":["payments"],"x-limited":true,"parameters":[{"name":"payment_id","in":"path","required":true,"description":"The id of the payment.","schema":{"type":"string"}},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The payment method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_method"},"example":{"url":"https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/payment_methods/0092503470929PmEP0ivO4","object":"payment_method","payment_method_id":"0092503470929PmEP0ivO4","date_created":"2026-11-02T18:20:31Z","date_modified":"2026-11-02T18:20:31Z","test":true,"type":"credit_card","data":{"object":"credit_card","mask":"4***********1111","fingerprint":"2321657x8123834dc21ea08f","exp_month":12,"exp_year":28,"cardholder_name":"John Doe","ending":"1111","type":"Visa","label":"Visa 1111","billing_address":{"object":"address","name":"John Doe","address_1":"123 Main St.","address_2":null,"city":"New York","state_prov":"NY","postal_code":"10019","country":"US","email":null,"meta":null}},"is_default":true,"date_last_used":"2026-11-02T18:20:31Z"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/payments/{payment_id}/refunds":{"get":{"summary":"List payment refunds","operationId":"list_payment_refunds","description":"Lists the refunds and chargebacks of a payment. An offset-based list. `sort_by` takes `date_created` (the default), `date_modified` or `date_completed`. Any token type may call it; a limited token only for a payment it is bound to.","tags":["payments"],"x-limited":true,"parameters":[{"name":"payment_id","in":"path","required":true,"description":"The id of the payment.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Only refunds with this status, for example `completed`, `pending` or `failed`.","schema":{"type":"string"}},{"name":"is_chargeback","in":"query","required":false,"description":"`true` for chargebacks only, `false` for refunds only.","schema":{"type":"boolean"}},{"name":"reference","in":"query","required":false,"description":"Only refunds with this `reference`.","schema":{"type":"string"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"name":"sort_by","in":"query","required":false,"description":"The field to sort by.","schema":{"type":"string","enum":["date_created","date_modified","date_completed"],"default":"date_created"}},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The refunds of the payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_refund_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC/refunds?offset=0&limit=10","data":[{"object":"refund","url":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5","refund_id":"0090374314462Rec3PffZ5","account_id":"AB1234","success":true,"status":"completed","reference":null,"date_created":"2026-11-03T10:12:40Z","date_modified":"2026-11-03T10:12:41Z","date_completed":"2026-11-03T10:12:41Z","test":true,"currency":"USD","subtotal":49.95,"shipping":0,"tax":0,"total":49.95,"reason":"Customer request","apply_to_balance":false,"is_chargeback":false,"record_only":false,"record_only_memo":null,"response_code":"OK","response_message":"OK","gateway_transaction_id":"re_test_3PffZ5","gateway_error_code":null,"gateway_error_message":null,"gateway":"https://api.comecero.com/api/v1/gateways/0089584408915Gtf5AsdJ8","comments":null,"payment_method":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/payment_method","settlement_currency":"USD","settlement_subtotal":49.95,"settlement_shipping":0,"settlement_tax":0,"settlement_total":49.95,"fx_rate":1,"reporting_currency":"USD","reporting_subtotal":49.95,"reporting_shipping":0,"reporting_tax":0,"reporting_total":49.95,"reporting_fx_rate":1,"items":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/items","customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","order":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954","payment":"https://api.comecero.com/api/v1/payments/0093717991362PyRYN1qc6","invoice":null,"fees":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fees","fee_summary":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fee_summary","commissions":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/commissions","meta":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Refund a payment","operationId":"create_payment_refund","description":"Gives money back on a captured payment, in full or in part. Money moves back to the shopper's payment method and refund events fire. Secret and trusted tokens that may create refunds only; a limited token gets `403`.","tags":["payments"],"x-limited":false,"parameters":[{"name":"payment_id","in":"path","required":true,"description":"The id of the payment.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/refund_request"},"examples":{"full":{"summary":"Full refund (empty body)","value":{}},"amount":{"summary":"Refund an amount","value":{"total":10,"reason":"Partial refund for a late delivery"}},"items":{"summary":"Refund one item (payment on an order or invoice)","value":{"items":[{"item_id":"1","quantity":1}],"reason":"Customer request"}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The refund.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/refund"},"example":{"object":"refund","url":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5","refund_id":"0090374314462Rec3PffZ5","account_id":"AB1234","success":true,"status":"completed","reference":null,"date_created":"2026-11-03T10:12:40Z","date_modified":"2026-11-03T10:12:41Z","date_completed":"2026-11-03T10:12:41Z","test":true,"currency":"USD","subtotal":49.95,"shipping":0,"tax":0,"total":49.95,"reason":"Customer request","apply_to_balance":false,"is_chargeback":false,"record_only":false,"record_only_memo":null,"response_code":"OK","response_message":"OK","gateway_transaction_id":"re_test_3PffZ5","gateway_error_code":null,"gateway_error_message":null,"gateway":"https://api.comecero.com/api/v1/gateways/0089584408915Gtf5AsdJ8","comments":null,"payment_method":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/payment_method","settlement_currency":"USD","settlement_subtotal":49.95,"settlement_shipping":0,"settlement_tax":0,"settlement_total":49.95,"fx_rate":1,"reporting_currency":"USD","reporting_subtotal":49.95,"reporting_shipping":0,"reporting_tax":0,"reporting_total":49.95,"reporting_fx_rate":1,"items":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/items","customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","order":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954","payment":"https://api.comecero.com/api/v1/payments/0093717991362PyRYN1qc6","invoice":null,"fees":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fees","fee_summary":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fee_summary","commissions":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/commissions","meta":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The gateway declined the refund.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/payments/{payment_id}/response_data":{"get":{"summary":"Retrieve payment response data","operationId":"get_payment_response_data","description":"Returns what the gateway sent back for the payment, by payment method type. For an `initiated` payment it holds the shopper's next step: a `redirect_url` (PayPal approval, or a 3-D Secure page), a `next_action` for a Comecero Express Payments 3-D Secure check on your own page, or the Stripe.js values for a `stripe` payment. For a card it holds the address and security code results (not for a limited token). Any token type may call it; a limited token only for a payment it is bound to.","tags":["payments"],"x-limited":true,"parameters":[{"name":"payment_id","in":"path","required":true,"description":"The id of the payment.","schema":{"type":"string"}},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The response data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/response_data"},"examples":{"card":{"summary":"A card payment","value":{"object":"payment.response_data.credit_card","url":"https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC/response_data","avs_match":true,"avs_code":"M","avs_message":null,"cvv_match":true,"cvv_code":"M","cvv_message":null}},"card_3ds_waiting":{"summary":"A card payment waiting for a 3-D Secure check","value":{"object":"payment.response_data.credit_card","url":"https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC/response_data","avs_match":false,"avs_code":null,"avs_message":null,"cvv_match":false,"cvv_code":null,"cvv_message":null,"redirect_url":"https://3ds.comecero.com/0090460891496PyrYzd9DC?token=example"}},"paypal_waiting":{"summary":"A PayPal payment waiting for the buyer","value":{"object":"payment.response_data.paypal","url":"https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC/response_data","redirect_url":"https://www.sandbox.paypal.com/checkoutnow?token=EC-0TEST000000000000","billing_agreement_accept_status":false}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/payments/{payment_id}/void":{"post":{"summary":"Void a payment","operationId":"void_payment","description":"Cancels a `pending` payment (authorized but not captured), so the hold on the shopper's money is released. Any other status is `422`. The payment becomes `cancelled` and the `payment:voided` event fires. Any body is ignored. To give back money that was captured, refund the payment instead. Secret and trusted tokens only; a limited token gets `403`.","tags":["payments"],"x-limited":false,"parameters":[{"name":"payment_id","in":"path","required":true,"description":"The id of the payment.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/formatted"}],"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The voided payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment"},"example":{"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}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The gateway declined the payment (type `transaction_error`). The failed payment is in `error.meta.payment`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"The gateway answered with an error (type `external_server_error`). The payment is in `error.meta.payment`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"504":{"description":"The gateway did not answer in time (type `external_server_timeout`). Read the payment before you try again: it may have gone through.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}}}},"/products":{"get":{"summary":"List products","operationId":"list_products","description":"Returns your products, sorted by name unless you choose another `sort_by`. Deleted products are left out unless you send `deleted=true`. Prices come back in one currency: the cart's or invoice's currency when you send `cart_id` or `invoice_id`, else the `currency` you send, else a currency guessed from `country` or the shopper's IP address, else the account's default. Secret, trusted and limited tokens may call it. This is the one list a limited token may read, so a shop can show its catalog before anyone signs in. For a limited token the list always holds only active, visible, not deleted products, whatever filters you send.","tags":["products"],"x-limited":true,"parameters":[{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/limit"},{"name":"sort_by","in":"query","description":"The field to sort by. The default is `name`.","schema":{"type":"string","enum":["name","date_created","date_modified","active","deleted","hidden"]}},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"name":"q","in":"query","description":"Search text. An exact product id returns that product; otherwise products whose name contains the text (any case) are returned.","schema":{"type":"string"}},{"name":"active","in":"query","description":"Only products with this `active` value. Always `true` for a limited token.","schema":{"type":"boolean"}},{"name":"hidden","in":"query","description":"Only products with this `hidden` value. Always `false` for a limited token.","schema":{"type":"boolean"}},{"name":"deleted","in":"query","description":"Send `true` to include deleted products as well. Any other value, or none, leaves them out. Always `false` for a limited token.","schema":{"type":"boolean"}},{"name":"currency","in":"query","description":"The ISO 4217 currency to price the products in. It must be a currency the account can take payment in, or the request fails with `400`.","schema":{"type":"string"}},{"name":"country","in":"query","description":"A two-letter ISO country code. Prices come back in that country's currency when the account supports it, else in the account's default currency.","schema":{"type":"string"}},{"name":"cart_id","in":"query","description":"Price the products in this cart's currency and exchange rate, so the list matches what the shopper will pay. Ignored if the token may not read the cart.","schema":{"type":"string"}},{"name":"invoice_id","in":"query","description":"Price the products in this invoice's currency and exchange rate. Ignored if the token may not read the invoice.","schema":{"type":"string"}},{"name":"user_locale","in":"query","description":"The shopper's language, such as `de` or `ja-JP`, used to pick a translation. When left out, the `Accept-Language` header is used for limited and trusted tokens.","schema":{"type":"string"}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of products.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/product_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/products?offset=0","data":[{"object":"product","url":"https://api.comecero.com/api/v1/products/widget.test","product_id":"widget.test","date_created":"2026-11-02T14:36:52Z","date_modified":"2026-11-02T14:36:52Z","test":true,"account_id":"AB1234","name":"Widget","price":49.95,"currency":"USD","compare_at_price":null,"type":"physical","description":"A simple widget for everyday use.","headline":null,"tax_code":null,"prices":[{"price":49.95,"currency":"USD"}],"compare_at_prices":[],"volume_prices":[],"effective_volume_prices":[],"inventory":null,"bundle_items":[],"weight":{"amount":3,"unit":"lb"},"active":true,"deleted":false,"hidden":false,"date_deleted":null,"file":null,"has_file":false,"license_service":null,"has_license_service":false,"subscription_plan":null,"subscription_terms":null,"images":[],"video_url":null,"related_products":"https://api.comecero.com/api/v1/products/widget.test/related_products","subscription_change_products":"https://api.comecero.com/api/v1/products/widget.test/subscription_change_products","subscription_term_change_products":"https://api.comecero.com/api/v1/products/widget.test/subscription_term_change_products","meta":null,"translations":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Create a product","operationId":"create_product","description":"Creates a product. Send `active: true` to put it on sale; a new product is inactive by default. A product id you choose must not be in use. Fires the `product.created` event. Secret and trusted tokens may call it.","tags":["products"],"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"$ref":"#/components/requestBodies/product_request"},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new product.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/product"},"example":{"object":"product","url":"https://api.comecero.com/api/v1/products/widget.test","product_id":"widget.test","date_created":"2026-11-02T14:36:52Z","date_modified":"2026-11-02T14:36:52Z","test":true,"account_id":"AB1234","name":"Widget","price":49.95,"currency":"USD","compare_at_price":59.95,"type":"physical","description":"A simple widget for everyday use.","headline":"The widget you will use every day","tax_code":null,"prices":[{"price":49.95,"currency":"USD"},{"price":45.95,"currency":"EUR"}],"compare_at_prices":[{"price":59.95,"currency":"USD"}],"volume_prices":[{"low":10,"high":null,"prices":[{"price":39.95,"currency":"USD"}]}],"effective_volume_prices":[{"low":1,"high":9,"price":49.95,"currency":"USD","discount_percent":0,"discount_amount":0},{"low":10,"high":null,"price":39.95,"currency":"USD","discount_percent":0.2,"discount_amount":10}],"inventory":{"in_stock":true,"quantity":120,"allow_oversells":false,"low_quantity_notification":10},"bundle_items":[],"weight":{"amount":3,"unit":"lb"},"active":true,"deleted":false,"hidden":false,"date_deleted":null,"file":null,"has_file":false,"license_service":null,"has_license_service":false,"subscription_plan":null,"subscription_terms":null,"images":[{"object":"image","url":"https://api.comecero.com/api/v1/images/0099844605810ImLAMbo73","image_id":"0099844605810ImLAMbo73","date_created":"2026-11-02T14:36:45Z","date_modified":"2026-11-02T14:36:45Z","test":true,"account_id":"AB1234","link":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/widget.png","link_small":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sm_widget.png","link_medium":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/md_widget.png","link_large":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/lg_widget.png","link_square":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sq_widget.png","filename":"widget.png"}],"video_url":null,"related_products":"https://api.comecero.com/api/v1/products/widget.test/related_products","subscription_change_products":"https://api.comecero.com/api/v1/products/widget.test/subscription_change_products","subscription_term_change_products":"https://api.comecero.com/api/v1/products/widget.test/subscription_term_change_products","meta":null,"translations":{"de":{"name":"Widget","headline":"Das Widget fur jeden Tag","description":"Ein einfaches Widget fur jeden Tag."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/products/{product_id}":{"get":{"summary":"Get a product","operationId":"get_product","description":"Returns one product, priced in one currency (see `currency`). A limited token may read any product of the account by its id, including a hidden one, but does not get the fields marked as not returned to limited tokens. Secret, trusted and limited tokens may call it.","tags":["products"],"x-limited":true,"parameters":[{"name":"product_id","in":"path","required":true,"description":"The product id. Test product ids end in `.test`.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"name":"currency","in":"query","description":"The ISO 4217 currency to price the products in. It must be a currency the account can take payment in, or the request fails with `400`.","schema":{"type":"string"}},{"name":"country","in":"query","description":"A two-letter ISO country code. Used to guess the shopper's currency when you send no `currency`, `cart_id` or `invoice_id`.","schema":{"type":"string"}},{"name":"cart_id","in":"query","description":"Price in this cart's currency and exchange rate. Ignored if the token may not read the cart.","schema":{"type":"string"}},{"name":"invoice_id","in":"query","description":"Price in this invoice's currency and exchange rate. Ignored if the token may not read the invoice.","schema":{"type":"string"}},{"name":"user_locale","in":"query","description":"The shopper's language, such as `de` or `ja-JP`, used to pick a translation.","schema":{"type":"string"}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The product.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/product"},"example":{"object":"product","url":"https://api.comecero.com/api/v1/products/widget.test","product_id":"widget.test","date_created":"2026-11-02T14:36:52Z","date_modified":"2026-11-02T14:36:52Z","test":true,"account_id":"AB1234","name":"Widget","price":49.95,"currency":"USD","compare_at_price":59.95,"type":"physical","description":"A simple widget for everyday use.","headline":"The widget you will use every day","tax_code":null,"prices":[{"price":49.95,"currency":"USD"},{"price":45.95,"currency":"EUR"}],"compare_at_prices":[{"price":59.95,"currency":"USD"}],"volume_prices":[{"low":10,"high":null,"prices":[{"price":39.95,"currency":"USD"}]}],"effective_volume_prices":[{"low":1,"high":9,"price":49.95,"currency":"USD","discount_percent":0,"discount_amount":0},{"low":10,"high":null,"price":39.95,"currency":"USD","discount_percent":0.2,"discount_amount":10}],"inventory":{"in_stock":true,"quantity":120,"allow_oversells":false,"low_quantity_notification":10},"bundle_items":[],"weight":{"amount":3,"unit":"lb"},"active":true,"deleted":false,"hidden":false,"date_deleted":null,"file":null,"has_file":false,"license_service":null,"has_license_service":false,"subscription_plan":null,"subscription_terms":null,"images":[{"object":"image","url":"https://api.comecero.com/api/v1/images/0099844605810ImLAMbo73","image_id":"0099844605810ImLAMbo73","date_created":"2026-11-02T14:36:45Z","date_modified":"2026-11-02T14:36:45Z","test":true,"account_id":"AB1234","link":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/widget.png","link_small":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sm_widget.png","link_medium":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/md_widget.png","link_large":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/lg_widget.png","link_square":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sq_widget.png","filename":"widget.png"}],"video_url":null,"related_products":"https://api.comecero.com/api/v1/products/widget.test/related_products","subscription_change_products":"https://api.comecero.com/api/v1/products/widget.test/subscription_change_products","subscription_term_change_products":"https://api.comecero.com/api/v1/products/widget.test/subscription_term_change_products","meta":null,"translations":{"de":{"name":"Widget","headline":"Das Widget fur jeden Tag","description":"Ein einfaches Widget fur jeden Tag."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Update a product","operationId":"update_product","description":"Changes a product. Send only the fields you want to change. Lists such as `prices`, `image_ids` and `related_product_ids` are replaced whole, not merged. The bundle rules are checked only when the request holds `type: bundle`, so send `type` with `bundle_items`. Fires the `product.modified` event. Secret and trusted tokens may call it.","tags":["products"],"parameters":[{"name":"product_id","in":"path","required":true,"description":"The product id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"description":"The fields to change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/product_request"},"example":{"prices":[{"price":44.95,"currency":"USD"}],"hidden":true}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The updated product.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/product"},"example":{"object":"product","url":"https://api.comecero.com/api/v1/products/widget.test","product_id":"widget.test","date_created":"2026-11-02T14:36:52Z","date_modified":"2026-11-02T14:36:52Z","test":true,"account_id":"AB1234","name":"Widget","price":49.95,"currency":"USD","compare_at_price":59.95,"type":"physical","description":"A simple widget for everyday use.","headline":"The widget you will use every day","tax_code":null,"prices":[{"price":49.95,"currency":"USD"},{"price":45.95,"currency":"EUR"}],"compare_at_prices":[{"price":59.95,"currency":"USD"}],"volume_prices":[{"low":10,"high":null,"prices":[{"price":39.95,"currency":"USD"}]}],"effective_volume_prices":[{"low":1,"high":9,"price":49.95,"currency":"USD","discount_percent":0,"discount_amount":0},{"low":10,"high":null,"price":39.95,"currency":"USD","discount_percent":0.2,"discount_amount":10}],"inventory":{"in_stock":true,"quantity":120,"allow_oversells":false,"low_quantity_notification":10},"bundle_items":[],"weight":{"amount":3,"unit":"lb"},"active":true,"deleted":false,"hidden":false,"date_deleted":null,"file":null,"has_file":false,"license_service":null,"has_license_service":false,"subscription_plan":null,"subscription_terms":null,"images":[{"object":"image","url":"https://api.comecero.com/api/v1/images/0099844605810ImLAMbo73","image_id":"0099844605810ImLAMbo73","date_created":"2026-11-02T14:36:45Z","date_modified":"2026-11-02T14:36:45Z","test":true,"account_id":"AB1234","link":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/widget.png","link_small":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sm_widget.png","link_medium":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/md_widget.png","link_large":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/lg_widget.png","link_square":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sq_widget.png","filename":"widget.png"}],"video_url":null,"related_products":"https://api.comecero.com/api/v1/products/widget.test/related_products","subscription_change_products":"https://api.comecero.com/api/v1/products/widget.test/subscription_change_products","subscription_term_change_products":"https://api.comecero.com/api/v1/products/widget.test/subscription_term_change_products","meta":null,"translations":{"de":{"name":"Widget","headline":"Das Widget fur jeden Tag","description":"Ein einfaches Widget fur jeden Tag."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"summary":"Delete a product","operationId":"delete_product","description":"Marks a product deleted and inactive. It is not erased: orders keep pointing at it, you can still read it, and you can bring it back by updating it with `deleted: false` or `active: true`. Fires the `product.deleted` event. Secret and trusted tokens may call it.","tags":["products"],"parameters":[{"name":"product_id","in":"path","required":true,"description":"The product id.","schema":{"type":"string"}}],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The product is deleted. No body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/products/{product_id}/related_products":{"get":{"summary":"List related products","operationId":"list_related_products","description":"The products you set in the product's `related_product_ids`, for \"you may also like\" offers. Inactive and deleted products are left out. All of them come back on one page; `offset` and `limit` do not apply. Prices follow the same currency rules as `GET /products`. Secret, trusted and limited tokens may call it.","tags":["products"],"x-limited":true,"parameters":[{"name":"product_id","in":"path","required":true,"description":"The product id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"name":"currency","in":"query","description":"The ISO 4217 currency to price the products in. It must be a currency the account can take payment in, or the request fails with `400`.","schema":{"type":"string"}},{"name":"country","in":"query","description":"A two-letter ISO country code. Used to guess the shopper's currency when you send no `currency`, `cart_id` or `invoice_id`.","schema":{"type":"string"}},{"name":"cart_id","in":"query","description":"Price in this cart's currency and exchange rate. Ignored if the token may not read the cart.","schema":{"type":"string"}},{"name":"invoice_id","in":"query","description":"Price in this invoice's currency and exchange rate. Ignored if the token may not read the invoice.","schema":{"type":"string"}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The products, all on one page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/product_list"},"example":{"total_items":1,"total_pages":0,"current_page":0,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/products/widget.test/related_products","data":[{"object":"product","url":"https://api.comecero.com/api/v1/products/widget-pro.test","product_id":"widget-pro.test","date_created":"2026-11-02T14:40:10Z","date_modified":"2026-11-02T14:40:10Z","test":true,"account_id":"AB1234","name":"Widget Pro","price":79.95,"currency":"USD","compare_at_price":null,"type":"physical","description":"The widget for people who use it all day.","headline":null,"tax_code":null,"prices":[{"price":79.95,"currency":"USD"}],"volume_prices":[],"effective_volume_prices":[],"inventory":null,"bundle_items":[],"has_file":false,"has_license_service":false,"subscription_plan":null,"subscription_terms":null,"images":[],"video_url":null,"related_products":"https://api.comecero.com/api/v1/products/widget-pro.test/related_products","subscription_change_products":"https://api.comecero.com/api/v1/products/widget-pro.test/subscription_change_products","subscription_term_change_products":"https://api.comecero.com/api/v1/products/widget-pro.test/subscription_term_change_products","meta":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/products/{product_id}/subscription_change_products":{"get":{"summary":"List plan change products","operationId":"list_subscription_change_products","description":"The products a subscriber to this product may switch to on the same subscription plan: the active, not deleted products in the product's `subscription_change_product_ids` that still have the same plan. All of them come back on one page; `offset` and `limit` do not apply. The upgrade and downgrade settings are not applied here; they apply when a customer changes a subscription. Secret, trusted and limited tokens may call it.","tags":["products"],"x-limited":true,"parameters":[{"name":"product_id","in":"path","required":true,"description":"The product id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"name":"currency","in":"query","description":"The ISO 4217 currency to price the products in. It must be a currency the account can take payment in, or the request fails with `400`.","schema":{"type":"string"}},{"name":"country","in":"query","description":"A two-letter ISO country code. Used to guess the shopper's currency when you send no `currency`, `cart_id` or `invoice_id`.","schema":{"type":"string"}},{"name":"cart_id","in":"query","description":"Price in this cart's currency and exchange rate. Ignored if the token may not read the cart.","schema":{"type":"string"}},{"name":"invoice_id","in":"query","description":"Price in this invoice's currency and exchange rate. Ignored if the token may not read the invoice.","schema":{"type":"string"}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The products, all on one page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/product_list"},"example":{"total_items":1,"total_pages":0,"current_page":0,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/products/widget.test/subscription_change_products","data":[{"object":"product","url":"https://api.comecero.com/api/v1/products/widget-pro.test","product_id":"widget-pro.test","date_created":"2026-11-02T14:40:10Z","date_modified":"2026-11-02T14:40:10Z","test":true,"account_id":"AB1234","name":"Widget Pro","price":79.95,"currency":"USD","compare_at_price":null,"type":"physical","description":"The widget for people who use it all day.","headline":null,"tax_code":null,"prices":[{"price":79.95,"currency":"USD"}],"volume_prices":[],"effective_volume_prices":[],"inventory":null,"bundle_items":[],"has_file":false,"has_license_service":false,"subscription_plan":null,"subscription_terms":null,"images":[],"video_url":null,"related_products":"https://api.comecero.com/api/v1/products/widget-pro.test/related_products","subscription_change_products":"https://api.comecero.com/api/v1/products/widget-pro.test/subscription_change_products","subscription_term_change_products":"https://api.comecero.com/api/v1/products/widget-pro.test/subscription_term_change_products","meta":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/products/{product_id}/subscription_term_change_products":{"get":{"summary":"List term change products","operationId":"list_subscription_term_change_products","description":"The products a subscriber to this product may switch to on a different subscription plan, for example yearly instead of monthly: the active, not deleted products in the product's `subscription_term_change_product_ids` that have a plan other than this product's. All of them come back on one page; `offset` and `limit` do not apply. Secret, trusted and limited tokens may call it.","tags":["products"],"x-limited":true,"parameters":[{"name":"product_id","in":"path","required":true,"description":"The product id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"name":"currency","in":"query","description":"The ISO 4217 currency to price the products in. It must be a currency the account can take payment in, or the request fails with `400`.","schema":{"type":"string"}},{"name":"country","in":"query","description":"A two-letter ISO country code. Used to guess the shopper's currency when you send no `currency`, `cart_id` or `invoice_id`.","schema":{"type":"string"}},{"name":"cart_id","in":"query","description":"Price in this cart's currency and exchange rate. Ignored if the token may not read the cart.","schema":{"type":"string"}},{"name":"invoice_id","in":"query","description":"Price in this invoice's currency and exchange rate. Ignored if the token may not read the invoice.","schema":{"type":"string"}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The products, all on one page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/product_list"},"example":{"total_items":1,"total_pages":0,"current_page":0,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/products/widget.test/subscription_term_change_products","data":[{"object":"product","url":"https://api.comecero.com/api/v1/products/widget-pro.test","product_id":"widget-pro.test","date_created":"2026-11-02T14:40:10Z","date_modified":"2026-11-02T14:40:10Z","test":true,"account_id":"AB1234","name":"Widget Pro","price":79.95,"currency":"USD","compare_at_price":null,"type":"physical","description":"The widget for people who use it all day.","headline":null,"tax_code":null,"prices":[{"price":79.95,"currency":"USD"}],"volume_prices":[],"effective_volume_prices":[],"inventory":null,"bundle_items":[],"has_file":false,"has_license_service":false,"subscription_plan":null,"subscription_terms":null,"images":[],"video_url":null,"related_products":"https://api.comecero.com/api/v1/products/widget-pro.test/related_products","subscription_change_products":"https://api.comecero.com/api/v1/products/widget-pro.test/subscription_change_products","subscription_term_change_products":"https://api.comecero.com/api/v1/products/widget-pro.test/subscription_term_change_products","meta":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/products/{product_id}/subscription_terms":{"get":{"summary":"Get subscription terms","operationId":"get_product_subscription_terms","description":"Shows what a subscription to this product would cost and when it would bill, if one unit were bought now: price, trial, billing interval and a sentence for the shopper. Use it on a product page before checkout. Nothing is created. Call it only for a product with a subscription plan. The currency is the `currency` you send, or one guessed from `country` or the shopper's IP address. Secret, trusted and limited tokens may call it.","tags":["products"],"x-limited":true,"parameters":[{"name":"product_id","in":"path","required":true,"description":"The product id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"name":"currency","in":"query","description":"The ISO 4217 currency for the terms. It must be a currency the account can take payment in, or the request fails with `400`.","schema":{"type":"string"}},{"name":"country","in":"query","description":"A two-letter ISO country code, used to guess the currency when you send no `currency`.","schema":{"type":"string"}},{"name":"user_locale","in":"query","description":"The shopper's language for `description`, such as `de`.","schema":{"type":"string"}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The subscription terms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/product_subscription_terms"},"example":{"object":"subscription_terms","price":9.95,"quantity":1,"currency":"USD","discount":0,"discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"tax_inclusve":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"month","trial_interval":14,"trial_interval_unit":"day","trial_interval_description":"14 days","date_trial_start":"2026-11-07T15:00:00Z","date_trial_end":"2026-11-21T15:00:00Z","end_at_billing_count":null,"date_billing_start":"2026-11-21T15:00:00Z","subscription_id":null,"description":"Widget Pro is a subscription that renews every month with a payment of $9.95.","price_per_day":0.33,"price_per_month":9.95,"price_per_year":119.4}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/promotions":{"get":{"summary":"List promotions","operationId":"list_promotions","description":"Returns your coupons, cross-sells and up-sells, oldest first unless you choose another `sort_by`. Secret and trusted tokens may call it.","tags":["promotions"],"parameters":[{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/limit"},{"name":"sort_by","in":"query","description":"The field to sort by. The default is `date_created`.","schema":{"type":"string","enum":["date_created","date_modified","promotion_id","name"]}},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"name":"q","in":"query","description":"Search text. Returns the promotion with this exact id and the first promotion whose name contains the text.","schema":{"type":"string"}},{"name":"active","in":"query","description":"Only promotions with this `active` value.","schema":{"type":"boolean"}},{"name":"type","in":"query","description":"Only promotions of this type.","schema":{"type":"string","enum":["coupon","cross_sell","up_sell"]}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of promotions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/promotion_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/promotions?offset=0","data":[{"object":"promotion","url":"https://api.comecero.com/api/v1/promotions/0070576784690PtKDqfI","promotion_id":"0070576784690PtKDqfI","name":"Ten percent off","test":true,"account_id":"AB1234","date_created":"2026-11-02T20:13:16Z","date_modified":"2026-11-02T20:13:16Z","type":"coupon","active":true,"apply_to_recurring":false,"apply_to_recurring_count":null,"use_count":4,"expires":null,"comments":null,"config":{"type":"order","code":"SAVE10","generator_prefix":null,"generator_secret_key":null,"discount_percent":0.1,"discount_amount":null,"product_ids":null,"exclude_product_ids":false,"max_uses_per_customer":1,"max_uses_global":null}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Create a promotion","operationId":"create_promotion","description":"Creates a coupon, cross-sell or up-sell. A new promotion is inactive unless you send `active: true`. For a coupon with a `generator_prefix`, a `generator_secret_key` is made when you do not send one. Secret and trusted tokens may call it.","tags":["promotions"],"parameters":[{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"description":"The new promotion.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/promotion_request"},{"required":["type","config"]}]},"examples":{"percent":{"summary":"A ten percent coupon","value":{"type":"coupon","name":"Ten percent off","active":true,"expires":"2026-12-31T23:59:59Z","config":{"type":"order","code":"SAVE10","discount_percent":0.1,"max_uses_per_customer":1}}},"amount":{"summary":"Five dollars off an order","value":{"type":"coupon","name":"Five dollars off","active":true,"config":{"type":"order","code":"FIVEOFF","discount_amount":[{"price":5,"currency":"USD"}]}}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new promotion.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/promotion"},"example":{"object":"promotion","url":"https://api.comecero.com/api/v1/promotions/0070576784690PtKDqfI","promotion_id":"0070576784690PtKDqfI","name":"Ten percent off","test":true,"account_id":"AB1234","date_created":"2026-11-02T20:13:16Z","date_modified":"2026-11-02T20:13:16Z","type":"coupon","active":true,"apply_to_recurring":false,"apply_to_recurring_count":null,"use_count":4,"expires":"2026-12-31T23:59:59Z","comments":null,"config":{"type":"order","code":"SAVE10","generator_prefix":null,"generator_secret_key":null,"discount_percent":0.1,"discount_amount":null,"product_ids":null,"exclude_product_ids":false,"max_uses_per_customer":1,"max_uses_global":null}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/promotions/{promotion_id}":{"get":{"summary":"Get a promotion","operationId":"get_promotion","description":"Returns one promotion. A limited token gets only whether it applies to recurring billings, which a cart needs to tell the shopper. Secret, trusted and limited tokens may call it.","tags":["promotions"],"x-limited":true,"parameters":[{"name":"promotion_id","in":"path","required":true,"description":"The promotion id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The promotion.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/promotion"},"example":{"object":"promotion","url":"https://api.comecero.com/api/v1/promotions/0070576784690PtKDqfI","promotion_id":"0070576784690PtKDqfI","name":"Ten percent off","test":true,"account_id":"AB1234","date_created":"2026-11-02T20:13:16Z","date_modified":"2026-11-02T20:13:16Z","type":"coupon","active":true,"apply_to_recurring":false,"apply_to_recurring_count":null,"use_count":4,"expires":"2026-12-31T23:59:59Z","comments":null,"config":{"type":"order","code":"SAVE10","generator_prefix":null,"generator_secret_key":null,"discount_percent":0.1,"discount_amount":null,"product_ids":null,"exclude_product_ids":false,"max_uses_per_customer":1,"max_uses_global":null}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Update a promotion","operationId":"update_promotion","description":"Changes a promotion. Send only the fields you want to change. The type cannot change, and neither can a coupon's `code` or `generator_prefix`. Setting `apply_to_recurring` to false clears `apply_to_recurring_count`. Secret and trusted tokens may call it.","tags":["promotions"],"parameters":[{"name":"promotion_id","in":"path","required":true,"description":"The promotion id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"description":"The fields to change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/promotion_request"},"example":{"active":false}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The updated promotion.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/promotion"},"example":{"object":"promotion","url":"https://api.comecero.com/api/v1/promotions/0070576784690PtKDqfI","promotion_id":"0070576784690PtKDqfI","name":"Ten percent off","test":true,"account_id":"AB1234","date_created":"2026-11-02T20:13:16Z","date_modified":"2026-11-02T20:13:16Z","type":"coupon","active":true,"apply_to_recurring":false,"apply_to_recurring_count":null,"use_count":4,"expires":"2026-12-31T23:59:59Z","comments":null,"config":{"type":"order","code":"SAVE10","generator_prefix":null,"generator_secret_key":null,"discount_percent":0.1,"discount_amount":null,"product_ids":null,"exclude_product_ids":false,"max_uses_per_customer":1,"max_uses_global":null}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"summary":"Delete a promotion","operationId":"delete_promotion","description":"Deletes a promotion for good. Its code stops working at once. To stop a promotion and keep its history, update it with `active: false` instead. Secret and trusted tokens may call it.","tags":["promotions"],"parameters":[{"name":"promotion_id","in":"path","required":true,"description":"The promotion id.","schema":{"type":"string"}}],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The promotion is deleted. No body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/refund_list/{refund_list_id}":{"get":{"operationId":"get_refund_list","summary":"Get a refund list","description":"Returns the result of an earlier order refund again: the `refund_list` that `POST /orders/{order_id}/refunds` returned, with each refund in its current state. Its `url` is in that response.\n\nNeeds a secret or trusted token. Limited tokens get `403`.","tags":["refunds"],"parameters":[{"name":"refund_list_id","in":"path","description":"The refund list id, from `refund_list_id` in the refund response.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The refund list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/refund_list"},"example":{"object":"refund_list","url":"https://api.comecero.com/api/v1/refund_list/0090374314470RlA8kWm3T","refund_list_id":"0090374314470RlA8kWm3T","test":true,"account_id":"AB1234","currency":"USD","subtotal":49.95,"shipping":0,"tax":0,"total":49.95,"success_count":1,"failure_count":0,"refunds":[{"object":"refund","url":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5","refund_id":"0090374314462Rec3PffZ5","account_id":"AB1234","success":true,"status":"completed","reference":null,"date_created":"2026-11-03T10:12:40Z","date_modified":"2026-11-03T10:12:41Z","date_completed":"2026-11-03T10:12:41Z","test":true,"currency":"USD","subtotal":49.95,"shipping":0,"tax":0,"total":49.95,"reason":"Customer request","apply_to_balance":false,"is_chargeback":false,"record_only":false,"record_only_memo":null,"response_code":"OK","response_message":"OK","gateway_transaction_id":"re_test_3PffZ5","gateway_error_code":null,"gateway_error_message":null,"gateway":"https://api.comecero.com/api/v1/gateways/0089584408915Gtf5AsdJ8","comments":null,"payment_method":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/payment_method","settlement_currency":"USD","settlement_subtotal":49.95,"settlement_shipping":0,"settlement_tax":0,"settlement_total":49.95,"fx_rate":1,"reporting_currency":"USD","reporting_subtotal":49.95,"reporting_shipping":0,"reporting_tax":0,"reporting_total":49.95,"reporting_fx_rate":1,"items":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/items","customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","order":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954","payment":"https://api.comecero.com/api/v1/payments/0093717991362PyRYN1qc6","invoice":null,"fees":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fees","fee_summary":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fee_summary","commissions":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/commissions","meta":null}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/refunds":{"get":{"operationId":"list_refunds","summary":"List refunds","description":"Lists the refunds and chargebacks on your account, including failed and pending ones, oldest first unless you send `desc=true`. To make a refund, refund an order (`POST /orders/{order_id}/refunds`), an invoice or a payment.\n\nThe list is cursor-based: use `after_item` and `before_item` (or the `next_page_url` and `previous_page_url` in the response). It is ordered by the date named in `date_type` (`date_created` by default; `date_modified` and `date_completed` also work). `sort_by` is ignored.\n\nNeeds a secret or trusted token. Limited tokens get `403`.","tags":["refunds"],"parameters":[{"name":"status","in":"query","description":"Only refunds with this status.","required":false,"schema":{"type":"string","enum":["pending","completed","failed"]}},{"name":"is_chargeback","in":"query","description":"Only chargebacks (`true`) or only refunds (`false`).","required":false,"schema":{"type":"boolean"}},{"name":"reference","in":"query","description":"Only refunds with this exact `reference`.","required":false,"schema":{"type":"string"}},{"name":"q","in":"query","description":"Search. Matches the exact refund id, reference or customer email, or part of the customer's name or company name.","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/date_start"},{"$ref":"#/components/parameters/date_end"},{"$ref":"#/components/parameters/date_type"},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/after_item"},{"$ref":"#/components/parameters/before_item"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A cursor-based page of refunds.","content":{"application/json":{"schema":{"title":"refund_cursor_list","allOf":[{"$ref":"#/components/schemas/list_cursor"},{"type":"object","properties":{"data":{"type":"array","description":"The refunds on this page.","items":{"$ref":"#/components/schemas/refund"}}}}]},"example":{"next_page_url":"https://api.comecero.com/api/v1/refunds?after_item=0090374314462Rec3PffZ5","next_page_after_item":"0090374314462Rec3PffZ5","previous_page_url":null,"previous_page_before_item":null,"current_page_url":"https://api.comecero.com/api/v1/refunds","data":[{"object":"refund","url":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5","refund_id":"0090374314462Rec3PffZ5","account_id":"AB1234","success":true,"status":"completed","reference":null,"date_created":"2026-11-03T10:12:40Z","date_modified":"2026-11-03T10:12:41Z","date_completed":"2026-11-03T10:12:41Z","test":true,"currency":"USD","subtotal":49.95,"shipping":0,"tax":0,"total":49.95,"reason":"Customer request","apply_to_balance":false,"is_chargeback":false,"record_only":false,"record_only_memo":null,"response_code":"OK","response_message":"OK","gateway_transaction_id":"re_test_3PffZ5","gateway_error_code":null,"gateway_error_message":null,"gateway":"https://api.comecero.com/api/v1/gateways/0089584408915Gtf5AsdJ8","comments":null,"payment_method":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/payment_method","settlement_currency":"USD","settlement_subtotal":49.95,"settlement_shipping":0,"settlement_tax":0,"settlement_total":49.95,"fx_rate":1,"reporting_currency":"USD","reporting_subtotal":49.95,"reporting_shipping":0,"reporting_tax":0,"reporting_total":49.95,"reporting_fx_rate":1,"items":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/items","customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","order":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954","payment":"https://api.comecero.com/api/v1/payments/0093717991362PyRYN1qc6","invoice":null,"fees":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fees","fee_summary":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fee_summary","commissions":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/commissions","meta":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/refunds/options":{"get":{"operationId":"get_refund_options","summary":"Get refund options","description":"Returns the refund reasons and chargeback reasons set in your account's payment settings, for example to fill a reason picker. Send one of them as `reason` when you refund.\n\nNeeds a secret or trusted token. Limited tokens get `403`.","tags":["refunds"],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The refund options.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/refund_options"},"example":{"account_id":"AB1234","test":true,"refund_reasons":["Customer request","Duplicate order","Product not as described"],"chargeback_reasons":["Fraudulent","Product not received"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/refunds/{refund_id}":{"get":{"operationId":"get_refund","summary":"Get a refund","description":"Returns one refund or chargeback.\n\nSecret and trusted tokens can read any refund on the account. A limited token can read a refund only when it is bound to it, and the gateway, chargeback and settlement fields are left out for it.","tags":["refunds"],"x-limited":true,"parameters":[{"name":"refund_id","in":"path","description":"The refund id.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/timezone"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The refund.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/refund"},"example":{"object":"refund","url":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5","refund_id":"0090374314462Rec3PffZ5","account_id":"AB1234","success":true,"status":"completed","reference":null,"date_created":"2026-11-03T10:12:40Z","date_modified":"2026-11-03T10:12:41Z","date_completed":"2026-11-03T10:12:41Z","test":true,"currency":"USD","subtotal":49.95,"shipping":0,"tax":0,"total":49.95,"reason":"Customer request","apply_to_balance":false,"is_chargeback":false,"record_only":false,"record_only_memo":null,"response_code":"OK","response_message":"OK","gateway_transaction_id":"re_test_3PffZ5","gateway_error_code":null,"gateway_error_message":null,"gateway":"https://api.comecero.com/api/v1/gateways/0089584408915Gtf5AsdJ8","comments":null,"payment_method":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/payment_method","settlement_currency":"USD","settlement_subtotal":49.95,"settlement_shipping":0,"settlement_tax":0,"settlement_total":49.95,"fx_rate":1,"reporting_currency":"USD","reporting_subtotal":49.95,"reporting_shipping":0,"reporting_tax":0,"reporting_total":49.95,"reporting_fx_rate":1,"items":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/items","customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","order":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954","payment":"https://api.comecero.com/api/v1/payments/0093717991362PyRYN1qc6","invoice":null,"fees":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fees","fee_summary":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fee_summary","commissions":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/commissions","meta":null}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"update_refund","summary":"Update a refund","description":"Changes your `comments` or `meta` on a refund. Amounts and status cannot be changed. No money moves and no event fires.\n\nNeeds a secret or trusted token. Limited tokens get `403`.","tags":["refunds"],"parameters":[{"name":"refund_id","in":"path","description":"The refund id.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/refund_update_request"},"examples":{"comments":{"summary":"Add a comment","value":{"comments":"Customer was refunded after a support call."}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The updated refund.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/refund"},"example":{"object":"refund","url":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5","refund_id":"0090374314462Rec3PffZ5","account_id":"AB1234","success":true,"status":"completed","reference":null,"date_created":"2026-11-03T10:12:40Z","date_modified":"2026-11-03T10:12:41Z","date_completed":"2026-11-03T10:12:41Z","test":true,"currency":"USD","subtotal":49.95,"shipping":0,"tax":0,"total":49.95,"reason":"Customer request","apply_to_balance":false,"is_chargeback":false,"record_only":false,"record_only_memo":null,"response_code":"OK","response_message":"OK","gateway_transaction_id":"re_test_3PffZ5","gateway_error_code":null,"gateway_error_message":null,"gateway":"https://api.comecero.com/api/v1/gateways/0089584408915Gtf5AsdJ8","comments":null,"payment_method":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/payment_method","settlement_currency":"USD","settlement_subtotal":49.95,"settlement_shipping":0,"settlement_tax":0,"settlement_total":49.95,"fx_rate":1,"reporting_currency":"USD","reporting_subtotal":49.95,"reporting_shipping":0,"reporting_tax":0,"reporting_total":49.95,"reporting_fx_rate":1,"items":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/items","customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","order":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954","payment":"https://api.comecero.com/api/v1/payments/0093717991362PyRYN1qc6","invoice":null,"fees":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fees","fee_summary":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fee_summary","commissions":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/commissions","meta":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"operationId":"delete_refund","summary":"Delete a refund","description":"Removes a chargeback or record-only refund that was entered by mistake. Only works for a refund with `is_chargeback` or `record_only` set, on a gateway that belongs to your account; any other refund gets `422`. No money moves: a refund that really sent money back cannot be deleted. The refund is removed from reports and the `refund:deleted` event fires.\n\nNeeds a secret or trusted token. Limited tokens get `403`.","tags":["refunds"],"parameters":[{"name":"refund_id","in":"path","description":"The refund id.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The refund was deleted. No body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"The refund is not a chargeback or record-only refund, or it was made on a gateway that Comecero owns.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/refunds/{refund_id}/commissions":{"get":{"operationId":"list_refund_commissions","summary":"List a refund's commissions","description":"Lists the commissions recorded for one refund. A refund takes back the commission paid on the sale, so the totals are negative. Offset-based (`offset`, `limit`). `sort_by` takes `date_created` (default) or `date_modified`. Note that the paging URLs in the response point to `/payments/{refund_id}/commissions`; build the next page URL from `next_page_offset` instead.\n\nNeeds a secret or trusted token that may read commissions. Limited tokens get `403`.","tags":["refunds"],"parameters":[{"name":"refund_id","in":"path","description":"The refund id.","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","description":"Only commissions of this type.","required":false,"schema":{"type":"string","enum":["product_sales"]}},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/desc"},{"name":"sort_by","in":"query","description":"The field to sort by.","required":false,"schema":{"type":"string","default":"date_created","enum":["date_created","date_modified"]}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"An offset-based page of commissions.","content":{"application/json":{"schema":{"title":"commission_offset_list","allOf":[{"$ref":"#/components/schemas/list_offset"},{"type":"object","properties":{"data":{"type":"array","description":"The commissions on this page.","items":{"$ref":"#/components/schemas/commission"}}}}]},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/commissions","data":[{"object":"commission","url":"https://api.comecero.com/api/v1/commissions/0090374314511CoH6tPz4v","commission_id":"0090374314511CoH6tPz4v","date_created":"2026-11-03T10:12:41Z","date_modified":"2026-11-03T10:12:41Z","test":true,"total":-49.95,"currency":"USD","type":"product_sales","description":null,"transaction_type":"refund","transaction":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5","accounting_id":"C-AB1234R261130USD"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/refunds/{refund_id}/complete":{"post":{"operationId":"complete_refund","summary":"Complete a pending refund","description":"Marks a `pending` refund `completed` without asking the payment provider again. For staff use when a refund did go through but Comecero never heard back. Completing it records fees and commissions, fires `refund:created_success` and sends the customer the refund email. A refund that is not pending comes back unchanged. No body is read.\n\nOnly Comecero staff (admin tokens) may call this. Secret, trusted and limited tokens get `403`.","tags":["refunds"],"parameters":[{"name":"refund_id","in":"path","description":"The refund id.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The refund, now completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/refund"},"example":{"object":"refund","url":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5","refund_id":"0090374314462Rec3PffZ5","account_id":"AB1234","success":true,"status":"completed","reference":null,"date_created":"2026-11-03T10:12:40Z","date_modified":"2026-11-03T10:12:41Z","date_completed":"2026-11-03T10:12:41Z","test":true,"currency":"USD","subtotal":49.95,"shipping":0,"tax":0,"total":49.95,"reason":"Customer request","apply_to_balance":false,"is_chargeback":false,"record_only":false,"record_only_memo":null,"response_code":"OK","response_message":"OK","gateway_transaction_id":"re_test_3PffZ5","gateway_error_code":null,"gateway_error_message":null,"gateway":"https://api.comecero.com/api/v1/gateways/0089584408915Gtf5AsdJ8","comments":null,"payment_method":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/payment_method","settlement_currency":"USD","settlement_subtotal":49.95,"settlement_shipping":0,"settlement_tax":0,"settlement_total":49.95,"fx_rate":1,"reporting_currency":"USD","reporting_subtotal":49.95,"reporting_shipping":0,"reporting_tax":0,"reporting_total":49.95,"reporting_fx_rate":1,"items":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/items","customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","order":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954","payment":"https://api.comecero.com/api/v1/payments/0093717991362PyRYN1qc6","invoice":null,"fees":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fees","fee_summary":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fee_summary","commissions":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/commissions","meta":null}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/refunds/{refund_id}/fee_summary":{"get":{"operationId":"get_refund_fee_summary","summary":"Get a refund's fee summary","description":"Returns the Comecero fees on one refund, added up per currency.\n\nNeeds a secret or trusted token that may read fees. Limited tokens are refused. A token without the fees permission gets `401`, not `403`.","tags":["refunds"],"parameters":[{"name":"refund_id","in":"path","description":"The refund id.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The fee summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/order_fee_summary"},"example":{"object":"fee_summary","url":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fee_summary","fixed_amount":0,"percentage_amount":0,"total":0.25,"currency":"USD","totals":[{"currency":"USD","fixed_amount":0,"percentage_amount":0,"total":0.25}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/refunds/{refund_id}/fees":{"get":{"operationId":"list_refund_fees","summary":"List a refund's fees","description":"Lists the Comecero fees recorded for one refund. Offset-based (`offset`, `limit`). `sort_by` takes `date_created` (default) or `date_modified`.\n\nNeeds a secret or trusted token that may read fees. Limited tokens get `403`.","tags":["refunds"],"parameters":[{"name":"refund_id","in":"path","description":"The refund id.","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","description":"Only fees of this type, for example `refund_completed` or `chargeback`.","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/desc"},{"name":"sort_by","in":"query","description":"The field to sort by.","required":false,"schema":{"type":"string","default":"date_created","enum":["date_created","date_modified"]}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"An offset-based page of fees.","content":{"application/json":{"schema":{"title":"fee_offset_list","allOf":[{"$ref":"#/components/schemas/list_offset"},{"type":"object","properties":{"data":{"type":"array","description":"The fees on this page.","items":{"$ref":"#/components/schemas/fee"}}}}]},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fees","data":[{"object":"fee","url":"https://api.comecero.com/api/v1/fees/0090374314500FeD2mLw9x","fee_id":"0090374314500FeD2mLw9x","date_created":"2026-11-03T10:12:41Z","date_modified":"2026-11-03T10:12:41Z","test":true,"account_id":"AB1234","fixed_amount":0,"percentage":0,"percentage_amount":0,"total":0.25,"currency":"USD","type":"refund_completed","category":"transaction","collected":false,"description":"Refund completed","transaction_type":"refund","transaction":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5","contract":null,"accounting_id":"C-AB1234R261130USD"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/refunds/{refund_id}/items":{"get":{"operationId":"list_refund_items","summary":"List a refund's items","description":"Lists the items given back in a refund of an order or invoice. A refund of an amount (not items) has no items. Offset-based (`offset`, `limit`). `sort_by` takes `date_created` (default), `date_modified` or `product_id`. Note that the paging URLs in the response point to `/refunds`; build the next page URL from `next_page_offset` instead.\n\nA limited token may call this for a refund it is bound to.","tags":["refunds"],"x-limited":true,"parameters":[{"name":"refund_id","in":"path","description":"The refund id.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/desc"},{"name":"sort_by","in":"query","description":"The field to sort by.","required":false,"schema":{"type":"string","default":"date_created","enum":["date_created","date_modified","product_id"]}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"An offset-based page of refund items.","content":{"application/json":{"schema":{"title":"refund_item_list","allOf":[{"$ref":"#/components/schemas/list_offset"},{"type":"object","properties":{"data":{"type":"array","description":"The refund items on this page.","items":{"$ref":"#/components/schemas/refund_item"}}}}]},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/items","data":[{"object":"refund_item","url":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/items/1","item_id":"1","date_created":"2026-11-02T16:46:16Z","date_modified":"2026-11-03T10:12:40Z","refund_id":"0090374314462Rec3PffZ5","name":"PDF Viewer Pro","type":"digital","quantity":1,"currency":"USD","price":49.95,"reference_price":49.95,"reference_currency":"USD","subtotal":49.95,"tax":0,"total":49.95,"tax_rate":0,"tax_code":null,"settlement_currency":"USD","settlement_price":49.95,"settlement_subtotal":49.95,"settlement_tax":0,"settlement_total":49.95,"fulfilled":true,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription":null,"meta":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/refunds/{refund_id}/items/{item_id}":{"get":{"operationId":"get_refund_item","summary":"Get a refund item","description":"Returns one item of a refund. A limited token may call this for a refund it is bound to.","tags":["refunds"],"x-limited":true,"parameters":[{"name":"refund_id","in":"path","description":"The refund id.","required":true,"schema":{"type":"string"}},{"name":"item_id","in":"path","description":"The `item_id` of the order or invoice item.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The refund item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/refund_item"},"example":{"object":"refund_item","url":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/items/1","item_id":"1","date_created":"2026-11-02T16:46:16Z","date_modified":"2026-11-03T10:12:40Z","refund_id":"0090374314462Rec3PffZ5","name":"PDF Viewer Pro","type":"digital","quantity":1,"currency":"USD","price":49.95,"reference_price":49.95,"reference_currency":"USD","subtotal":49.95,"tax":0,"total":49.95,"tax_rate":0,"tax_code":null,"settlement_currency":"USD","settlement_price":49.95,"settlement_subtotal":49.95,"settlement_tax":0,"settlement_total":49.95,"fulfilled":true,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription":null,"meta":null}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/refunds/{refund_id}/notifications":{"get":{"operationId":"list_refund_notifications","summary":"List a refund's notifications","description":"Lists the emails sent to the customer about this refund. Offset-based (`offset`, `limit`). `sort_by` takes `date_created` (default) or `date_modified`.\n\nA limited token may call this for a refund it is bound to.","tags":["refunds"],"x-limited":true,"parameters":[{"name":"refund_id","in":"path","description":"The refund id.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/desc"},{"name":"sort_by","in":"query","description":"The field to sort by.","required":false,"schema":{"type":"string","default":"date_created","enum":["date_created","date_modified"]}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"An offset-based page of notifications.","content":{"application/json":{"schema":{"title":"notification_offset_list","allOf":[{"$ref":"#/components/schemas/list_offset"},{"type":"object","properties":{"data":{"type":"array","description":"The notifications on this page.","items":{"$ref":"#/components/schemas/notification"}}}}]},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/notifications","data":[{"object":"notification","url":"https://api.comecero.com/api/v1/notifications/0093718200533NtX7cR1pQ","notification_id":"0093718200533NtX7cR1pQ","test":true,"account_id":"AB1234","type":"refund:confirmation","method":"email","from":"notification@comecero.com","from_name":"Example Shop","reply_to":"support@example.com","bcc":null,"destination":"john@example.com","subject":"Your refund","customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","status":"delivered","date_created":"2026-11-03T10:12:45Z","date_modified":"2026-11-03T10:12:47Z"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/refunds/{refund_id}/payment_method":{"get":{"operationId":"get_refund_payment_method","summary":"Get a refund's payment method","description":"Returns the payment method the money went back to: the card, wallet or bank account of the payment, or the customer's store credit (`customer_account_balance`). Card numbers are masked. A record-only refund has no payment method, so you get an empty object `{}`.\n\nA limited token may call this for a refund it is bound to.","tags":["refunds"],"x-limited":true,"parameters":[{"name":"refund_id","in":"path","description":"The refund id.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The payment method, or `{}` for a record-only refund.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_method"},"example":{"url":"https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/payment_methods/0092503470929PmEP0ivO4","object":"payment_method","payment_method_id":"0092503470929PmEP0ivO4","date_created":"2026-11-02T18:20:31Z","date_modified":"2026-11-02T18:20:31Z","test":true,"type":"credit_card","data":{"object":"credit_card","mask":"4***********1111","fingerprint":"2321657x8123834dc21ea08f","exp_month":12,"exp_year":28,"cardholder_name":"John Doe","ending":"1111","type":"Visa","label":"Visa 1111","billing_address":{"object":"address","name":"John Doe","address_1":"123 Main St.","address_2":null,"city":"New York","state_prov":"NY","postal_code":"10019","country":"US","email":null,"meta":null}},"is_default":true,"date_last_used":"2026-11-02T18:20:31Z"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/reports/commissions":{"get":{"summary":"Get the commissions report","operationId":"get_commissions_report","tags":["reports"],"description":"Totals the commissions Comecero owes your account, per currency, with one breakdown row per commission type. A commission is recorded when a payment is taken on a Comecero-owned gateway: the settlement total less tax, or the full total on an agent account. A refund records a negative commission.\n\nSend `accounting_id` to get the commissions on one payout. With an `accounting_id` and no dates, every date is included. With no `accounting_id` and no dates, the report covers yesterday in the report time zone. A `date_start` later than today is refused.\n\nWithout `currency`, amounts stay in each commission's own currency, one group per currency. With one of your reporting currencies, every commission is converted into it and there is one group. Needs a secret or trusted token with permission to read reports.","parameters":[{"$ref":"#/components/parameters/date_start"},{"$ref":"#/components/parameters/date_end"},{"$ref":"#/components/parameters/timezone"},{"name":"sort_by","in":"query","required":false,"description":"How to order the currency groups. Any other value orders by `total`.","schema":{"type":"string","enum":["total","currency","transaction_count"],"default":"total"}},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/formatted"},{"name":"accounting_id","in":"query","required":false,"description":"Only count the commissions on this payout, for example `C-AB1234P261130USD`. It starts with `C-` and is 18 or 20 characters long.","schema":{"type":"string","example":"C-AB1234P261130USD"}},{"name":"currency","in":"query","required":false,"description":"One of your two reporting currencies (Settings, General). Any other value is refused. Leave it out to keep each commission in its own currency.","schema":{"type":"string","example":"USD"}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The commissions report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/report_commissions"},"example":{"object":"report.commissions","url":"https://api.comecero.com/api/v1/reports/commissions?date_start=2026-11-01T00:00:00&date_end=2026-11-06T23:59:59&timezone=UTC","account_id":"AB1234","date_created":"2026-11-07T14:12:44Z","date_start":"2026-11-01T00:00:00Z","date_end":"2026-11-06T23:59:59Z","timezone":"UTC","test":true,"type":null,"data":[{"currency":"USD","total":249.9,"transaction_count":3,"breakdowns":[{"type":"product_sales","total":249.9,"transaction_count":3}]}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/reports/fees":{"get":{"summary":"Get the fees report","operationId":"get_fees_report","tags":["reports"],"description":"Totals the fees Comecero charged your account, per currency, with one breakdown row per fee type. Fees the provider already took from the money (Comecero Express Payments) are shown apart as `collected_total` and are not in `total`.\n\nSend `accounting_id` to get the fees on one bill. With an `accounting_id` and no dates, every date is included. With no `accounting_id` and no dates, the report covers yesterday in the report time zone. A `date_start` later than today is refused. The range is read against the date each fee was created.\n\nWithout `currency`, amounts stay in each fee's own currency, one group per currency. With one of your reporting currencies, every fee is converted into it and there is one group. Needs a secret or trusted token with permission to read reports.","parameters":[{"$ref":"#/components/parameters/date_start"},{"$ref":"#/components/parameters/date_end"},{"$ref":"#/components/parameters/timezone"},{"name":"sort_by","in":"query","required":false,"description":"How to order the currency groups. Any other value orders by `total`.","schema":{"type":"string","enum":["total","currency","transaction_count"],"default":"total"}},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/formatted"},{"name":"type","in":"query","required":false,"description":"Only count fees of this type.","schema":{"type":"string","enum":["payment_completed","refund_completed","auth","zero_auth","capture","void","decline","chargeback","fx_conversion","international_card","payout","platform_monthly","platform_annual","support_annual","miscellaneous"]}},{"name":"category","in":"query","required":false,"description":"Only count fees in this category: `transaction` (fees on payments and refunds) or `operation` (account fees).","schema":{"type":"string","enum":["transaction","operation"]}},{"name":"accounting_id","in":"query","required":false,"description":"Only count the fees on this bill, for example `C-AB1234R261130USD`. It starts with `C-` and is 18 or 20 characters long.","schema":{"type":"string","example":"C-AB1234R261130USD"}},{"name":"currency","in":"query","required":false,"description":"One of your two reporting currencies (Settings, General). Any other value is refused. Leave it out to keep each fee in its own currency.","schema":{"type":"string","example":"USD"}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The fees report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/report_fees"},"example":{"object":"report.fees","url":"https://api.comecero.com/api/v1/reports/fees?date_start=2026-11-01T00:00:00&date_end=2026-11-06T23:59:59&timezone=UTC","account_id":"AB1234","date_created":"2026-11-07T14:12:44Z","date_start":"2026-11-01T00:00:00Z","date_end":"2026-11-06T23:59:59Z","timezone":"UTC","test":true,"type":null,"data":[{"currency":"USD","total":4.5,"transaction_count":3,"collected_total":0,"collected_transaction_count":0,"breakdowns":[{"type":"payment_completed","category":"transaction","collected":false,"total":4.5,"transaction_count":3}]}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/reports/items":{"get":{"summary":"Get the items report","operationId":"get_items_report","tags":["reports"],"description":"Totals your sales per product for a date range: subtotal, tax, total, number of orders and units sold, one row per `item_id`. The list is offset-based, up to 100 rows a page.\n\nWith no dates, the report covers yesterday in the report time zone. A `date_end` later than today is cut back to the end of today, and a `date_start` later than today is refused. There is no maximum range.\n\nAmounts are in your primary reporting currency, or your secondary one when you send it in `currency`. Needs a secret or trusted token with permission to read reports.","parameters":[{"$ref":"#/components/parameters/date_start"},{"$ref":"#/components/parameters/date_end"},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"name":"sort_by","in":"query","required":false,"description":"The field to sort the rows by. Any other value sorts by `subtotal`.","schema":{"type":"string","enum":["subtotal","name","item_id"],"default":"subtotal"}},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/formatted"},{"name":"type","in":"query","required":false,"description":"Which transactions to count: `payments`, `refunds` (as negative amounts) or `combined` (payments net of refunds on the items in this page).","schema":{"type":"string","enum":["payments","refunds","combined"],"default":"payments"}},{"name":"currency","in":"query","required":false,"description":"One of your two reporting currencies (Settings, General). Any other value is refused. Leave it out for the primary reporting currency.","schema":{"type":"string","example":"EUR"}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The items report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/report_items"},"example":{"object":"report.items","url":"https://api.comecero.com/api/v1/reports/items?date_start=2026-11-01T00:00:00&date_end=2026-11-06T23:59:59&type=payments&timezone=UTC","account_id":"AB1234","date_created":"2026-11-07T14:12:44Z","date_start":"2026-11-01T00:00:00Z","date_end":"2026-11-06T23:59:59Z","timezone":"UTC","test":true,"type":"payments","currency":"USD","next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"data":[{"item_id":"prod-pro-1y.test","name":"Pro license, 1 year","subtotal":299.85,"tax":0,"total":299.85,"transaction_count":3,"item_count":3}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/reports/sales":{"get":{"summary":"Get the sales report","operationId":"get_sales_report","tags":["reports"],"description":"Totals your sales for a date range: subtotal, shipping, tax, total, transaction count and item count, with sum, average, min, max and median. Set `group_by` to get one row per hour, day, month or year.\n\nWith no dates, the report covers yesterday in the report time zone. A `date_end` later than today is cut back to the end of today, and a `date_start` later than today is refused. The longest range is 31 days by hour, 2 years by day, 5 years by month and 10 years by year.\n\nThe time zone is your account's, or the one you send in `timezone`. All amounts are in your primary reporting currency, or your secondary one when you send it in `currency`. Needs a secret or trusted token with permission to read reports.","parameters":[{"$ref":"#/components/parameters/date_start"},{"$ref":"#/components/parameters/date_end"},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/formatted"},{"name":"group_by","in":"query","required":false,"description":"Split the report into one row per period. Leave it out (or send `none`) for one row for the whole range.","schema":{"type":"string","enum":["none","hour","day","month","year"]}},{"name":"type","in":"query","required":false,"description":"Which transactions to count: `payments`, `refunds` (as negative amounts) or `combined` (payments net of refunds).","schema":{"type":"string","enum":["payments","refunds","combined"],"default":"payments"}},{"name":"segment","in":"query","required":false,"description":"Which sales to count.","schema":{"type":"string","enum":["all","non_subscriptions","subscriptions","new_subscriptions","renewal_subscriptions"],"default":"all"}},{"name":"currency","in":"query","required":false,"description":"One of your two reporting currencies (Settings, General). Any other value is refused. Leave it out for the primary reporting currency.","schema":{"type":"string","example":"EUR"}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The sales report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/report_sales"},"example":{"object":"report.sales","url":"https://api.comecero.com/api/v1/reports/sales?date_start=2026-11-01T00:00:00&date_end=2026-11-02T23:59:59&type=payments&segment=all&timezone=America/New_York","account_id":"AB1234","date_created":"2026-11-07T09:12:44-05:00","date_start":"2026-11-01T00:00:00-04:00","date_end":"2026-11-02T23:59:59-05:00","timezone":"America/New_York","test":true,"type":"payments","segment":"all","currency":"USD","subtotal":{"sum":149.9,"average":74.95,"max":99.95,"min":49.95,"median":74.95},"tax":{"sum":0,"average":0,"max":0,"min":0,"median":0},"shipping":{"sum":0,"average":0,"max":0,"min":0,"median":0},"total":{"sum":149.9,"average":74.95,"max":99.95,"min":49.95,"median":74.95},"transaction_count":{"sum":2,"average":1,"max":1,"min":1,"median":1},"item_count":{"sum":2,"average":1,"max":1,"min":1,"median":1},"data":[{"date":"2026-11-01","subtotal":99.95,"shipping":0,"tax":0,"total":99.95,"transaction_count":1,"item_count":1},{"date":"2026-11-02","subtotal":49.95,"shipping":0,"tax":0,"total":49.95,"transaction_count":1,"item_count":1}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/reports/sales_summary":{"get":{"summary":"Get the sales summary","operationId":"get_sales_summary_report","tags":["reports"],"description":"Totals your completed payments and refunds per currency: subtotal, shipping, tax and total. Send `currency` to get one total with every currency converted into it.\n\nWith no dates, the report covers yesterday in the report time zone. A `date_end` later than today is cut back to the end of today, and a `date_start` later than today is refused. The range is read against the date each transaction completed.\n\nAmounts are in the settlement currency by default, or the payment currency with `currency_type=payment`. With `currency`, each row is converted at the wholesale rate less 3 percent (no change when it is already in that currency). Needs a secret or trusted token with permission to read reports.","parameters":[{"$ref":"#/components/parameters/date_start"},{"$ref":"#/components/parameters/date_end"},{"$ref":"#/components/parameters/timezone"},{"name":"sort_by","in":"query","required":false,"description":"How to order the rows. Any other value orders by `total`.","schema":{"type":"string","enum":["total","currency"],"default":"total"}},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/formatted"},{"name":"type","in":"query","required":false,"description":"Which transactions to count: `payments`, `refunds` (as negative amounts) or `combined` (payments net of refunds).","schema":{"type":"string","enum":["payments","refunds","combined"],"default":"combined"}},{"name":"currency_type","in":"query","required":false,"description":"Total the currency the customer paid in (`payment`) or the currency the money settled in (`settlement`).","schema":{"type":"string","enum":["payment","settlement"],"default":"settlement"}},{"name":"account_model","in":"query","required":false,"description":"Only count transactions made while your account had this model. Leave it out to count both.","schema":{"type":"string","enum":["reseller","agent"]}},{"name":"currency","in":"query","required":false,"description":"A three-letter currency code (any currency Comecero supports). Every row is converted into it and added into one row.","schema":{"type":"string","example":"USD"}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The sales summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/report_sales_summary"},"example":{"object":"report.sales_summary","url":"https://api.comecero.com/api/v1/reports/sales_summary?date_start=2026-11-01T00:00:00&date_end=2026-11-06T23:59:59&timezone=UTC","account_id":"AB1234","date_created":"2026-11-07T14:12:44Z","date_start":"2026-11-01T00:00:00Z","date_end":"2026-11-06T23:59:59Z","timezone":"UTC","test":true,"type":null,"data":[{"currency":"USD","subtotal":249.9,"shipping":0,"tax":10.25,"total":260.15},{"currency":"EUR","subtotal":84,"shipping":0,"tax":15.96,"total":99.96}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/reports/tax":{"get":{"summary":"Get the tax report","operationId":"get_tax_report","tags":["reports"],"description":"Totals your taxed sales per currency, tax country and state or province: subtotal, shipping, tax, total and total less tax. Only payments and refunds with tax above zero are counted, so use it for tax returns, not for total sales.\n\nWith no dates, the report covers last month in the report time zone. A `date_end` later than today is cut back to the end of today, and a `date_start` later than today is refused. The range is read against the date each transaction completed.\n\nAmounts are in the payment currency, or the settlement currency with `currency_type=settlement`. They are never converted. Needs a secret or trusted token with permission to read reports.","parameters":[{"$ref":"#/components/parameters/date_start"},{"$ref":"#/components/parameters/date_end"},{"$ref":"#/components/parameters/timezone"},{"name":"sort_by","in":"query","required":false,"description":"How to order the rows. Any other value orders by country.","schema":{"type":"string","enum":["country","currency"],"default":"country"}},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/formatted"},{"name":"type","in":"query","required":false,"description":"Which transactions to count: `payments`, `refunds` (as negative amounts) or `combined` (payments net of refunds).","schema":{"type":"string","enum":["payments","refunds","combined"],"default":"combined"}},{"name":"currency_type","in":"query","required":false,"description":"Report in the currency the customer paid in (`payment`) or the currency the money settled in (`settlement`).","schema":{"type":"string","enum":["payment","settlement"],"default":"payment"}},{"name":"account_model","in":"query","required":false,"description":"Only count transactions made while your account had this model. Defaults to your account's model today.","schema":{"type":"string","enum":["reseller","agent"]}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The tax report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/report_tax"},"example":{"object":"report.tax","url":"https://api.comecero.com/api/v1/reports/tax?date_start=2026-10-01T00:00:00&date_end=2026-10-31T23:59:59&timezone=UTC","account_id":"AB1234","date_created":"2026-11-07T14:12:44Z","date_start":"2026-10-01T00:00:00Z","date_end":"2026-10-31T23:59:59Z","timezone":"UTC","test":true,"type":"combined","data":[{"currency":"EUR","country":"DE","state_prov":null,"subtotal":84,"shipping":0,"tax":15.96,"total":99.96,"total_minus_tax":84},{"currency":"USD","country":"US","state_prov":"WA","subtotal":99.95,"shipping":0,"tax":10.25,"total":110.2,"total_minus_tax":99.95}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/roles":{"get":{"summary":"List roles","operationId":"list_roles","description":"Lists the roles of your account in the mode of the token you call with. The list is offset-based.\n\nSecret and trusted tokens may call this with the `roles` read permission.","tags":["roles"],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"name":"sort_by","in":"query","description":"The field to sort by. The default is `role_id`.","required":false,"schema":{"type":"string","enum":["role_id","date_created","date_modified"],"default":"role_id"}},{"$ref":"#/components/parameters/desc"},{"name":"q","in":"query","description":"Finds the role with exactly this `role_id`. If there is none, finds the roles whose name contains it (any case).","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/timezone"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"An offset-based list of roles.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/role_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/roles","data":[{"object":"role","url":"https://api.comecero.com/api/v1/roles/support","role_id":"support","date_created":"2026-10-01T14:36:52Z","date_modified":"2026-10-01T14:36:52Z","test":true,"account_id":"AB1234","name":"Support","comments":"Can look up and update orders and customers.","permission_type":null,"permissions":[{"resource":"orders","methods":["read","update"],"allow":true}]}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Create a role","operationId":"create_role","description":"Creates a role in the mode of the token you call with. Give it to users and secret tokens through their `roles` list.\n\nSecret and trusted tokens may call this with the `roles` create permission.","tags":["roles"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/role_request"},"examples":{"role":{"summary":"A support role","value":{"name":"Support","comments":"Can look up and update orders and customers.","permissions":[{"resource":"orders","methods":["read","update"],"allow":true},{"resource":"customers","methods":["read"],"allow":true}]}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new role.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/role"},"example":{"object":"role","url":"https://api.comecero.com/api/v1/roles/support","role_id":"support","date_created":"2026-10-01T14:36:52Z","date_modified":"2026-10-01T14:36:52Z","test":true,"account_id":"AB1234","name":"Support","comments":"Can look up and update orders and customers.","permission_type":null,"permissions":[{"resource":"orders","methods":["read","update"],"allow":true},{"resource":"customers","methods":["read"],"allow":true}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/roles/{role_id}":{"parameters":[{"name":"role_id","in":"path","description":"The role's `role_id`.","required":true,"schema":{"type":"string"},"example":"support"}],"get":{"summary":"Get a role","operationId":"get_role","description":"Gets one role. A role of the other mode is not found (`404`).\n\nSecret and trusted tokens may call this with the `roles` read permission.","tags":["roles"],"parameters":[{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/timezone"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The role.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/role"},"example":{"object":"role","url":"https://api.comecero.com/api/v1/roles/support","role_id":"support","date_created":"2026-10-01T14:36:52Z","date_modified":"2026-10-01T14:36:52Z","test":true,"account_id":"AB1234","name":"Support","comments":"Can look up and update orders and customers.","permission_type":null,"permissions":[{"resource":"orders","methods":["read","update"],"allow":true},{"resource":"customers","methods":["read"],"allow":true}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"put":{"summary":"Replace a role","operationId":"update_role","description":"Replaces a role with the one you send. This is `PUT`, not `POST`: send the whole role, including its `role_id` (`400` without it) and at least one permission. Fields you leave out are cleared.\n\nSecret and trusted tokens may call this with the `roles` update permission.","tags":["roles"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/role_request"},"example":{"role_id":"support","name":"Support","comments":"Can look up orders and customers.","permissions":[{"resource":"orders","methods":["read"],"allow":true},{"resource":"customers","methods":["read"],"allow":true}]}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The role.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/role"},"example":{"object":"role","url":"https://api.comecero.com/api/v1/roles/support","role_id":"support","date_created":"2026-10-01T14:36:52Z","date_modified":"2026-10-01T14:36:52Z","test":true,"account_id":"AB1234","name":"Support","comments":"Can look up and update orders and customers.","permission_type":null,"permissions":[{"resource":"orders","methods":["read","update"],"allow":true},{"resource":"customers","methods":["read"],"allow":true}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"summary":"Delete a role","operationId":"delete_role","description":"Deletes a role. Users and tokens that list it keep the `role_id` but no longer get its permissions.\n\nSecret and trusted tokens may call this with the `roles` delete permission.","tags":["roles"],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The role is deleted. No body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/settings/analytics":{"get":{"operationId":"get_analytics_settings","summary":"Get analytics settings","description":"Returns the tracking settings: your GA4 measurement ID, Google Ads conversion ID and label, Matomo site and your own tracking code. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_analytics`. Limited tokens may not.","tags":["settings"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The analytics settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_analytics"},"example":{"object":"settings_analytics","url":"https://api.comecero.com/api/v1/settings/analytics","account_id":"AB1234","test":true,"date_modified":"2026-10-02T14:21:07Z","pageview_tracking":null,"conversion_tracking":null,"google_tracking_id":null,"ga4_measurement_id":"G-4X7KQ2M9PL","google_ads_id":"AW-123456789","google_ads_label":"AbC_dEfGh-12","matomo_url":null,"matomo_site_id":null,"has_matomo_token_auth":false,"send_transactions":false,"send_events":false}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"update_analytics_settings","summary":"Update analytics settings","description":"Changes the tracking settings. Send only the fields you want to change. The tracking scripts are rebuilt at once, so the change shows on the next page load. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_analytics`. Limited tokens may not.","tags":["settings"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_analytics_request"},"examples":{"analytics":{"summary":"Google Analytics and Google Ads","value":{"ga4_measurement_id":"G-4X7KQ2M9PL","google_ads_id":"AW-123456789","google_ads_label":"AbC_dEfGh-12"}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The analytics settings, after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_analytics"},"example":{"object":"settings_analytics","url":"https://api.comecero.com/api/v1/settings/analytics","account_id":"AB1234","test":true,"date_modified":"2026-10-02T14:21:07Z","pageview_tracking":null,"conversion_tracking":null,"google_tracking_id":null,"ga4_measurement_id":"G-4X7KQ2M9PL","google_ads_id":"AW-123456789","google_ads_label":"AbC_dEfGh-12","matomo_url":null,"matomo_site_id":null,"has_matomo_token_auth":false,"send_transactions":false,"send_events":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/settings/fraud":{"get":{"operationId":"get_fraud_settings","summary":"Get fraud settings","description":"Returns the fraud screening rules: the score threshold, payment counts per shopper and blocked countries. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Only Comecero staff tokens may call it. Secret and trusted tokens get `403`; ask support to change these rules.","tags":["settings"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The fraud settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_fraud"},"example":{"object":"settings_fraud","url":"https://api.comecero.com/api/v1/settings/fraud","account_id":"AB1234","test":true,"date_created":"2026-01-12T09:30:00Z","date_modified":"2026-10-02T14:21:07Z","enable_fraud_screening":true,"max_score":0.6,"max_successful_payments":5,"max_failed_payments":3,"block_ip_country_mismatch":false,"blocked_countries":null,"step_up_enabled":null,"step_up_max_score":null}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"update_fraud_settings","summary":"Update fraud settings","description":"Changes the fraud screening rules. Send only the fields you want to change. The 3-D Secure step-up fields can only be changed by Comecero (`403`). Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Only Comecero staff tokens may call it. Secret and trusted tokens get `403`; ask support to change these rules.","tags":["settings"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_fraud_request"},"examples":{"fraud":{"summary":"Score limit and blocked countries","value":{"max_score":0.6,"blocked_countries":["XX"]}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The fraud settings, after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_fraud"},"example":{"object":"settings_fraud","url":"https://api.comecero.com/api/v1/settings/fraud","account_id":"AB1234","test":true,"date_created":"2026-01-12T09:30:00Z","date_modified":"2026-10-02T14:21:07Z","enable_fraud_screening":true,"max_score":0.6,"max_successful_payments":5,"max_failed_payments":3,"block_ip_country_mismatch":false,"blocked_countries":null,"step_up_enabled":null,"step_up_max_score":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/settings/fulfillment":{"get":{"operationId":"get_fulfillment_settings","summary":"Get fulfillment settings","description":"Returns whether payments are captured and items are fulfilled automatically, and after what delay. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_fulfillment`. Limited tokens may not.","tags":["settings"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The fulfillment settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_fulfillment"},"example":{"object":"settings_fulfillment","url":"https://api.comecero.com/api/v1/settings/fulfillment","account_id":"AB1234","test":true,"date_modified":"2026-10-02T14:21:07Z","auto_fulfill_items":false,"auto_fulfill_delay":0,"auto_capture":true,"auto_capture_delay":0,"low_inventory_notification":10}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"update_fulfillment_settings","summary":"Update fulfillment settings","description":"Changes the capture and fulfillment rules. Send only the fields you want to change. The change applies to payments and orders made after it. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_fulfillment`. Limited tokens may not.","tags":["settings"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_fulfillment_request"},"examples":{"fulfillment":{"summary":"Capture a day after the order","value":{"auto_capture":true,"auto_capture_delay":24}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The fulfillment settings, after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_fulfillment"},"example":{"object":"settings_fulfillment","url":"https://api.comecero.com/api/v1/settings/fulfillment","account_id":"AB1234","test":true,"date_modified":"2026-10-02T14:21:07Z","auto_fulfill_items":false,"auto_fulfill_delay":0,"auto_capture":true,"auto_capture_delay":0,"low_inventory_notification":10}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/settings/general":{"get":{"operationId":"get_general_settings","summary":"Get general settings","description":"Returns the reporting currencies, notification from addresses, document templates and custom invoice fields. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_general`. Limited tokens may not.","tags":["settings"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The general settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_general"},"example":{"object":"settings_general","url":"https://api.comecero.com/api/v1/settings/general","account_id":"AB1234","test":true,"date_modified":"2026-10-02T14:21:07Z","reporting_currency_primary":"USD","reporting_currency_secondary":"EUR","notification_from_addresses":["sales@example.com"],"cart_app_id":"comecero-shopping-cart","invoice_app_id":"comecero-shopping-cart","customer_admin_app_id":"comecero-customer-admin","order_pdf_template_id":null,"invoice_pdf_template_id":null,"invoice_custom_fields":[{"key":"po_number","label":"PO Number","required":false}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"update_general_settings","summary":"Update general settings","description":"Changes the general settings. Send only the fields you want to change. A new notification from address is sent a verification email. Reporting currencies cannot change once the account has a payment in this mode. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_general`. Limited tokens may not.","tags":["settings"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_general_request"},"examples":{"general":{"summary":"Sender addresses and an invoice field","value":{"notification_from_addresses":["sales@example.com"],"invoice_custom_fields":[{"label":"PO Number","required":false}]}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The general settings, after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_general"},"example":{"object":"settings_general","url":"https://api.comecero.com/api/v1/settings/general","account_id":"AB1234","test":true,"date_modified":"2026-10-02T14:21:07Z","reporting_currency_primary":"USD","reporting_currency_secondary":"EUR","notification_from_addresses":["sales@example.com"],"cart_app_id":"comecero-shopping-cart","invoice_app_id":"comecero-shopping-cart","customer_admin_app_id":"comecero-customer-admin","order_pdf_template_id":null,"invoice_pdf_template_id":null,"invoice_custom_fields":[{"key":"po_number","label":"PO Number","required":false}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/settings/payment":{"get":{"operationId":"get_payment_settings","summary":"Get payment settings","description":"Returns how the account takes payments: card statement text, saved cards, currencies, duplicate and country checks, and refund and chargeback reasons. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_payment`. Limited tokens may not.","tags":["settings"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The payment settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_payment"},"example":{"object":"settings_payment","url":"https://api.comecero.com/api/v1/settings/payment","account_id":"AB1234","test":true,"date_created":"2026-01-12T09:30:00Z","date_modified":"2026-10-02T14:21:07Z","merchant_descriptor_name":"EXAMPLE STORE","product_as_merchant_descriptor_name":true,"merchant_descriptor_contact":"8005551234","allow_save_cards":true,"save_cards_by_default":false,"ignore_bad_cvv":true,"ignore_bad_avs":true,"duplicate_payment_timeout":120,"default_payment_currency":"USD","default_settlement_currency":"USD","currency_settlement_rules":[],"customer_required_fields":["name","email","country"],"customer_optional_fields":["phone"],"refund_reasons":["Customer request","Duplicate order"],"chargeback_reasons":["Fraudulent Charge","Merchandise Not Received","Other"],"blocked_countries":[],"max_gateway_attempts":2}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"update_payment_settings","summary":"Update payment settings","description":"Changes the payment settings. Send only the fields you want to change. `allow_save_cards` is set by Comecero and ignored if you send it. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_payment`. Limited tokens may not.","tags":["settings"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_payment_request"},"examples":{"payment":{"summary":"Descriptor and required fields","value":{"merchant_descriptor_name":"EXAMPLE STORE","duplicate_payment_timeout":120,"customer_required_fields":["name","email","country"]}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The payment settings, after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_payment"},"example":{"object":"settings_payment","url":"https://api.comecero.com/api/v1/settings/payment","account_id":"AB1234","test":true,"date_created":"2026-01-12T09:30:00Z","date_modified":"2026-10-02T14:21:07Z","merchant_descriptor_name":"EXAMPLE STORE","product_as_merchant_descriptor_name":true,"merchant_descriptor_contact":"8005551234","allow_save_cards":true,"save_cards_by_default":false,"ignore_bad_cvv":true,"ignore_bad_avs":true,"duplicate_payment_timeout":120,"default_payment_currency":"USD","default_settlement_currency":"USD","currency_settlement_rules":[],"customer_required_fields":["name","email","country"],"customer_optional_fields":["phone"],"refund_reasons":["Customer request","Duplicate order"],"chargeback_reasons":["Fraudulent Charge","Merchandise Not Received","Other"],"blocked_countries":[],"max_gateway_attempts":2}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/settings/pricing":{"get":{"operationId":"get_pricing_settings","summary":"Get pricing settings","description":"Returns the exchange rate markups and rounding rules used when a price is converted into another currency. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_pricing`. Limited tokens may not.","tags":["settings"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The pricing settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_pricing"},"example":{"object":"settings_pricing","url":"https://api.comecero.com/api/v1/settings/pricing","account_id":"AB1234","test":true,"date_modified":"2026-10-02T14:21:07Z","currency_rounding_rules":[{"currency":null,"method":"highest","minimum":3,"positions":[0,0.25,0.5,0.75,0.95,0.99],"date_created":"2026-10-02T14:21:07Z"}],"currency_markup_rules":[{"currency":null,"markup_percentage":0.03,"date_created":"2026-10-02T14:21:07Z"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"update_pricing_settings","summary":"Update pricing settings","description":"Changes the markup and rounding rules. Each list you send replaces the saved list. New conversions use the new rules at once. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_pricing`. Limited tokens may not.","tags":["settings"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_pricing_request"},"examples":{"pricing":{"summary":"Currency markups","value":{"currency_markup_rules":[{"currency":null,"markup_percentage":0.03},{"currency":"JPY","markup_percentage":0.04}]}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The pricing settings, after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_pricing"},"example":{"object":"settings_pricing","url":"https://api.comecero.com/api/v1/settings/pricing","account_id":"AB1234","test":true,"date_modified":"2026-10-02T14:21:07Z","currency_rounding_rules":[{"currency":null,"method":"highest","minimum":3,"positions":[0,0.25,0.5,0.75,0.95,0.99],"date_created":"2026-10-02T14:21:07Z"}],"currency_markup_rules":[{"currency":null,"markup_percentage":0.03,"date_created":"2026-10-02T14:21:07Z"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/settings/shipping":{"get":{"operationId":"get_shipping_settings","summary":"Get shipping settings","description":"Returns the shipping settings with every shipping method. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_shipping`. Limited tokens may not.","tags":["settings"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The shipping settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_shipping"},"example":{"object":"settings_shipping","url":"https://api.comecero.com/api/v1/settings/shipping","account_id":"AB1234","test":true,"date_created":"2026-01-12T09:30:00Z","date_modified":"2026-10-02T14:21:07Z","methods":[{"object":"settings_shipping.method","url":"https://api.comecero.com/api/v1/settings/shipping/methods/standard-shipping-us","method_id":"standard-shipping-us","description":"Standard Shipping","details":null,"countries":["US"],"quantity_rules":null,"subtotal_rules":[{"currency":"USD","ranges":[{"minimum":0,"maximum":49.99,"price":5},{"minimum":50,"maximum":99.99,"price":10},{"minimum":100,"maximum":999999,"price":15}]}],"weight_rules":null,"adjustments":null}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"update_shipping_settings","summary":"Update shipping settings","description":"Replaces every shipping method at once. Each method gets a new `method_id`. To add, change or remove one method, use the shipping method endpoints. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_shipping`. Limited tokens may not.","tags":["settings"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_shipping_request"},"examples":{"shipping":{"summary":"One flat shipping method","value":{"methods":[{"description":"Standard Shipping","countries":["*"],"quantity_rules":[{"minimum":1,"maximum":999,"prices":[{"price":7.5,"currency":"USD"}]}]}]}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The shipping settings, after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_shipping"},"example":{"object":"settings_shipping","url":"https://api.comecero.com/api/v1/settings/shipping","account_id":"AB1234","test":true,"date_created":"2026-01-12T09:30:00Z","date_modified":"2026-10-02T14:21:07Z","methods":[{"object":"settings_shipping.method","url":"https://api.comecero.com/api/v1/settings/shipping/methods/standard-shipping-us","method_id":"standard-shipping-us","description":"Standard Shipping","details":null,"countries":["US"],"quantity_rules":null,"subtotal_rules":[{"currency":"USD","ranges":[{"minimum":0,"maximum":49.99,"price":5},{"minimum":50,"maximum":99.99,"price":10},{"minimum":100,"maximum":999999,"price":15}]}],"weight_rules":null,"adjustments":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/settings/shipping/methods":{"get":{"operationId":"list_settings_shipping_methods","summary":"List shipping methods in settings","description":"Lists the shipping methods in the shipping settings. The list is offset-based and returns every method unless you set `limit`. Filter by `country` to get the methods that ship there. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_shipping`. Limited tokens may not.","tags":["settings"],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/desc"},{"name":"sort_by","in":"query","description":"The field to sort by. Default `method_id`.","required":false,"schema":{"type":"string","enum":["method_id","date_created","date_modified"],"default":"method_id"}},{"name":"country","in":"query","description":"Only methods that ship to this two-letter ISO country code.","required":false,"schema":{"type":"string","minLength":2,"maxLength":2}},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"x-is-list":true,"description":"An offset-based list of shipping methods.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_shipping_method_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/settings/shipping/methods","data":[{"object":"settings_shipping.method","url":"https://api.comecero.com/api/v1/settings/shipping/methods/standard-shipping-us","method_id":"standard-shipping-us","description":"Standard Shipping","details":"Arrives in 3 to 5 business days.","countries":["US"],"quantity_rules":null,"subtotal_rules":[{"currency":"USD","ranges":[{"minimum":0,"maximum":49.99,"price":5},{"minimum":50,"maximum":999999,"price":0}]}],"weight_rules":null,"adjustments":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"create_settings_shipping_method","summary":"Create a shipping method in settings","description":"Adds a shipping method to the shipping settings. Comecero sets its `method_id` from the description and countries. Give exactly one set of rules: `quantity_rules`, `subtotal_rules` or `weight_rules`. Gaps between ranges are closed when saved. Carts and invoices are not priced from these settings: shoppers only see the methods made with `POST /shipping_methods`. Secret and trusted tokens may call it when their permissions allow updates to `settings_shipping`. Limited tokens may not.","tags":["settings"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_shipping_method_request"},"examples":{"method":{"summary":"Free shipping over 50 USD","value":{"description":"Standard Shipping","details":"Arrives in 3 to 5 business days.","countries":["US"],"subtotal_rules":[{"currency":"USD","ranges":[{"minimum":0,"maximum":49.99,"price":5},{"minimum":50,"maximum":999999,"price":0}]}]}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new shipping method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_shipping_method"},"example":{"object":"settings_shipping.method","url":"https://api.comecero.com/api/v1/settings/shipping/methods/standard-shipping-us","method_id":"standard-shipping-us","description":"Standard Shipping","details":"Arrives in 3 to 5 business days.","countries":["US"],"quantity_rules":null,"subtotal_rules":[{"currency":"USD","ranges":[{"minimum":0,"maximum":49.99,"price":5},{"minimum":50,"maximum":999999,"price":0}]}],"weight_rules":null,"adjustments":[{"country":"US","regions":["AK","HI"],"percentage":null,"amounts":[{"price":10,"currency":"USD"}]}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/settings/shipping/methods/{method_id}":{"parameters":[{"name":"method_id","in":"path","required":true,"description":"The shipping method ID.","schema":{"type":"string"}}],"get":{"operationId":"get_settings_shipping_method","summary":"Get a shipping method in settings","description":"Returns one shipping method from the shipping settings. Secret and trusted tokens may call it when their permissions include `settings_shipping`. Limited tokens may not.","tags":["settings"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The shipping method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_shipping_method"},"example":{"object":"settings_shipping.method","url":"https://api.comecero.com/api/v1/settings/shipping/methods/standard-shipping-us","method_id":"standard-shipping-us","description":"Standard Shipping","details":"Arrives in 3 to 5 business days.","countries":["US"],"quantity_rules":null,"subtotal_rules":[{"currency":"USD","ranges":[{"minimum":0,"maximum":49.99,"price":5},{"minimum":50,"maximum":999999,"price":0}]}],"weight_rules":null,"adjustments":[{"country":"US","regions":["AK","HI"],"percentage":null,"amounts":[{"price":10,"currency":"USD"}]}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"update_settings_shipping_method","summary":"Update a shipping method in settings","description":"Changes a shipping method. The body is checked as a whole method, so send `description`, `countries` and one set of rules every time, even if you change only one field. The `method_id` stays the same. Secret and trusted tokens may call it when their permissions allow updates to `settings_shipping`. Limited tokens may not.","tags":["settings"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_shipping_method_request"},"examples":{"method":{"summary":"Replace the method","value":{"description":"Standard Shipping","details":"Arrives in 3 to 5 business days.","countries":["US"],"subtotal_rules":[{"currency":"USD","ranges":[{"minimum":0,"maximum":49.99,"price":5},{"minimum":50,"maximum":999999,"price":0}]}]}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The shipping method, after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_shipping_method"},"example":{"object":"settings_shipping.method","url":"https://api.comecero.com/api/v1/settings/shipping/methods/standard-shipping-us","method_id":"standard-shipping-us","description":"Standard Shipping","details":"Arrives in 3 to 5 business days.","countries":["US"],"quantity_rules":null,"subtotal_rules":[{"currency":"USD","ranges":[{"minimum":0,"maximum":49.99,"price":5},{"minimum":50,"maximum":999999,"price":0}]}],"weight_rules":null,"adjustments":[{"country":"US","regions":["AK","HI"],"percentage":null,"amounts":[{"price":10,"currency":"USD"}]}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"operationId":"delete_settings_shipping_method","summary":"Delete a shipping method in settings","description":"Removes a shipping method from the shipping settings. This cannot be undone. It does not change the methods under `/shipping_methods`, which are the ones shoppers pick from. Secret and trusted tokens may call it when their permissions allow deletes on `settings_shipping`. Limited tokens may not.","tags":["settings"],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The shipping method was deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/settings/storefront":{"get":{"operationId":"get_storefront_settings","summary":"Get storefront settings","description":"Returns the hosted storefront's settings document, its switch, the shop's addresses and what the caller may change. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_storefront`. Limited tokens may not.","tags":["settings"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The storefront settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_storefront"},"example":{"object":"settings_storefront","url":"https://api.comecero.com/api/v1/settings/storefront","account_id":"AB1234","test":true,"date_created":"2026-09-28T10:02:44Z","date_modified":"2026-10-02T14:21:07Z","modified_by":"1000","enabled":true,"live":true,"managed":false,"date_enabled":"2026-10-02T14:21:07Z","can_switch":true,"can_edit_code":true,"has_settings":true,"settings":{"version":1,"brand":{"name":"Example Store","logo":"https://cdn.example.com/logo.png"},"theme":{"mode":"standard","primary":"#1F6FEB"},"source":{"kind":"storefront"}},"storefront_url":"https://example.apps.comecero.com","preview_url":"https://example.shop.comecero.com","hosts":["example.apps.comecero.com"],"platform_apps":[{"app_id":"comecero-shopping-cart","alias":"cart","name":"Shopping Cart","version":"3.1.60","key":"cart"}],"own_apps":[],"alias_conflicts":[]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"update_storefront_settings","summary":"Update storefront settings","description":"Changes the storefront document, its switch, or both. Groups you send are merged into the saved document. Custom CSS and JavaScript, and the switch, need a trusted token of the account owner. One change is saved at a time: if another is being saved, you get `409` and can try again. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_storefront`. Limited tokens may not.","tags":["settings"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_storefront_request"},"examples":{"storefront":{"summary":"Brand name and color","value":{"settings":{"brand":{"name":"Example Store"},"theme":{"primary":"#1F6FEB"}}}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The storefront settings, after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_storefront"},"example":{"object":"settings_storefront","url":"https://api.comecero.com/api/v1/settings/storefront","account_id":"AB1234","test":true,"date_created":"2026-09-28T10:02:44Z","date_modified":"2026-10-02T14:21:07Z","modified_by":"1000","enabled":true,"live":true,"managed":false,"date_enabled":"2026-10-02T14:21:07Z","can_switch":true,"can_edit_code":true,"has_settings":true,"settings":{"version":1,"brand":{"name":"Example Store","logo":"https://cdn.example.com/logo.png"},"theme":{"mode":"standard","primary":"#1F6FEB"},"source":{"kind":"storefront"}},"storefront_url":"https://example.apps.comecero.com","preview_url":"https://example.shop.comecero.com","hosts":["example.apps.comecero.com"],"platform_apps":[{"app_id":"comecero-shopping-cart","alias":"cart","name":"Shopping Cart","version":"3.1.60","key":"cart"}],"own_apps":[],"alias_conflicts":[]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/settings/subscription":{"get":{"operationId":"get_subscription_settings","summary":"Get subscription settings","description":"Returns how subscriptions renew: reminders, payment retries, what customers may change themselves, and renewal emails. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_subscription`. Limited tokens may not.","tags":["settings"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The subscription settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_subscription"},"example":{"object":"settings_subscription","url":"https://api.comecero.com/api/v1/settings/subscription","account_id":"AB1234","test":true,"date_modified":"2026-10-02T14:21:07Z","copy_affiliate_id_on_subscription_renewal":false,"subscription_renewal_notification_days":3,"subscription_invoice_payment_delay":0,"payment_retry_delay":3,"allow_deep_payment_retries":true,"max_payment_attempts":4,"payment_retry_friday_bias":true,"allow_customer_subscription_cancel":true,"allow_customer_subscription_downgrade":true,"allow_customer_subscription_upgrade":true,"use_customer_payment_currency":false,"cancel_on_chargeback":true,"receipt_on_renewal":true,"digital_delivery_on_renewal":true,"cancellation_reasons":["Too expensive","No longer needed"],"immediate_upgrade_product_types":["digital","service"],"immediate_downgrade_product_types":[]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"update_subscription_settings","summary":"Update subscription settings","description":"Changes the subscription settings. Send only the fields you want to change. Renewals after the change follow the new rules. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_subscription`. Limited tokens may not.","tags":["settings"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_subscription_request"},"examples":{"subscription":{"summary":"Retry failed renewals","value":{"payment_retry_delay":2,"max_payment_attempts":5}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The subscription settings, after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_subscription"},"example":{"object":"settings_subscription","url":"https://api.comecero.com/api/v1/settings/subscription","account_id":"AB1234","test":true,"date_modified":"2026-10-02T14:21:07Z","copy_affiliate_id_on_subscription_renewal":false,"subscription_renewal_notification_days":3,"subscription_invoice_payment_delay":0,"payment_retry_delay":3,"allow_deep_payment_retries":true,"max_payment_attempts":4,"payment_retry_friday_bias":true,"allow_customer_subscription_cancel":true,"allow_customer_subscription_downgrade":true,"allow_customer_subscription_upgrade":true,"use_customer_payment_currency":false,"cancel_on_chargeback":true,"receipt_on_renewal":true,"digital_delivery_on_renewal":true,"cancellation_reasons":["Too expensive","No longer needed"],"immediate_upgrade_product_types":["digital","service"],"immediate_downgrade_product_types":[]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/settings/tax":{"get":{"operationId":"get_tax_settings","summary":"Get tax settings","description":"Returns the tax inclusive countries, gross discount countries and your own tax rules. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_tax`. Limited tokens may not.","tags":["settings"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The tax settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_tax"},"example":{"object":"settings_tax","url":"https://api.comecero.com/api/v1/settings/tax","account_id":"AB1234","test":true,"date_modified":"2026-10-02T14:21:07Z","tax_inclusive_countries":["EU"],"gross_discount_countries":[],"rules":[{"country":"US","state_prov":"WA","location_postal_code":null,"rate":null,"tax_code":null},{"country":"AU","state_prov":null,"location_postal_code":null,"rate":0.1,"tax_code":null}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"update_tax_settings","summary":"Update tax settings","description":"Changes the tax settings. Each list you send replaces the saved list. On accounts where Comecero is the seller, `rules` is ignored because Comecero handles the tax. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_tax`. Limited tokens may not.","tags":["settings"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_tax_request"},"examples":{"tax":{"summary":"Prices include tax in the EU and UK","value":{"tax_inclusive_countries":["EU","GB"]}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The tax settings, after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_tax"},"example":{"object":"settings_tax","url":"https://api.comecero.com/api/v1/settings/tax","account_id":"AB1234","test":true,"date_modified":"2026-10-02T14:21:07Z","tax_inclusive_countries":["EU"],"gross_discount_countries":[],"rules":[{"country":"US","state_prov":"WA","location_postal_code":null,"rate":null,"tax_code":null},{"country":"AU","state_prov":null,"location_postal_code":null,"rate":0.1,"tax_code":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/settings/technical":{"get":{"operationId":"get_technical_settings","summary":"Get technical settings","description":"Returns the time zone, shop host names, app alias redirects, the signing key for webhooks, OAuth redirect addresses and CORS origins. The response holds your signing key: call it from your server only. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_technical`. Limited tokens may not.","tags":["settings"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The technical settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_technical"},"example":{"object":"settings_technical","url":"https://api.comecero.com/api/v1/settings/technical","account_id":"AB1234","test":true,"date_modified":"2026-10-02T14:21:07Z","timezone":"America/New_York","app_hosts":["example.apps.comecero.com"],"app_alias_redirects":null,"signature_key":"7f3K9pQx2LmN8vB4","oauth_redirect_uris":["https://www.example.com/oauth/callback"],"cors_allowed_origins":["https://www.example.com"],"allow_public_limited_test_tokens":false}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"update_technical_settings","summary":"Update technical settings","description":"Changes the technical settings. Send only the fields you want to change. Changing `app_hosts` changes where your shop answers. Settings are kept per mode: a test token works on the test settings, a live token on the live ones. Secret and trusted tokens may call it when their permissions include `settings_technical`. Limited tokens may not.","tags":["settings"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_technical_request"},"examples":{"technical":{"summary":"Allow your own sites","value":{"cors_allowed_origins":["https://www.example.com","https://shop.example.com"]}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The technical settings, after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/settings_technical"},"example":{"object":"settings_technical","url":"https://api.comecero.com/api/v1/settings/technical","account_id":"AB1234","test":true,"date_modified":"2026-10-02T14:21:07Z","timezone":"America/New_York","app_hosts":["example.apps.comecero.com"],"app_alias_redirects":null,"signature_key":"7f3K9pQx2LmN8vB4","oauth_redirect_uris":["https://www.example.com/oauth/callback"],"cors_allowed_origins":["https://www.example.com"],"allow_public_limited_test_tokens":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/shipments":{"get":{"operationId":"list_shipments","summary":"List shipments","description":"Lists the shipments on your account, oldest first unless you send `desc=true`. To create one, use `POST /orders/{order_id}/shipments`.\n\nThe list is cursor-based: use `after_item` and `before_item` (or the `next_page_url` and `previous_page_url` in the response). It is ordered by the date named in `date_type`: `date_created` (default) or `date_modified`. `sort_by` is ignored.\n\nNeeds a secret or trusted token. Limited tokens get `403`.","tags":["shipments"],"parameters":[{"name":"q","in":"query","description":"Search by exact shipment id.","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/date_start"},{"$ref":"#/components/parameters/date_end"},{"$ref":"#/components/parameters/date_type"},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/after_item"},{"$ref":"#/components/parameters/before_item"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A cursor-based page of shipments.","content":{"application/json":{"schema":{"title":"shipment_cursor_list","allOf":[{"$ref":"#/components/schemas/list_cursor"},{"type":"object","properties":{"data":{"type":"array","description":"The shipments on this page.","items":{"$ref":"#/components/schemas/shipment"}}}}]},"example":{"next_page_url":"https://api.comecero.com/api/v1/shipments?after_item=0093718200417ShQ2xN8kL","next_page_after_item":"0093718200417ShQ2xN8kL","previous_page_url":null,"previous_page_before_item":null,"current_page_url":"https://api.comecero.com/api/v1/shipments","data":[{"object":"shipment","url":"https://api.comecero.com/api/v1/shipments/0093718200417ShQ2xN8kL","shipment_id":"0093718200417ShQ2xN8kL","date_created":"2026-11-04T09:30:00Z","date_modified":"2026-11-04T09:30:00Z","date_shipped":"2026-11-04T09:30:00Z","test":true,"account_id":"AB1234","items":[{"object":"shipment_item","item_id":"1","product_id":"lens-cloth.test","name":"Lens cleaning cloth","quantity":2,"product":"https://api.comecero.com/api/v1/products/lens-cloth.test"}],"order":"https://api.comecero.com/api/v1/orders/2979-KXVST-674","courier":"UPS","tracking_number":"1Z999AA10123456784","tracking_url":"http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784","notifications":"https://api.comecero.com/api/v1/shipments/0093718200417ShQ2xN8kL/notifications","meta":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/shipments/{shipment_id}":{"get":{"operationId":"get_shipment","summary":"Get a shipment","description":"Returns one shipment.\n\nSecret and trusted tokens can read any shipment on the account. A limited token can read a shipment only when it is bound to it, and `meta` is left out for it.","tags":["shipments"],"x-limited":true,"parameters":[{"name":"shipment_id","in":"path","description":"The shipment id.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/timezone"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The shipment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/shipment"},"example":{"object":"shipment","url":"https://api.comecero.com/api/v1/shipments/0093718200417ShQ2xN8kL","shipment_id":"0093718200417ShQ2xN8kL","date_created":"2026-11-04T09:30:00Z","date_modified":"2026-11-04T09:30:00Z","date_shipped":"2026-11-04T09:30:00Z","test":true,"account_id":"AB1234","items":[{"object":"shipment_item","item_id":"1","product_id":"lens-cloth.test","name":"Lens cleaning cloth","quantity":2,"product":"https://api.comecero.com/api/v1/products/lens-cloth.test"}],"order":"https://api.comecero.com/api/v1/orders/2979-KXVST-674","courier":"UPS","tracking_number":"1Z999AA10123456784","tracking_url":"http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784","notifications":"https://api.comecero.com/api/v1/shipments/0093718200417ShQ2xN8kL/notifications","meta":null}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"update_shipment","summary":"Update a shipment","description":"Changes the date shipped, carrier, tracking number, tracking URL or `meta` of a shipment. The items cannot be changed. The `shipment:modified` event fires. The customer is not emailed again.\n\nNeeds a secret or trusted token. Limited tokens get `403`.","tags":["shipments"],"parameters":[{"name":"shipment_id","in":"path","description":"The shipment id.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/shipment_update_request"},"examples":{"tracking":{"summary":"Fix the tracking number","value":{"tracking_number":"1Z999AA10123456799"}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The updated shipment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/shipment"},"example":{"object":"shipment","url":"https://api.comecero.com/api/v1/shipments/0093718200417ShQ2xN8kL","shipment_id":"0093718200417ShQ2xN8kL","date_created":"2026-11-04T09:30:00Z","date_modified":"2026-11-04T09:30:00Z","date_shipped":"2026-11-04T09:30:00Z","test":true,"account_id":"AB1234","items":[{"object":"shipment_item","item_id":"1","product_id":"lens-cloth.test","name":"Lens cleaning cloth","quantity":2,"product":"https://api.comecero.com/api/v1/products/lens-cloth.test"}],"order":"https://api.comecero.com/api/v1/orders/2979-KXVST-674","courier":"UPS","tracking_number":"1Z999AA10123456784","tracking_url":"http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784","notifications":"https://api.comecero.com/api/v1/shipments/0093718200417ShQ2xN8kL/notifications","meta":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"operationId":"delete_shipment","summary":"Delete a shipment","description":"Deletes a shipment, for example one entered by mistake. Order items that no longer have all their units shipped are marked not fulfilled again, and so is the order. A payment already captured stays captured. The `shipment:deleted` event fires.\n\nNeeds a secret or trusted token. Limited tokens get `403`.","tags":["shipments"],"parameters":[{"name":"shipment_id","in":"path","description":"The shipment id.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The shipment was deleted. No body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/shipments/{shipment_id}/notifications":{"get":{"operationId":"list_shipment_notifications","summary":"List a shipment's notifications","description":"Lists the emails sent to the customer about this shipment, such as the shipment confirmation. Offset-based (`offset`, `limit`). `sort_by` takes `date_created` (default) or `date_modified`.\n\nA limited token may call this for a shipment it is bound to.","tags":["shipments"],"x-limited":true,"parameters":[{"name":"shipment_id","in":"path","description":"The shipment id.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/desc"},{"name":"sort_by","in":"query","description":"The field to sort by.","required":false,"schema":{"type":"string","default":"date_created","enum":["date_created","date_modified"]}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"An offset-based page of notifications.","content":{"application/json":{"schema":{"title":"notification_offset_list","allOf":[{"$ref":"#/components/schemas/list_offset"},{"type":"object","properties":{"data":{"type":"array","description":"The notifications on this page.","items":{"$ref":"#/components/schemas/notification"}}}}]},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/shipments/0093718200417ShQ2xN8kL/notifications","data":[{"object":"notification","url":"https://api.comecero.com/api/v1/notifications/0093718200601NtB3jQ5wE","notification_id":"0093718200601NtB3jQ5wE","test":true,"account_id":"AB1234","type":"shipment:confirmation","method":"email","from":"notification@comecero.com","from_name":"Example Shop","reply_to":"support@example.com","bcc":null,"destination":"john@example.com","subject":"Your order has shipped","customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","status":"delivered","date_created":"2026-11-03T10:12:45Z","date_modified":"2026-11-03T10:12:47Z"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/shipping_methods":{"get":{"summary":"List shipping methods","operationId":"list_shipping_methods","description":"Returns your shipping methods, oldest first unless you choose another `sort_by`. Unlike other lists, all of them come back on one page unless you send `limit`. Secret and trusted tokens may call it. The same methods are also at `/settings/shipping/methods`.","tags":["shipping_methods"],"parameters":[{"$ref":"#/components/parameters/offset"},{"name":"limit","in":"query","description":"How many methods to return, from 1 to 100. When left out, all are returned.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"sort_by","in":"query","description":"The field to sort by. The default is `date_created`.","schema":{"type":"string","enum":["date_created","date_modified","shipping_method_id","description"]}},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"},{"name":"q","in":"query","description":"Search text. An exact shipping method id returns that method; otherwise methods whose description contains the text (any case) are returned.","schema":{"type":"string"}},{"name":"country","in":"query","description":"A two-letter ISO country code. Only methods that list this country are returned. Methods set to every country (`*`) are left out by this filter.","schema":{"type":"string"}}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of shipping methods.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/shipping_method_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/shipping_methods","data":[{"object":"shipping_method","url":"https://api.comecero.com/api/v1/shipping_methods/Standard-Shipping","shipping_method_id":"Standard-Shipping","test":true,"account_id":"AB1234","date_created":"2026-11-02T20:13:16Z","date_modified":"2026-11-02T20:13:16Z","description":"Standard Shipping","details":null,"countries":["US"],"quantity_config":null,"subtotal_config":{"percent_of_subtotal":null,"rules":[{"currency":"USD","ranges":[{"minimum":0,"maximum":49.99,"price":5}]}]},"weight_config":null,"adjustments":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Create a shipping method","operationId":"create_shipping_method","description":"Adds a shipping method. Its id is made from the description, so you cannot choose it. Weight rules are stored in grams. The token needs the update permission on shipping methods, not the create permission. Secret and trusted tokens may call it.","tags":["shipping_methods"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"description":"The new shipping method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/shipping_method_request"},"examples":{"method":{"summary":"Free shipping over 50 USD","value":{"description":"Standard Shipping","details":"Arrives in 3 to 5 business days.","countries":["US"],"subtotal_config":{"rules":[{"currency":"USD","ranges":[{"minimum":0,"maximum":49.99,"price":5},{"minimum":50,"maximum":999999,"price":0}]}]}}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new shipping method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/shipping_method"},"example":{"object":"shipping_method","url":"https://api.comecero.com/api/v1/shipping_methods/Standard-Shipping","shipping_method_id":"Standard-Shipping","test":true,"account_id":"AB1234","date_created":"2026-11-02T20:13:16Z","date_modified":"2026-11-02T20:13:16Z","description":"Standard Shipping","details":"Arrives in 3 to 5 business days.","countries":["US"],"quantity_config":null,"subtotal_config":{"percent_of_subtotal":null,"rules":[{"currency":"USD","ranges":[{"minimum":0,"maximum":49.99,"price":5},{"minimum":50,"maximum":999999,"price":0}]}]},"weight_config":null,"adjustments":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/shipping_methods/{shipping_method_id}":{"get":{"summary":"Get a shipping method","operationId":"get_shipping_method","description":"Returns one shipping method. An id that does not exist does not return `404`: it returns `200` with an empty object whose `shipping_method_id` is null, so check that field. Secret and trusted tokens may call it.","tags":["shipping_methods"],"parameters":[{"name":"shipping_method_id","in":"path","required":true,"description":"The shipping method id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The shipping method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/shipping_method"},"example":{"object":"shipping_method","url":"https://api.comecero.com/api/v1/shipping_methods/Standard-Shipping","shipping_method_id":"Standard-Shipping","test":true,"account_id":"AB1234","date_created":"2026-11-02T20:13:16Z","date_modified":"2026-11-02T20:13:16Z","description":"Standard Shipping","details":"Arrives in 3 to 5 business days.","countries":["US"],"quantity_config":null,"subtotal_config":{"percent_of_subtotal":null,"rules":[{"currency":"USD","ranges":[{"minimum":0,"maximum":49.99,"price":5},{"minimum":50,"maximum":999999,"price":0}]}]},"weight_config":null,"adjustments":null}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Update a shipping method","operationId":"update_shipping_method","description":"Changes a shipping method. Only the fields you send are changed, but the request is checked as a whole method: it must hold `description`, `countries` and exactly one of the three configs, even when you change only one of them. The id does not change. Secret and trusted tokens may call it.","tags":["shipping_methods"],"parameters":[{"name":"shipping_method_id","in":"path","required":true,"description":"The shipping method id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"description":"The shipping method, with the fields to change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/shipping_method_request"},"examples":{"method":{"summary":"Replace the method","value":{"description":"Standard Shipping","details":"Arrives in 3 to 5 business days.","countries":["US"],"subtotal_config":{"rules":[{"currency":"USD","ranges":[{"minimum":0,"maximum":49.99,"price":5},{"minimum":50,"maximum":999999,"price":0}]}]}}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The updated shipping method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/shipping_method"},"example":{"object":"shipping_method","url":"https://api.comecero.com/api/v1/shipping_methods/Standard-Shipping","shipping_method_id":"Standard-Shipping","test":true,"account_id":"AB1234","date_created":"2026-11-02T20:13:16Z","date_modified":"2026-11-02T20:13:16Z","description":"Standard Shipping","details":"Arrives in 3 to 5 business days.","countries":["US"],"quantity_config":null,"subtotal_config":{"percent_of_subtotal":null,"rules":[{"currency":"USD","ranges":[{"minimum":0,"maximum":49.99,"price":5},{"minimum":50,"maximum":999999,"price":0}]}]},"weight_config":null,"adjustments":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"summary":"Delete a shipping method","operationId":"delete_shipping_method","description":"Removes a shipping method for good. Shoppers can no longer pick it. Secret and trusted tokens may call it.","tags":["shipping_methods"],"parameters":[{"name":"shipping_method_id","in":"path","required":true,"description":"The shipping method id.","schema":{"type":"string"}}],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The shipping method is deleted. No body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/subscription_plans":{"get":{"operationId":"list_subscription_plans","summary":"List subscription plans","description":"Lists the subscription plans in your account. Deleted plans are not listed. The list is offset-based. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["subscription_plans"],"parameters":[{"name":"q","in":"query","required":false,"description":"Search by exact plan id, or by part of the plan name (not case sensitive).","schema":{"type":"string"}},{"name":"sort_by","in":"query","required":false,"description":"The field to sort by.","schema":{"type":"string","enum":["date_created","date_modified","name"],"default":"date_created"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of subscription plans.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_plan_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/subscription_plans","data":[{"object":"subscription_plan","url":"https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C","subscription_plan_id":"0093472113202Spzs4AV8C","date_created":"2026-09-18T20:28:33Z","date_modified":"2026-09-18T20:28:33Z","test":true,"account_id":"AB1234","name":"Monthly, 14-day trial","description":null,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","end_at_billing_count":null,"trial_interval":14,"trial_interval_unit":"day","trial_interval_description":"14 days","deleted":false,"date_deleted":null,"meta":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"create_subscription_plan","summary":"Create a subscription plan","description":"Creates a subscription plan. Link it to a product (the product's `subscription_plan_id`) to sell that product as a subscription. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["subscription_plans"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_plan_request"},"examples":{"trial":{"summary":"Monthly with a free trial","value":{"name":"Monthly, 14-day trial","billing_interval":1,"billing_interval_unit":"month","trial_interval":14,"trial_interval_unit":"day"}},"yearly":{"summary":"Yearly, no trial","value":{"name":"Yearly","billing_interval":1,"billing_interval_unit":"year"}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_plan"},"example":{"object":"subscription_plan","url":"https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C","subscription_plan_id":"0093472113202Spzs4AV8C","date_created":"2026-09-18T20:28:33Z","date_modified":"2026-09-18T20:28:33Z","test":true,"account_id":"AB1234","name":"Monthly, 14-day trial","description":null,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","end_at_billing_count":null,"trial_interval":14,"trial_interval_unit":"day","trial_interval_description":"14 days","deleted":false,"date_deleted":null,"meta":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/subscription_plans/{subscription_plan_id}":{"parameters":[{"name":"subscription_plan_id","in":"path","required":true,"description":"The subscription plan id.","schema":{"type":"string"}}],"get":{"operationId":"get_subscription_plan","summary":"Get a subscription plan","description":"Returns one subscription plan. Secret, trusted and limited tokens may call it. A limited token gets the billing fields only: `name`, `description`, `deleted`, `date_deleted` and `meta` are left out.","tags":["subscription_plans"],"x-limited":true,"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_plan"},"example":{"object":"subscription_plan","url":"https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C","subscription_plan_id":"0093472113202Spzs4AV8C","date_created":"2026-09-18T20:28:33Z","date_modified":"2026-09-18T20:28:33Z","test":true,"account_id":"AB1234","name":"Monthly, 14-day trial","description":null,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","end_at_billing_count":null,"trial_interval":14,"trial_interval_unit":"day","trial_interval_description":"14 days","deleted":false,"date_deleted":null,"meta":null}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"update_subscription_plan","summary":"Update a subscription plan","description":"Changes a subscription plan. Only new subscriptions use the new values; existing subscriptions keep what they copied when they were made. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["subscription_plans"],"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_plan_update_request"},"examples":{"trial":{"summary":"Longer trial","value":{"name":"Monthly, 30-day trial","trial_interval":30}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The updated plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_plan"},"example":{"object":"subscription_plan","url":"https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C","subscription_plan_id":"0093472113202Spzs4AV8C","date_created":"2026-09-18T20:28:33Z","date_modified":"2026-09-18T20:28:33Z","test":true,"account_id":"AB1234","name":"Monthly, 14-day trial","description":null,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","end_at_billing_count":null,"trial_interval":14,"trial_interval_unit":"day","trial_interval_description":"14 days","deleted":false,"date_deleted":null,"meta":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"operationId":"delete_subscription_plan","summary":"Delete a subscription plan","description":"Retires a subscription plan: it is marked `deleted` and leaves the plan list, but you can still get it by id. Subscriptions already on the plan keep billing as before. Core does not check whether products still use the plan, so move those products first. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["subscription_plans"],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The plan was deleted. No body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/subscriptions":{"get":{"operationId":"list_subscriptions","summary":"List subscriptions","description":"Lists the subscriptions in your account, oldest first by `date_type` (default `date_created`). The list is cursor-based: use `next_page_url` or `after_item` to page forward. Secret and trusted tokens may call it. A limited token may not (`403`); a signed-in customer reads their own with `GET /customers/{customer_id}/subscriptions`.","tags":["subscriptions"],"parameters":[{"name":"status","in":"query","description":"Only subscriptions with this status. Cannot be sent with `terminated`.","required":false,"schema":{"type":"string","enum":["trial","active","cancelled","completed"]}},{"name":"terminated","in":"query","description":"`true` returns `cancelled` and `completed` subscriptions, `false` returns `trial` and `active` ones. Cannot be sent with `status`.","required":false,"schema":{"type":"boolean"}},{"name":"in_grace_period","in":"query","description":"Only subscriptions that are, or are not, in the grace period after a failed renewal.","required":false,"schema":{"type":"boolean"}},{"name":"q","in":"query","description":"Search by exact subscription id, exact customer email, or part of the customer name or company name.","required":false,"schema":{"type":"string"}},{"name":"date_type","in":"query","description":"Which date `date_start` and `date_end` filter on, and the list is sorted by. `date_current_period_start` and `date_current_period_end` cannot be used with `status=cancelled`, `status=completed` or `terminated=true`.","required":false,"schema":{"type":"string","enum":["date_created","date_modified","date_current_period_start","date_current_period_end"],"default":"date_created"}},{"$ref":"#/components/parameters/date_start"},{"$ref":"#/components/parameters/date_end"},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/after_item"},{"$ref":"#/components/parameters/before_item"},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of subscriptions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_list"},"example":{"next_page_url":"https://api.comecero.com/api/v1/subscriptions?after_item=0093799318129SuLByRPW8&status=active","next_page_after_item":"0093799318129SuLByRPW8","previous_page_url":null,"previous_page_before_item":null,"current_page_url":"https://api.comecero.com/api/v1/subscriptions?status=active&limit=1","data":[{"object":"subscription","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_id":"0093799318129SuLByRPW8","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-11-02T15:21:31Z","test":true,"account_id":"AB1234","status":"active","in_grace_period":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"billing_count":2,"end_at_billing_count":null,"currency":"USD","items":[{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}],"shipping_method_id":null,"date_trial_start":null,"date_trial_end":null,"date_current_period_start":"2026-11-02T15:21:28Z","date_current_period_end":"2026-12-02T15:21:28Z","date_next_renewal_notification":"2026-11-29T15:21:28Z","date_cancelled":null,"cancellation_reason":null,"cancel_at_current_period_end":false,"date_ended":null,"add_at_current_period_end":[],"subscription_plan":"https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C","customer":"https://api.comecero.com/api/v1/customers/0093799288003CuGOip8X9","invoices":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/invoices","history":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/history","meta":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/subscriptions/options":{"get":{"operationId":"get_subscription_options","summary":"Get subscription options","description":"Returns choices for managing subscriptions, such as the cancellation reasons set in your subscription settings. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["subscriptions"],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The subscription options.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_options"},"example":{"account_id":"AB1234","test":true,"cancellation_reasons":["Too expensive","No longer needed","Switching to another product"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/subscriptions/{subscription_id}":{"parameters":[{"name":"subscription_id","in":"path","required":true,"description":"The subscription id.","schema":{"type":"string"}}],"get":{"operationId":"get_subscription","summary":"Get a subscription","description":"Returns one subscription with its items. Secret and trusted tokens may call it. A limited token may read a subscription of the customer it is signed in as; some fields are then left out (see the object).","tags":["subscriptions"],"x-limited":true,"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription"},"example":{"object":"subscription","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_id":"0093799318129SuLByRPW8","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-11-02T15:21:31Z","test":true,"account_id":"AB1234","status":"active","in_grace_period":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"billing_count":2,"end_at_billing_count":null,"currency":"USD","items":[{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}],"shipping_method_id":null,"date_trial_start":null,"date_trial_end":null,"date_current_period_start":"2026-11-02T15:21:28Z","date_current_period_end":"2026-12-02T15:21:28Z","date_next_renewal_notification":"2026-11-29T15:21:28Z","date_cancelled":null,"cancellation_reason":null,"cancel_at_current_period_end":false,"date_ended":null,"add_at_current_period_end":[],"subscription_plan":"https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C","customer":"https://api.comecero.com/api/v1/customers/0093799288003CuGOip8X9","invoices":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/invoices","history":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/history","meta":null}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"update_subscription","summary":"Update a subscription","description":"Changes a subscription's cancellation state, cancellation reason or `meta`. Other fields, such as `currency`, are not changed by this endpoint. Setting `status` to `cancelled` cancels at once: open invoices are closed, the `subscription:cancelled` event fires and the customer is emailed. Setting `cancel_at_current_period_end` to `true` schedules the cancellation and emails the customer. Secret and trusted tokens may call it; a limited token may not (`403`), it uses the cancel and uncancel endpoints instead.","tags":["subscriptions"],"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_update_request"},"examples":{"cancel_later":{"summary":"Cancel at the end of the period","value":{"cancel_at_current_period_end":true,"cancellation_reason":"No longer needed"}},"change_plan":{"summary":"Move to another plan","value":{"subscription_plan_id":"0093472113202Spzs4AV8C"}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The updated subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription"},"example":{"object":"subscription","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_id":"0093799318129SuLByRPW8","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-11-02T15:21:31Z","test":true,"account_id":"AB1234","status":"active","in_grace_period":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"billing_count":2,"end_at_billing_count":null,"currency":"USD","items":[{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}],"shipping_method_id":null,"date_trial_start":null,"date_trial_end":null,"date_current_period_start":"2026-11-02T15:21:28Z","date_current_period_end":"2026-12-02T15:21:28Z","date_next_renewal_notification":"2026-11-29T15:21:28Z","date_cancelled":null,"cancellation_reason":null,"cancel_at_current_period_end":false,"date_ended":null,"add_at_current_period_end":[],"subscription_plan":"https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C","customer":"https://api.comecero.com/api/v1/customers/0093799288003CuGOip8X9","invoices":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/invoices","history":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/history","meta":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/subscriptions/{subscription_id}/add_at_current_period_end":{"parameters":[{"name":"subscription_id","in":"path","required":true,"description":"The subscription id.","schema":{"type":"string"}}],"delete":{"operationId":"delete_subscription_scheduled_additions","summary":"Remove scheduled item additions","description":"Removes every item that was scheduled to be added at the end of the current billing period (`add_at_current_period_end`). Nothing is charged or refunded. Returns the subscription, not an empty body. Secret, trusted and limited tokens may call it; a limited token only for the customer it is signed in as.","tags":["subscriptions"],"x-limited":true,"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The subscription after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription"},"example":{"object":"subscription","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_id":"0093799318129SuLByRPW8","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-11-02T15:21:31Z","test":true,"account_id":"AB1234","status":"active","in_grace_period":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"billing_count":2,"end_at_billing_count":null,"currency":"USD","items":[{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}],"shipping_method_id":null,"date_trial_start":null,"date_trial_end":null,"date_current_period_start":"2026-11-02T15:21:28Z","date_current_period_end":"2026-12-02T15:21:28Z","date_next_renewal_notification":"2026-11-29T15:21:28Z","date_cancelled":null,"cancellation_reason":null,"cancel_at_current_period_end":false,"date_ended":null,"add_at_current_period_end":[],"subscription_plan":"https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C","customer":"https://api.comecero.com/api/v1/customers/0093799288003CuGOip8X9","invoices":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/invoices","history":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/history","meta":null}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"The subscription is cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/subscriptions/{subscription_id}/cancel":{"parameters":[{"name":"subscription_id","in":"path","required":true,"description":"The subscription id.","schema":{"type":"string"}}],"post":{"operationId":"cancel_subscription","summary":"Cancel a subscription","description":"Cancels a subscription. By default (or with no body) the cancellation is scheduled: the subscription and its items keep billing until the end of the current period, then end, and the `subscription:cancellation_scheduled` event fires now. With `cancel_at_current_period_end: false` it is cancelled at once: every item is cancelled, open invoices are closed, no further renewals are billed, the `subscription:cancelled` event fires and the customer is emailed a cancellation notice. No refund is made. Secret, trusted and limited tokens may call it. A limited token may only cancel a subscription of the customer it is signed in as, and only when your subscription settings allow customers to cancel (otherwise `403`).","tags":["subscriptions"],"x-limited":true,"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_cancel_request"},"examples":{"at_period_end":{"summary":"Cancel at the end of the period","value":{"cancel_at_current_period_end":true,"cancellation_reason":"No longer needed"}},"now":{"summary":"Cancel now","value":{"cancel_at_current_period_end":false,"cancellation_reason":"Too expensive"}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The subscription after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription"},"example":{"object":"subscription","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_id":"0093799318129SuLByRPW8","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-11-02T15:21:31Z","test":true,"account_id":"AB1234","status":"active","in_grace_period":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"billing_count":2,"end_at_billing_count":null,"currency":"USD","items":[{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}],"shipping_method_id":null,"date_trial_start":null,"date_trial_end":null,"date_current_period_start":"2026-11-02T15:21:28Z","date_current_period_end":"2026-12-02T15:21:28Z","date_next_renewal_notification":"2026-11-29T15:21:28Z","date_cancelled":null,"cancellation_reason":null,"cancel_at_current_period_end":false,"date_ended":null,"add_at_current_period_end":[],"subscription_plan":"https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C","customer":"https://api.comecero.com/api/v1/customers/0093799288003CuGOip8X9","invoices":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/invoices","history":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/history","meta":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"The subscription is already cancelled or completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/subscriptions/{subscription_id}/extend":{"parameters":[{"name":"subscription_id","in":"path","required":true,"description":"The subscription id.","schema":{"type":"string"}}],"post":{"operationId":"extend_subscription","summary":"Extend a subscription period","description":"Pushes back the next billing without charging. During a trial the trial end moves; otherwise the end of the current billing period moves. Use it to give a customer free time. The subscription must be `active` or `trial`, and the extension cannot be more than one year past the current end. The change is logged in the subscription history. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["subscriptions"],"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_extend_request"},"examples":{"week":{"summary":"Add seven days","value":{"interval":7,"interval_unit":"day"}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The subscription after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription"},"example":{"object":"subscription","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_id":"0093799318129SuLByRPW8","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-11-02T15:21:31Z","test":true,"account_id":"AB1234","status":"active","in_grace_period":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"billing_count":2,"end_at_billing_count":null,"currency":"USD","items":[{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}],"shipping_method_id":null,"date_trial_start":null,"date_trial_end":null,"date_current_period_start":"2026-11-02T15:21:28Z","date_current_period_end":"2026-12-02T15:21:28Z","date_next_renewal_notification":"2026-11-29T15:21:28Z","date_cancelled":null,"cancellation_reason":null,"cancel_at_current_period_end":false,"date_ended":null,"add_at_current_period_end":[],"subscription_plan":"https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C","customer":"https://api.comecero.com/api/v1/customers/0093799288003CuGOip8X9","invoices":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/invoices","history":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/history","meta":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/subscriptions/{subscription_id}/fast_forward":{"parameters":[{"name":"subscription_id","in":"path","required":true,"description":"The subscription id.","schema":{"type":"string"}}],"post":{"operationId":"fast_forward_subscription","summary":"Fast forward a test subscription","description":"For testing renewals. Moves the end of the current billing period (and of the trial, if any) to `seconds_from_end` seconds from now. When that time comes, the renewal runs as normal: an invoice is made and the customer's saved payment method is charged (in test mode), and renewal emails and events go out. Only works with a test token on a test subscription that is `active` or `trial`, and not when the period already ends sooner. Secret and trusted tokens may call it; a limited token may not (`403`). No body.","tags":["subscriptions"],"parameters":[{"name":"seconds_from_end","in":"query","required":false,"description":"How many seconds from now the current period should end. Default `0` (now). Maximum `86400` (one day).","schema":{"type":"integer","default":0,"maximum":86400}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The subscription after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription"},"example":{"object":"subscription","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_id":"0093799318129SuLByRPW8","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-11-02T15:21:31Z","test":true,"account_id":"AB1234","status":"active","in_grace_period":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"billing_count":2,"end_at_billing_count":null,"currency":"USD","items":[{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}],"shipping_method_id":null,"date_trial_start":null,"date_trial_end":null,"date_current_period_start":"2026-11-02T15:21:28Z","date_current_period_end":"2026-12-02T15:21:28Z","date_next_renewal_notification":"2026-11-29T15:21:28Z","date_cancelled":null,"cancellation_reason":null,"cancel_at_current_period_end":false,"date_ended":null,"add_at_current_period_end":[],"subscription_plan":"https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C","customer":"https://api.comecero.com/api/v1/customers/0093799288003CuGOip8X9","invoices":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/invoices","history":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/history","meta":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Not a test subscription, not `active` or `trial`, or the period already ends before the time asked for.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/subscriptions/{subscription_id}/history":{"parameters":[{"name":"subscription_id","in":"path","required":true,"description":"The subscription id.","schema":{"type":"string"}}],"get":{"operationId":"get_subscription_history","summary":"Get subscription history","description":"Returns the change log of a subscription: who changed what and when. Core keeps the last 100 entries. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["subscriptions"],"parameters":[{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The subscription history.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_history"},"example":{"object":"subscription_history","subscription_id":"0093799318129SuLByRPW8","test":true,"entries":[{"date_created":"2026-11-02T15:21:31Z","initiated_by":"Administrator","description":"The current billing period has been extended by 7 days"},{"date_created":"2026-11-05T09:12:44Z","initiated_by":"customer","description":"The subscription has been scheduled to be cancelled at the end of the current billing period"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/subscriptions/{subscription_id}/invoices":{"parameters":[{"name":"subscription_id","in":"path","required":true,"description":"The subscription id.","schema":{"type":"string"}}],"get":{"operationId":"list_subscription_invoices","summary":"List subscription invoices","description":"Lists the invoices of a subscription, one per billing period plus any made for item changes. Together they are the subscription's billing history. Draft invoices are left out. The list is offset-based. Secret, trusted and limited tokens may call it; a limited token only for the customer it is signed in as.","tags":["subscriptions"],"x-limited":true,"parameters":[{"name":"open","in":"query","required":false,"description":"Only invoices that are, or are not, open (still to be paid).","schema":{"type":"boolean"}},{"name":"payment_status","in":"query","required":false,"description":"Only invoices with this payment status.","schema":{"type":"string","enum":["unpaid","scheduled","initiated","processing","pending","completed","failed","cancelled","refunded","retry"]}},{"name":"q","in":"query","required":false,"description":"Only the invoice with this exact id.","schema":{"type":"string"}},{"name":"sort_by","in":"query","required":false,"description":"The field to sort by.","schema":{"type":"string","enum":["date_created","date_modified","date_completed"],"default":"date_created"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of invoices.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/invoice_list_offset"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/invoices?offset=0&limit=10","data":[{"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"}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/subscriptions/{subscription_id}/items":{"parameters":[{"name":"subscription_id","in":"path","required":true,"description":"The subscription id.","schema":{"type":"string"}}],"get":{"operationId":"list_subscription_items","summary":"List subscription items","description":"Returns the items of a subscription, including cancelled ones, as a plain JSON array (no paging wrapper). `limit` and `offset` slice the array. Secret, trusted and limited tokens may call it; a limited token only for the customer it is signed in as.","tags":["subscriptions"],"x-limited":true,"parameters":[{"name":"sort_by","in":"query","required":false,"description":"The field to sort by.","schema":{"type":"string","enum":["date_created","date_modified","product_id","item_id"],"default":"date_created"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The items.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/subscription_item"}},"example":[{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}]}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"create_subscription_item","summary":"Add a subscription item","description":"Adds an item to a running subscription, or replaces one item with another when you send `remove_item_id` (an upgrade or downgrade). The item is a product (`product_id`) or a custom item (`name`, `type`, `reference_price` and `reference_currency`, no `product_id`). Answers `201` with the new item when the change applies now, or `200` with the pending item when it is scheduled for the end of the current period (then nothing is charged and the item shows in `add_at_current_period_end` or the replaced item's `change_at_current_period_end`). Money can move. When the change applies at once, the customer pays the prorated amount for the rest of the current period now (from their account balance first, then their saved payment method) and an invoice is made; a cheaper replacement or lower quantity is refunded prorated, to the original payment method where possible, otherwise to the account balance. Whether a change applies at once or at the period end depends on the immediate upgrade and downgrade product types in your subscription settings, or on `apply_immediately`. On a live subscription only one money-moving change is allowed every 10 minutes. Use the preview endpoint first to show the customer the amount. Secret, trusted and limited tokens may call it. A limited token only for the customer it is signed in as; it may not send prices, discounts or `apply_immediately`, may only replace product items, and only when your subscription settings allow customer upgrades or downgrades.","tags":["subscriptions"],"x-limited":true,"parameters":[{"name":"remove_item_id","in":"query","required":false,"description":"The id of an active item to replace with the new one. A new item at the same or a higher price is an upgrade; a lower price is a downgrade. A product on another subscription plan makes a new subscription when paid, if the product allows that term change.","schema":{"type":"string"}},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_item_request"},"examples":{"product":{"summary":"Add a product","value":{"product_id":"widget-pro.test","quantity":1}},"custom":{"summary":"Add a custom line","value":{"name":"Priority support","type":"service","quantity":1,"reference_price":10,"reference_currency":"USD"}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The change is scheduled for the end of the current period. Returns the pending item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_item"},"example":{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}}}},"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The item was added now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_item"},"example":{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"The change cannot be made: the subscription is cancelled, completed or in its grace period, the item is not active, the product is already in the subscription or uses another plan, the payment for the change failed, or a live subscription had a money-moving change less than 10 minutes ago.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/subscriptions/{subscription_id}/items/preview":{"parameters":[{"name":"subscription_id","in":"path","required":true,"description":"The subscription id.","schema":{"type":"string"}}],"post":{"operationId":"preview_subscription_item","summary":"Preview adding an item","description":"Takes the same body and `remove_item_id` as `POST /subscriptions/{subscription_id}/items` and returns what the change would cost and when it would apply, without charging. Send `date_effective` from the result with `apply_immediately: true` to make the real change with the same amounts. Always answers `200`. Secret, trusted and limited tokens may call it, with the same rules as adding an item.","tags":["subscriptions"],"x-limited":true,"parameters":[{"name":"remove_item_id","in":"query","required":false,"description":"The id of an active item the new one would replace.","schema":{"type":"string"}},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_item_request"},"examples":{"product":{"summary":"Preview adding a product","value":{"product_id":"widget-pro.test","quantity":1}},"custom":{"summary":"Preview a custom line","value":{"name":"Priority support","type":"service","quantity":1,"reference_price":10,"reference_currency":"USD"}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"What the change would do.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_change_summary"},"example":{"object":"subscription_change_summary","payment_total":13.3,"refund_total":0,"net_total":13.3,"currency":"USD","date_next_payment":"2026-12-02T15:21:28Z","date_effective":"2026-11-12T10:00:00Z","generates_new_subscription":false,"apply_at_period_end":false,"subscription_terms":{"object":"subscription_terms","price":19.95,"quantity":2,"currency":"USD","discount":0,"discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"tax_inclusve":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"date_trial_start":null,"date_trial_end":null,"end_at_billing_count":null,"date_billing_start":"2026-10-02T15:21:28Z","subscription_id":"0093799318129SuLByRPW8","description":"Acme Pro (monthly) is a subscription that renews every month with a payment of $19.95, per quantity.","price_per_day":0.66,"price_per_month":19.95,"price_per_year":239.4}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"The change cannot be made: the subscription is cancelled, completed or in its grace period, the item is not active, the product is already in the subscription or uses another plan, the payment for the change failed, or a live subscription had a money-moving change less than 10 minutes ago.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/subscriptions/{subscription_id}/items/{item_id}":{"parameters":[{"name":"subscription_id","in":"path","required":true,"description":"The subscription id.","schema":{"type":"string"}},{"name":"item_id","in":"path","required":true,"description":"The item id. For a product item it is the `product_id`.","schema":{"type":"string"}}],"get":{"operationId":"get_subscription_item","summary":"Get a subscription item","description":"Returns one item of a subscription. Secret, trusted and limited tokens may call it; a limited token only for the customer it is signed in as.","tags":["subscriptions"],"x-limited":true,"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_item"},"example":{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"update_subscription_item","summary":"Update a subscription item","description":"Changes an item's quantity, price or discount, or its `meta`. A change to `meta` or `cancellation_reason` only is saved at once with no charge. A change to quantity, price or discount applies now or at the end of the current period; when scheduled it shows in the item's `change_at_current_period_end`. Money can move. When the change applies at once, the customer pays the prorated amount for the rest of the current period now (from their account balance first, then their saved payment method) and an invoice is made; a cheaper replacement or lower quantity is refunded prorated, to the original payment method where possible, otherwise to the account balance. Whether a change applies at once or at the period end depends on the immediate upgrade and downgrade product types in your subscription settings, or on `apply_immediately`. On a live subscription only one money-moving change is allowed every 10 minutes. Use the preview endpoint first to show the customer the amount. Always answers `200` with the item. Secret, trusted and limited tokens may call it. A limited token only for the customer it is signed in as; it may change the quantity only (when your subscription settings allow customer upgrades or downgrades).","tags":["subscriptions"],"x-limited":true,"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_item_update_request"},"examples":{"quantity":{"summary":"Change the quantity","value":{"quantity":2}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The item after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_item"},"example":{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"The change cannot be made: the subscription is cancelled, completed or in its grace period, the item is not active, the product is already in the subscription or uses another plan, the payment for the change failed, or a live subscription had a money-moving change less than 10 minutes ago.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/subscriptions/{subscription_id}/items/{item_id}/cancel":{"parameters":[{"name":"subscription_id","in":"path","required":true,"description":"The subscription id.","schema":{"type":"string"}},{"name":"item_id","in":"path","required":true,"description":"The item id. For a product item it is the `product_id`.","schema":{"type":"string"}}],"post":{"operationId":"cancel_subscription_item","summary":"Cancel a subscription item","description":"Cancels one item. By default (or with no body) the cancellation is scheduled for the end of the current period and the item is billed until then. With `cancel_at_current_period_end: false` the item is cancelled at once and any scheduled change to it is dropped. No refund is made. When the last active item is cancelled at once, the whole subscription is cancelled. Events `subscription_item:cancellation_scheduled` or `subscription_item:cancelled` fire. Secret, trusted and limited tokens may call it. A limited token only for the customer it is signed in as, and only when your subscription settings allow customers to cancel (otherwise `403`).","tags":["subscriptions"],"x-limited":true,"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_cancel_request"},"examples":{"at_period_end":{"summary":"Cancel the item at the end of the period","value":{"cancel_at_current_period_end":true,"cancellation_reason":"No longer needed"}},"now":{"summary":"Cancel the item now","value":{"cancel_at_current_period_end":false,"cancellation_reason":"Too expensive"}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The item after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_item"},"example":{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"The item id is not in the subscription, the item is already cancelled, or the subscription is cancelled or completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/subscriptions/{subscription_id}/items/{item_id}/change_at_current_period_end":{"parameters":[{"name":"subscription_id","in":"path","required":true,"description":"The subscription id.","schema":{"type":"string"}},{"name":"item_id","in":"path","required":true,"description":"The item id. For a product item it is the `product_id`.","schema":{"type":"string"}}],"delete":{"operationId":"delete_subscription_item_scheduled_change","summary":"Remove an item's scheduled change","description":"Removes the change scheduled for this item at the end of the current period (`change_at_current_period_end`), such as a new quantity or a replacement product. Nothing is charged or refunded. Returns the item, not an empty body. Secret, trusted and limited tokens may call it; a limited token only for the customer it is signed in as.","tags":["subscriptions"],"x-limited":true,"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The item after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_item"},"example":{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"The item or the subscription is cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/subscriptions/{subscription_id}/items/{item_id}/preview":{"parameters":[{"name":"subscription_id","in":"path","required":true,"description":"The subscription id.","schema":{"type":"string"}},{"name":"item_id","in":"path","required":true,"description":"The item id. For a product item it is the `product_id`.","schema":{"type":"string"}}],"post":{"operationId":"preview_subscription_item_update","summary":"Preview an item change","description":"Takes the same body as `POST /subscriptions/{subscription_id}/items/{item_id}` and returns what the change would cost and when it would apply, without charging or saving. A body with no change to quantity, price or discount answers `422`. Secret, trusted and limited tokens may call it, with the same rules as updating the item.","tags":["subscriptions"],"x-limited":true,"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_item_update_request"},"examples":{"quantity":{"summary":"Preview a new quantity","value":{"quantity":2}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"What the change would do.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_change_summary"},"example":{"object":"subscription_change_summary","payment_total":13.3,"refund_total":0,"net_total":13.3,"currency":"USD","date_next_payment":"2026-12-02T15:21:28Z","date_effective":"2026-11-12T10:00:00Z","generates_new_subscription":false,"apply_at_period_end":false,"subscription_terms":{"object":"subscription_terms","price":19.95,"quantity":2,"currency":"USD","discount":0,"discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"tax_inclusve":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"date_trial_start":null,"date_trial_end":null,"end_at_billing_count":null,"date_billing_start":"2026-10-02T15:21:28Z","subscription_id":"0093799318129SuLByRPW8","description":"Acme Pro (monthly) is a subscription that renews every month with a payment of $19.95, per quantity.","price_per_day":0.66,"price_per_month":19.95,"price_per_year":239.4}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"The change cannot be made: the subscription is cancelled, completed or in its grace period, the item is not active, the product is already in the subscription or uses another plan, the payment for the change failed, or a live subscription had a money-moving change less than 10 minutes ago.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/subscriptions/{subscription_id}/items/{item_id}/subscription_terms":{"parameters":[{"name":"subscription_id","in":"path","required":true,"description":"The subscription id.","schema":{"type":"string"}},{"name":"item_id","in":"path","required":true,"description":"The item id. For a product item it is the `product_id`.","schema":{"type":"string"}}],"get":{"operationId":"get_subscription_item_terms","summary":"Get an item's billing terms","description":"Returns the billing terms of one item: price, quantity, interval, trial, discount and a ready-to-show sentence. Secret, trusted and limited tokens may call it; a limited token only for the customer it is signed in as.","tags":["subscriptions"],"x-limited":true,"parameters":[{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The item's billing terms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_terms"},"example":{"object":"subscription_terms","price":19.95,"quantity":1,"currency":"USD","discount":0,"discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"tax_inclusve":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"date_trial_start":null,"date_trial_end":null,"end_at_billing_count":null,"date_billing_start":"2026-10-02T15:21:28Z","subscription_id":"0093799318129SuLByRPW8","description":"Acme Pro (monthly) is a subscription that renews every month with a payment of $19.95.","price_per_day":0.66,"price_per_month":19.95,"price_per_year":239.4}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/subscriptions/{subscription_id}/items/{item_id}/uncancel":{"parameters":[{"name":"subscription_id","in":"path","required":true,"description":"The subscription id.","schema":{"type":"string"}},{"name":"item_id","in":"path","required":true,"description":"The item id. For a product item it is the `product_id`.","schema":{"type":"string"}}],"post":{"operationId":"uncancel_subscription_item","summary":"Undo an item's scheduled cancellation","description":"Removes a cancellation of one item that was scheduled for the end of the current period, so the item keeps renewing. An item that is already cancelled cannot be uncancelled (`422`). The `subscription_item:cancellation_unscheduled` event fires. No body. Secret, trusted and limited tokens may call it. A limited token only for the customer it is signed in as, and only when your subscription settings allow customers to cancel (otherwise `403`).","tags":["subscriptions"],"x-limited":true,"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The item after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_item"},"example":{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"The item or the subscription is already cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/subscriptions/{subscription_id}/notifications":{"parameters":[{"name":"subscription_id","in":"path","required":true,"description":"The subscription id.","schema":{"type":"string"}}],"get":{"operationId":"list_subscription_notifications","summary":"List subscription notifications","description":"Lists the emails sent to the customer about this subscription, such as renewal reminders and cancellation notices. The list is offset-based. Secret, trusted and limited tokens may call it; a limited token only for the customer it is signed in as.","tags":["subscriptions"],"x-limited":true,"parameters":[{"name":"sort_by","in":"query","required":false,"description":"The field to sort by.","schema":{"type":"string","enum":["date_created","date_modified"],"default":"date_created"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of notifications.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription_notification_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/notifications?offset=0&limit=10","data":[{"object":"notification","url":"https://api.comecero.com/api/v1/notifications/1102611073905NOq2Lx7Pv","notification_id":"1102611073905NOq2Lx7Pv","test":true,"account_id":"AB1234","type":"order:confirmation","method":"email","from":"notification@comecero.com","from_name":"Example Shop","reply_to":"support@example.com","bcc":null,"destination":"john@example.com","subject":"Your Order Confirmation","notification_subscription":"https://api.comecero.com/api/v1/notification_subscriptions/1102500112233NSd4Kw9Tz","customer":"https://api.comecero.com/api/v1/customers/1102611073801CUa8Hn2Lq","status":"delivered","date_created":"2026-11-07T14:32:12Z","date_modified":"2026-11-07T14:32:14Z","data":{"order":{"order_id":"7393-GMRFY-954","total":99.95,"currency":"USD"}},"body":"<html><body><h1>Thanks for your order</h1></body></html>"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/subscriptions/{subscription_id}/retry":{"parameters":[{"name":"subscription_id","in":"path","required":true,"description":"The subscription id.","schema":{"type":"string"}}],"post":{"operationId":"retry_subscription_payment","summary":"Retry a failed renewal payment","description":"Charges the customer now. Core takes the newest open invoice of the subscription whose payment status is `retry` and tries to pay it with the customer's account balance and saved payment method, outside the automatic retry schedule. The automatic schedule is not changed. The subscription must be `active`. If a manual retry was declined in the last 12 hours, or another payment attempt for the invoice is running or was made in the last 10 minutes, the request is refused (`422`). A successful payment answers `201` with the payment and ends the grace period. A failed payment answers with an error whose `meta.payment` holds the failed payment. Secret and trusted tokens may call it, and need permission to update payments; a limited token may not (`403`).","tags":["subscriptions"],"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The successful payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment"},"example":{"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}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The payment was declined. `error.meta.payment` holds the failed payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"description":"Nothing to retry (no open invoice in `retry` status), the subscription is not active, or a retry is not allowed yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"The payment gateway returned an error. `error.meta.payment` holds the failed payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"504":{"description":"The payment gateway timed out. `error.meta.payment` holds the payment. Check the payment before you retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}}}}},"/subscriptions/{subscription_id}/uncancel":{"parameters":[{"name":"subscription_id","in":"path","required":true,"description":"The subscription id.","schema":{"type":"string"}}],"post":{"operationId":"uncancel_subscription","summary":"Undo a scheduled cancellation","description":"Removes a cancellation that was scheduled for the end of the current period, for the subscription and all its items, so it keeps renewing. The `subscription:cancellation_unscheduled` event fires. A subscription that is already cancelled cannot be uncancelled (`422`). No body. Secret, trusted and limited tokens may call it. A limited token may only do this for the customer it is signed in as, and only when your subscription settings allow customers to cancel (otherwise `403`).","tags":["subscriptions"],"x-limited":true,"parameters":[{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The subscription after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/subscription"},"example":{"object":"subscription","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_id":"0093799318129SuLByRPW8","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-11-02T15:21:31Z","test":true,"account_id":"AB1234","status":"active","in_grace_period":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"billing_count":2,"end_at_billing_count":null,"currency":"USD","items":[{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}],"shipping_method_id":null,"date_trial_start":null,"date_trial_end":null,"date_current_period_start":"2026-11-02T15:21:28Z","date_current_period_end":"2026-12-02T15:21:28Z","date_next_renewal_notification":"2026-11-29T15:21:28Z","date_cancelled":null,"cancellation_reason":null,"cancel_at_current_period_end":false,"date_ended":null,"add_at_current_period_end":[],"subscription_plan":"https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C","customer":"https://api.comecero.com/api/v1/customers/0093799288003CuGOip8X9","invoices":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/invoices","history":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/history","meta":null}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"The subscription is already cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/templates":{"get":{"operationId":"list_templates","summary":"List templates","description":"Lists the templates in your account, email and PDF. In the list, `body` is left out; get one template to read it. The list is offset-based. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["templates"],"parameters":[{"name":"q","in":"query","required":false,"description":"An exact template id.","schema":{"type":"string"}},{"name":"sort_by","in":"query","required":false,"description":"The field to sort by. Any other value uses the default.","schema":{"type":"string","enum":["date_created","date_modified","template_id"],"default":"date_created"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/desc"},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"A page of templates.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/template_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/templates","data":[{"object":"template","url":"https://api.comecero.com/api/v1/templates/1102500900112TEm5Jc3Rw","template_id":"1102500900112TEm5Jc3Rw","date_created":"2026-10-01T09:05:00Z","date_modified":"2026-10-01T09:05:00Z","test":true,"account_id":"AB1234","expand":null,"show":null,"hide":null,"wrapper_template":null,"comments":"Download email","template_type":null,"pdf_type":null,"page_format":null,"orientation":null,"margin_top":null,"margin_bottom":null,"margin_left":null,"margin_right":null,"body":"To obtain the template body, access this resource directly."}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"create_template","summary":"Create a template","description":"Saves a Handlebars template. Use its id as `template_id` on a notification subscription, as `wrapper_template_id` on another template, or with `POST /notifications`. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["templates"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/template_request"},{"required":["body"]}]},"examples":{"minimal":{"summary":"Body only","value":{"body":"<p>Thanks for your order, {{customer.first_name}}.</p>"}},"full":{"summary":"With a subject and comments","value":{"body":"<p>Hi {{customer.first_name}}, your download is ready: {{download_url}}</p>","default_subject":"Your download is ready","comments":"Download email"}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new template.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/template"},"example":{"object":"template","url":"https://api.comecero.com/api/v1/templates/1102500900112TEm5Jc3Rw","template_id":"1102500900112TEm5Jc3Rw","date_created":"2026-10-01T09:05:00Z","date_modified":"2026-10-01T09:05:00Z","test":true,"account_id":"AB1234","expand":null,"show":null,"hide":null,"wrapper_template":null,"comments":"Download email","template_type":null,"pdf_type":null,"page_format":null,"orientation":null,"margin_top":null,"margin_bottom":null,"margin_left":null,"margin_right":null,"body":"<p>Hi {{customer.first_name}}, your download is ready: {{download_url}}</p>"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/templates/{id}":{"get":{"operationId":"get_template","summary":"Get a template","description":"Gets one template with its `body`. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["templates"],"parameters":[{"name":"id","in":"path","required":true,"description":"The template id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/timezone"},{"$ref":"#/components/parameters/expand"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/formatted"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The template.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/template"},"example":{"object":"template","url":"https://api.comecero.com/api/v1/templates/1102500900112TEm5Jc3Rw","template_id":"1102500900112TEm5Jc3Rw","date_created":"2026-10-01T09:05:00Z","date_modified":"2026-10-01T09:05:00Z","test":true,"account_id":"AB1234","expand":null,"show":null,"hide":null,"wrapper_template":null,"comments":"Download email","template_type":null,"pdf_type":null,"page_format":null,"orientation":null,"margin_top":null,"margin_bottom":null,"margin_left":null,"margin_right":null,"body":"<p>Hi {{customer.first_name}}, your download is ready: {{download_url}}</p>"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"update_template","summary":"Update a template","description":"Changes the fields you send and leaves the others as they are. Emails sent after the change use the new body. Answers `201`, not `200`. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["templates"],"parameters":[{"name":"id","in":"path","required":true,"description":"The template id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/template_request"},"example":{"body":"<p>Hello {{customer.first_name}}, here is your download: {{download_url}}</p>"}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The updated template.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/template"},"example":{"object":"template","url":"https://api.comecero.com/api/v1/templates/1102500900112TEm5Jc3Rw","template_id":"1102500900112TEm5Jc3Rw","date_created":"2026-10-01T09:05:00Z","date_modified":"2026-10-01T09:05:00Z","test":true,"account_id":"AB1234","expand":null,"show":null,"hide":null,"wrapper_template":null,"comments":"Download email","template_type":null,"pdf_type":null,"page_format":null,"orientation":null,"margin_top":null,"margin_bottom":null,"margin_left":null,"margin_right":null,"body":"<p>Hi {{customer.first_name}}, your download is ready: {{download_url}}</p>"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"operationId":"delete_template","summary":"Delete a template","description":"Deletes the template. Core does not check whether a notification subscription or another template still uses it: check first, or those emails fall back to the built-in template. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["templates"],"parameters":[{"name":"id","in":"path","required":true,"description":"The template id.","schema":{"type":"string"}}],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The template was deleted. There is no body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/templates/{template_id}/build":{"post":{"operationId":"build_template","summary":"Render a template","description":"Fills the template (and its wrapper and embedded templates) with the JSON object you send and returns the result. Use it to preview an email. Nothing is saved or sent. Your account's details are added as `account` unless the body has its own. The body must be a JSON object. Secret and trusted tokens may call it; a limited token may not (`403`).","tags":["templates"],"parameters":[{"name":"template_id","in":"path","required":true,"description":"The template id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","title":"template_build_request","description":"The values the template reads.","additionalProperties":true},"example":{"customer":{"first_name":"John"},"download_url":"https://example.com/downloads/abc123"}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The rendered template.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/template_build"},"example":{"data":"<p>Hi John, your download is ready: https://example.com/downloads/abc123</p>"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/users":{"get":{"summary":"List users","operationId":"list_users","description":"Lists the users of your account in the mode of the token you call with. A test token lists test users. The list is offset-based.\n\nSecret and trusted tokens may call this with the `users` read permission.","tags":["users"],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"name":"sort_by","in":"query","description":"The field to sort by. The default is `user_id`.","required":false,"schema":{"type":"string","enum":["user_id","name","email","date_created","date_modified"],"default":"user_id"}},{"$ref":"#/components/parameters/desc"},{"name":"q","in":"query","description":"Finds users whose `user_id` or `email` is exactly this value, or whose name contains it (any case).","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/timezone"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"An offset-based list of users.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/user_list"},"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/users","data":[{"object":"user","url":"https://api.comecero.com/api/v1/users/jane.smith.test","user_id":"jane.smith.test","test":true,"date_created":"2026-10-01T14:36:52Z","date_modified":"2026-10-01T14:36:52Z","account_id":"AB1234","account_alias":"example-shop","account_live":true,"name":"Jane Smith","email":"jane@example.com","is_account_owner":false,"language":"en","locale":"en-US","date_last_login":"2026-11-06T09:12:40Z","allow_test_transactions":true,"roles":["support"],"permissions":[],"effective_permissions":{"orders":{"create":false,"read":true,"update":true,"delete":false}},"meta":null}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Create a user","operationId":"create_user","description":"Adds a user who can sign in to your dashboard, in the mode of the token you call with. A user made with a test token is a test user and its `user_id` gets `.test` added. Fires the `user:created` event.\n\nSecret and trusted tokens may call this with the `users` create permission.","tags":["users"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/user_request"},"examples":{"minimal":{"summary":"Required fields only","value":{"user_id":"jane.smith","name":"Jane Smith","email":"jane@example.com","password":"correct-horse-battery"}},"full":{"summary":"With a role","value":{"user_id":"jane.smith","name":"Jane Smith","email":"jane@example.com","password":"correct-horse-battery","roles":["support"]}}}}}},"responses":{"201":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The new user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/user"},"example":{"object":"user","url":"https://api.comecero.com/api/v1/users/jane.smith.test","user_id":"jane.smith.test","test":true,"date_created":"2026-10-01T14:36:52Z","date_modified":"2026-10-01T14:36:52Z","account_id":"AB1234","account_alias":"example-shop","account_live":true,"name":"Jane Smith","email":"jane@example.com","is_account_owner":false,"language":"en","locale":"en-US","date_last_login":"2026-11-06T09:12:40Z","allow_test_transactions":true,"roles":["support"],"permissions":[],"effective_permissions":{"orders":{"create":false,"read":true,"update":true,"delete":false}},"meta":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/users/{user_id}":{"parameters":[{"name":"user_id","in":"path","description":"The user's `user_id`. With a trusted token, `me` means the signed-in user. `me` with any other token type is `403`.","required":true,"schema":{"type":"string"},"example":"jane.smith.test"}],"get":{"summary":"Get a user","operationId":"get_user","description":"Gets one user. A trusted token may always read its own user with `me`, even without the `users` read permission. Reading any other user needs a secret or trusted token with that permission. A user of the other mode is not found (`404`).","tags":["users"],"parameters":[{"$ref":"#/components/parameters/formatted"},{"$ref":"#/components/parameters/show"},{"$ref":"#/components/parameters/hide"},{"$ref":"#/components/parameters/timezone"}],"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/user"},"example":{"object":"user","url":"https://api.comecero.com/api/v1/users/jane.smith.test","user_id":"jane.smith.test","test":true,"date_created":"2026-10-01T14:36:52Z","date_modified":"2026-10-01T14:36:52Z","account_id":"AB1234","account_alias":"example-shop","account_live":true,"name":"Jane Smith","email":"jane@example.com","is_account_owner":false,"language":"en","locale":"en-US","date_last_login":"2026-11-06T09:12:40Z","allow_test_transactions":true,"roles":["support"],"permissions":[],"effective_permissions":{"orders":{"create":false,"read":true,"update":true,"delete":false}},"meta":null}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Update a user","operationId":"update_user","description":"Changes a user. Only the fields you send change. Fires the `user:modified` event.\n\nA trusted token may always update its own user with `me`, even without the `users` update permission. On `me` only `name`, `email`, `password` and `language` are used; other fields are ignored. Updating any other user needs a secret or trusted token with that permission.","tags":["users"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/user_update_request"},"examples":{"update":{"summary":"New name and roles","value":{"name":"Jane Smith-Jones","roles":["support","fulfillment"]}}}}}},"responses":{"200":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The updated user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/user"},"example":{"object":"user","url":"https://api.comecero.com/api/v1/users/jane.smith.test","user_id":"jane.smith.test","test":true,"date_created":"2026-10-01T14:36:52Z","date_modified":"2026-10-01T14:36:52Z","account_id":"AB1234","account_alias":"example-shop","account_live":true,"name":"Jane Smith","email":"jane@example.com","is_account_owner":false,"language":"en","locale":"en-US","date_last_login":"2026-11-06T09:12:40Z","allow_test_transactions":true,"roles":["support"],"permissions":[],"effective_permissions":{"orders":{"create":false,"read":true,"update":true,"delete":false}},"meta":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"summary":"Delete a user","operationId":"delete_user","description":"Deletes a user so they can no longer sign in. You cannot delete yourself or use `me` (`400`).\n\nSecret and trusted tokens may call this with the `users` delete permission.","tags":["users"],"responses":{"204":{"headers":{"X-Token-Expires-In-Seconds":{"$ref":"#/components/headers/X-Token-Expires-In-Seconds"}},"description":"The user is deleted. No body."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}}},"webhooks":{"account:modified":{"post":{"operationId":"event_account_modified","summary":"Account modified","description":"Fires when your account's details are changed (company name, contact details, status and so on). It is only made in live mode, so only live event subscriptions receive it. The body is an event object with the account in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"account:modified"},"data":{"description":"The account the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/account"}]}}}]},"examples":{"event":{"summary":"A account:modified event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"account:modified","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"account","url":"https://api.comecero.com/api/v1/accounts/AB1234","account_id":"AB1234","alias":"example-shop","date_created":"2026-03-01T14:36:52Z","date_modified":"2026-10-01T09:20:11Z","company_name":"Example Software Ltd","dba":"Example Software","name":"John Doe","email":"john@example.com","website":"https://www.example.com","phone":"+1 555 0100","tax_number":null,"registration_number":null,"logo_url":"https://www.example.com/logo.png","address_1":"100 Main Street","address_2":null,"city":"Springfield","state_prov":"IL","postal_code":"62701","country":"US","support_email":"support@example.com","support_website":"https://www.example.com/support","live":true,"closed":false,"date_closed":null,"account_meta":"https://api.comecero.com/api/v1/accounts/AB1234/account_meta"}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"cart:payment_completed":{"post":{"operationId":"event_cart_payment_completed","summary":"Cart payment completed","description":"Fires when the completed payments on the order made from a cart cover its total and no payment on it is `pending`, at the same time as `order:payment_completed`. A cart paid by an authorization that is captured later fires it at capture. The body is an event object with the cart in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"cart:payment_completed"},"data":{"description":"The cart the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/cart"}]}}}]},"examples":{"event":{"summary":"A cart:payment_completed event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"cart:payment_completed","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"cart","url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1","cart_id":"0091307952465CafhFSTa1","date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:21:40Z","test":true,"account_id":"AB1234","order_id":"8352-CSGYX-348","open":true,"payment_status":null,"currency":"USD","subtotal":199.9,"subtotal_original":199.9,"shipping":0,"shipping_original":0,"discount":0,"item_discounts":0,"total_discounts":0,"total_discounts_percent":0,"tax":14.99,"tax_original":14.99,"total":214.89,"total_original":214.89,"tax_inclusive":false,"total_payments":0,"total_remaining":214.89,"discount_on_gross":false,"settlement_currency":"USD","settlement_subtotal":199.9,"settlement_subtotal_original":199.9,"settlement_shipping":0,"settlement_shipping_original":0,"settlement_discount":0,"settlement_total_discounts":0,"settlement_tax":14.99,"settlement_tax_original":14.99,"settlement_total":214.89,"settlement_total_original":214.89,"customer_ip_address":"203.0.113.44","customer_ip_country":"US","referrer":"campaign-0044","affiliate_id":null,"promotion_code":null,"items_count":1,"items_quantity":2,"items":[{"object":"cart_item","url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/items/pdf-pro.test","item_id":"pdf-pro.test","cross_sell_id":null,"up_sell_id":null,"bundle_id":null,"bundle_group_id":null,"date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:19:12Z","product_id":"pdf-pro.test","cart_id":"0091307952465CafhFSTa1","name":"PDF Viewer Pro","type":"digital","quantity":2,"currency":"USD","price":99.95,"price_original":99.95,"reference_price":null,"reference_currency":null,"subtotal":199.9,"subtotal_original":199.9,"discount":0,"discount_percent":0,"tax":14.99,"tax_original":14.99,"total":214.89,"total_original":214.89,"tax_rate":0.075,"tax_code":null,"settlement_currency":"USD","settlement_price":99.95,"settlement_price_original":99.95,"settlement_subtotal":199.9,"settlement_subtotal_original":199.9,"settlement_discount":0,"settlement_tax":14.99,"settlement_tax_original":14.99,"settlement_total":214.89,"settlement_total_original":214.89,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription_plan":null,"subscription_terms":null,"meta":null}],"shipping_item":null,"customer":{"object":"customer","url":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1","customer_id":"0091307952481CuXUhvCA1","date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:21:40Z","account_id":"AB1234","test":true,"company_name":null,"name":"John Smith","email":"john@example.com","phone":null,"billing_address":{"object":"address","name":null,"address_1":null,"address_2":null,"city":null,"state_prov":null,"postal_code":"27265","country":"US","email":null,"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":null,"tax_number":null,"tax_exempt":false,"has_payments":false,"locale":"en-US","meta":null,"payment_methods":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/payment_methods","payments":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/payments","refunds":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/refunds","orders":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/orders","subscriptions":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/subscriptions","invoices":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/invoices"},"order":null,"payments":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/payments","promotions":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/promotions","options":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/options","meta":null,"related_products":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/related_products","cross_sells":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/cross_sells","up_sells":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/up_sells"}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"gateway:created":{"post":{"operationId":"event_gateway_created","summary":"Gateway created","description":"Fires when a payment gateway is added to your account. The body is an event object with the gateway in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"gateway:created"},"data":{"description":"The gateway the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/gateway"}]}}}]},"examples":{"event":{"summary":"A gateway:created event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"gateway:created","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"gateway","url":"https://api.comecero.com/api/v1/gateways/0070576784690GtKDqfI7c","gateway_id":"0070576784690GtKDqfI7c","test":true,"name":"Test Gateway","provider_id":"test","date_created":"2026-10-01T14:36:52Z","date_modified":"2026-10-01T14:36:52Z","account_id":"AB1234","payment_method_types":["credit_card"],"currencies":["USD","EUR"],"card_types":["visa","mastercard","american_express"],"supports_void":true,"supports_general_credit":false,"active":true,"weight":1,"comments":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"gateway:modified":{"post":{"operationId":"event_gateway_modified","summary":"Gateway modified","description":"Fires when a payment gateway is changed, including when it is turned on or off. The body is an event object with the gateway in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"gateway:modified"},"data":{"description":"The gateway the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/gateway"}]}}}]},"examples":{"event":{"summary":"A gateway:modified event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"gateway:modified","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"gateway","url":"https://api.comecero.com/api/v1/gateways/0070576784690GtKDqfI7c","gateway_id":"0070576784690GtKDqfI7c","test":true,"name":"Test Gateway","provider_id":"test","date_created":"2026-10-01T14:36:52Z","date_modified":"2026-10-01T14:36:52Z","account_id":"AB1234","payment_method_types":["credit_card"],"currencies":["USD","EUR"],"card_types":["visa","mastercard","american_express"],"supports_void":true,"supports_general_credit":false,"active":true,"weight":1,"comments":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"event_subscription:created":{"post":{"operationId":"event_event_subscription_created","summary":"Event subscription created","description":"Fires when an event subscription is created. The `data` includes the new subscription's `signature_key` and HTTP authorization password, so treat this event as secret. The body is an event object with the event subscription in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"event_subscription:created"},"data":{"description":"The event subscription the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/event_subscription"}]}}}]},"examples":{"event":{"summary":"A event_subscription:created event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"event_subscription:created","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"event_subscription","url":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","event_subscription_id":"1102610913420ES4f9QmLp","date_created":"2026-11-07T14:20:03Z","date_modified":"2026-11-07T14:20:03Z","test":true,"active":true,"account_id":"AB1234","event_type":"order:created","destination":"https://example.com/webhooks/comecero","format":"json","method":"http","timezone":null,"signature_key":null,"expand":"customer","show":null,"hide":null,"http_authorization_username":null,"http_authorization_password":null,"custom_header_name":null,"custom_header_value":null,"environment_variables":{"store":"main"},"comments":"Order sync"}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"event_subscription:modified":{"post":{"operationId":"event_event_subscription_modified","summary":"Event subscription modified","description":"Fires when an event subscription is changed. The `data` includes its `signature_key` and HTTP authorization password, so treat this event as secret. The body is an event object with the event subscription in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"event_subscription:modified"},"data":{"description":"The event subscription the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/event_subscription"}]}}}]},"examples":{"event":{"summary":"A event_subscription:modified event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"event_subscription:modified","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"event_subscription","url":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","event_subscription_id":"1102610913420ES4f9QmLp","date_created":"2026-11-07T14:20:03Z","date_modified":"2026-11-07T14:20:03Z","test":true,"active":true,"account_id":"AB1234","event_type":"order:created","destination":"https://example.com/webhooks/comecero","format":"json","method":"http","timezone":null,"signature_key":null,"expand":"customer","show":null,"hide":null,"http_authorization_username":null,"http_authorization_password":null,"custom_header_name":null,"custom_header_value":null,"environment_variables":{"store":"main"},"comments":"Order sync"}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"event_subscription:deleted":{"post":{"operationId":"event_event_subscription_deleted","summary":"Event subscription deleted","description":"Fires when an event subscription is deleted. The `data` is the subscription as it was. The body is an event object with the event subscription in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"event_subscription:deleted"},"data":{"description":"The event subscription the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/event_subscription"}]}}}]},"examples":{"event":{"summary":"A event_subscription:deleted event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"event_subscription:deleted","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"event_subscription","url":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","event_subscription_id":"1102610913420ES4f9QmLp","date_created":"2026-11-07T14:20:03Z","date_modified":"2026-11-07T14:20:03Z","test":true,"active":true,"account_id":"AB1234","event_type":"order:created","destination":"https://example.com/webhooks/comecero","format":"json","method":"http","timezone":null,"signature_key":null,"expand":"customer","show":null,"hide":null,"http_authorization_username":null,"http_authorization_password":null,"custom_header_name":null,"custom_header_value":null,"environment_variables":{"store":"main"},"comments":"Order sync"}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"license_service:low_licenses":{"post":{"operationId":"event_license_service_low_licenses","summary":"License service low on licenses","description":"Fires when a license key is taken from a list-based license service and the number left is at or below its `notify_at_count`, or the list is empty. The keys themselves are not sent: `list.licenses` holds a note instead. New accounts get an email subscription to this event by default. The body is an event object with the license service in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"license_service:low_licenses"},"data":{"description":"The license service the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/license_service"}]}}}]},"examples":{"event":{"summary":"A license_service:low_licenses event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"license_service:low_licenses","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"license_service","url":"https://api.comecero.com/api/v1/license_services/0095012789659LsuOeAWLC","license_service_id":"0095012789659LsuOeAWLC","date_created":"2026-11-02T16:26:29Z","date_modified":"2026-11-02T16:45:25Z","test":true,"account_id":"AB1234","name":"Widget Pro keys","label":"License Code","description":null,"instructions":"Open Widget Pro, choose Help, then Enter License, and paste the code.","type":"remote_url","expand":null,"show":null,"hide":null,"configuration":{"url":"https://licenses.example.com/issue","format":"json","http_authorization_username":null,"http_authorization_password":null,"custom_header_name":null,"custom_header_value":null}}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"invoice:created":{"post":{"operationId":"event_invoice_created","summary":"Invoice created","description":"Fires when an invoice is created. For an invoice made by a subscription change that needs a payment, it fires only once that payment succeeds. The body is an event object with the invoice in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"invoice:created"},"data":{"description":"The invoice the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/invoice"}]}}}]},"examples":{"event":{"summary":"A invoice:created event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"invoice:created","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"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"}}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"invoice:published":{"post":{"operationId":"event_invoice_published","summary":"Invoice published","description":"Fires when an invoice leaves draft: when it is created with `draft: false`, or when a draft is changed to `draft: false`. This is when it can be paid and sent to the customer. The body is an event object with the invoice in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"invoice:published"},"data":{"description":"The invoice the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/invoice"}]}}}]},"examples":{"event":{"summary":"A invoice:published event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"invoice:published","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"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"}}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"invoice:paid":{"post":{"operationId":"event_invoice_paid","summary":"Invoice paid","description":"Fires when a payment on the invoice succeeds and the order is made. The payment may still be `pending` (for example an authorization not yet captured); wait for `invoice:payment_completed` when you need the money taken. The body is an event object with the invoice in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"invoice:paid"},"data":{"description":"The invoice the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/invoice"}]}}}]},"examples":{"event":{"summary":"A invoice:paid event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"invoice:paid","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"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"}}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"invoice:payment_completed":{"post":{"operationId":"event_invoice_payment_completed","summary":"Invoice payment completed","description":"Fires when the completed payments on the invoice's order cover its total and no payment on it is `pending`, so the money is taken. It fires at the same time as `order:payment_completed`. The body is an event object with the invoice in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"invoice:payment_completed"},"data":{"description":"The invoice the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/invoice"}]}}}]},"examples":{"event":{"summary":"A invoice:payment_completed event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"invoice:payment_completed","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"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"}}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"order:created":{"post":{"operationId":"event_order_created","summary":"Order created","description":"Fires when a cart or invoice is paid and its order is made, after downloads and license keys are set up, so the order shows its latest payment status. It is the usual event for starting fulfillment. A payment that is only authorized still makes an order: check `payment_status`. The body is an event object with the order in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"order:created"},"data":{"description":"The order the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/order"}]}}}]},"examples":{"event":{"summary":"A order:created event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"order:created","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"order","url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954","order_id":"7393-GMRFY-954","date_created":"2026-11-02T16:46:16Z","date_modified":"2026-11-02T16:46:38Z","test":true,"account_id":"AB1234","payment_status":"completed","fulfilled":true,"currency":"USD","subtotal":49.95,"subtotal_original":49.95,"shipping":0,"shipping_original":0,"discount":0,"item_discounts":0,"total_discounts":0,"total_discounts_percent":0,"tax":0,"tax_original":0,"total":49.95,"total_original":49.95,"tax_inclusive":false,"discount_on_gross":false,"settlement_currency":"USD","settlement_subtotal":49.95,"settlement_subtotal_original":49.95,"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":49.95,"settlement_total_original":49.95,"customer_ip_address":"203.0.113.24","customer_ip_country":"US","referrer":null,"affiliate_id":null,"promotion_code":null,"items_count":1,"items_quantity":1,"items":[{"object":"order_item","url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/items/1","item_id":"1","cross_sell_id":null,"up_sell_id":null,"bundle_id":null,"bundle_group_id":null,"date_created":"2026-11-02T16:46:16Z","date_modified":"2026-11-02T16:46:16Z","product_id":"pdf-pro.test","order_id":"7393-GMRFY-954","name":"PDF Viewer Pro","type":"digital","quantity":1,"currency":"USD","price":49.95,"price_original":49.95,"reference_price":49.95,"reference_currency":"USD","subtotal":49.95,"subtotal_original":49.95,"discount":0,"discount_percent":0,"tax":0,"tax_original":0,"total":49.95,"total_original":49.95,"tax_rate":0,"tax_code":null,"settlement_currency":"USD","settlement_price":49.95,"settlement_price_original":49.95,"settlement_subtotal":49.95,"settlement_subtotal_original":49.95,"settlement_discount":0,"settlement_tax":0,"settlement_tax_original":0,"settlement_total":49.95,"settlement_total_original":49.95,"fulfilled":true,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription":null,"subscription_terms":null,"shipments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/items/1/shipments","license":null,"download":"https://api.comecero.com/api/v1/downloads/0093717990011DlR4kQp2a","meta":null}],"shipping_item":null,"customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","cart":"https://api.comecero.com/api/v1/carts/0093717976083CaO5bXdLA","payments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/payments","payment":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/payments","subscription":null,"refunds":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/refunds","fee_summary":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/fee_summary","invoice":null,"promotions":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/promotions","shipments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/shipments","meta":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"order:payment_completed":{"post":{"operationId":"event_order_payment_completed","summary":"Order payment completed","description":"Fires when no payment on the order is `pending` any more, so the money is taken: at once for a sale, or when an authorization is captured. The body is an event object with the order in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"order:payment_completed"},"data":{"description":"The order the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/order"}]}}}]},"examples":{"event":{"summary":"A order:payment_completed event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"order:payment_completed","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"order","url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954","order_id":"7393-GMRFY-954","date_created":"2026-11-02T16:46:16Z","date_modified":"2026-11-02T16:46:38Z","test":true,"account_id":"AB1234","payment_status":"completed","fulfilled":true,"currency":"USD","subtotal":49.95,"subtotal_original":49.95,"shipping":0,"shipping_original":0,"discount":0,"item_discounts":0,"total_discounts":0,"total_discounts_percent":0,"tax":0,"tax_original":0,"total":49.95,"total_original":49.95,"tax_inclusive":false,"discount_on_gross":false,"settlement_currency":"USD","settlement_subtotal":49.95,"settlement_subtotal_original":49.95,"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":49.95,"settlement_total_original":49.95,"customer_ip_address":"203.0.113.24","customer_ip_country":"US","referrer":null,"affiliate_id":null,"promotion_code":null,"items_count":1,"items_quantity":1,"items":[{"object":"order_item","url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/items/1","item_id":"1","cross_sell_id":null,"up_sell_id":null,"bundle_id":null,"bundle_group_id":null,"date_created":"2026-11-02T16:46:16Z","date_modified":"2026-11-02T16:46:16Z","product_id":"pdf-pro.test","order_id":"7393-GMRFY-954","name":"PDF Viewer Pro","type":"digital","quantity":1,"currency":"USD","price":49.95,"price_original":49.95,"reference_price":49.95,"reference_currency":"USD","subtotal":49.95,"subtotal_original":49.95,"discount":0,"discount_percent":0,"tax":0,"tax_original":0,"total":49.95,"total_original":49.95,"tax_rate":0,"tax_code":null,"settlement_currency":"USD","settlement_price":49.95,"settlement_price_original":49.95,"settlement_subtotal":49.95,"settlement_subtotal_original":49.95,"settlement_discount":0,"settlement_tax":0,"settlement_tax_original":0,"settlement_total":49.95,"settlement_total_original":49.95,"fulfilled":true,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription":null,"subscription_terms":null,"shipments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/items/1/shipments","license":null,"download":"https://api.comecero.com/api/v1/downloads/0093717990011DlR4kQp2a","meta":null}],"shipping_item":null,"customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","cart":"https://api.comecero.com/api/v1/carts/0093717976083CaO5bXdLA","payments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/payments","payment":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/payments","subscription":null,"refunds":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/refunds","fee_summary":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/fee_summary","invoice":null,"promotions":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/promotions","shipments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/shipments","meta":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"order:fulfilled":{"post":{"operationId":"event_order_fulfilled","summary":"Order fulfilled","description":"Fires when the last unfulfilled item on the order is marked fulfilled, so `fulfilled` becomes `true`. The body is an event object with the order in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"order:fulfilled"},"data":{"description":"The order the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/order"}]}}}]},"examples":{"event":{"summary":"A order:fulfilled event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"order:fulfilled","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"order","url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954","order_id":"7393-GMRFY-954","date_created":"2026-11-02T16:46:16Z","date_modified":"2026-11-02T16:46:38Z","test":true,"account_id":"AB1234","payment_status":"completed","fulfilled":true,"currency":"USD","subtotal":49.95,"subtotal_original":49.95,"shipping":0,"shipping_original":0,"discount":0,"item_discounts":0,"total_discounts":0,"total_discounts_percent":0,"tax":0,"tax_original":0,"total":49.95,"total_original":49.95,"tax_inclusive":false,"discount_on_gross":false,"settlement_currency":"USD","settlement_subtotal":49.95,"settlement_subtotal_original":49.95,"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":49.95,"settlement_total_original":49.95,"customer_ip_address":"203.0.113.24","customer_ip_country":"US","referrer":null,"affiliate_id":null,"promotion_code":null,"items_count":1,"items_quantity":1,"items":[{"object":"order_item","url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/items/1","item_id":"1","cross_sell_id":null,"up_sell_id":null,"bundle_id":null,"bundle_group_id":null,"date_created":"2026-11-02T16:46:16Z","date_modified":"2026-11-02T16:46:16Z","product_id":"pdf-pro.test","order_id":"7393-GMRFY-954","name":"PDF Viewer Pro","type":"digital","quantity":1,"currency":"USD","price":49.95,"price_original":49.95,"reference_price":49.95,"reference_currency":"USD","subtotal":49.95,"subtotal_original":49.95,"discount":0,"discount_percent":0,"tax":0,"tax_original":0,"total":49.95,"total_original":49.95,"tax_rate":0,"tax_code":null,"settlement_currency":"USD","settlement_price":49.95,"settlement_price_original":49.95,"settlement_subtotal":49.95,"settlement_subtotal_original":49.95,"settlement_discount":0,"settlement_tax":0,"settlement_tax_original":0,"settlement_total":49.95,"settlement_total_original":49.95,"fulfilled":true,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription":null,"subscription_terms":null,"shipments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/items/1/shipments","license":null,"download":"https://api.comecero.com/api/v1/downloads/0093717990011DlR4kQp2a","meta":null}],"shipping_item":null,"customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","cart":"https://api.comecero.com/api/v1/carts/0093717976083CaO5bXdLA","payments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/payments","payment":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/payments","subscription":null,"refunds":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/refunds","fee_summary":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/fee_summary","invoice":null,"promotions":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/promotions","shipments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/shipments","meta":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"order:licenses_assigned":{"post":{"operationId":"event_order_licenses_assigned","summary":"Order licenses assigned","description":"Fires when every item in the order that needs a license key has one, for example after your license server answered. The body is an event object with the order in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"order:licenses_assigned"},"data":{"description":"The order the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/order"}]}}}]},"examples":{"event":{"summary":"A order:licenses_assigned event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"order:licenses_assigned","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"order","url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954","order_id":"7393-GMRFY-954","date_created":"2026-11-02T16:46:16Z","date_modified":"2026-11-02T16:46:38Z","test":true,"account_id":"AB1234","payment_status":"completed","fulfilled":true,"currency":"USD","subtotal":49.95,"subtotal_original":49.95,"shipping":0,"shipping_original":0,"discount":0,"item_discounts":0,"total_discounts":0,"total_discounts_percent":0,"tax":0,"tax_original":0,"total":49.95,"total_original":49.95,"tax_inclusive":false,"discount_on_gross":false,"settlement_currency":"USD","settlement_subtotal":49.95,"settlement_subtotal_original":49.95,"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":49.95,"settlement_total_original":49.95,"customer_ip_address":"203.0.113.24","customer_ip_country":"US","referrer":null,"affiliate_id":null,"promotion_code":null,"items_count":1,"items_quantity":1,"items":[{"object":"order_item","url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/items/1","item_id":"1","cross_sell_id":null,"up_sell_id":null,"bundle_id":null,"bundle_group_id":null,"date_created":"2026-11-02T16:46:16Z","date_modified":"2026-11-02T16:46:16Z","product_id":"pdf-pro.test","order_id":"7393-GMRFY-954","name":"PDF Viewer Pro","type":"digital","quantity":1,"currency":"USD","price":49.95,"price_original":49.95,"reference_price":49.95,"reference_currency":"USD","subtotal":49.95,"subtotal_original":49.95,"discount":0,"discount_percent":0,"tax":0,"tax_original":0,"total":49.95,"total_original":49.95,"tax_rate":0,"tax_code":null,"settlement_currency":"USD","settlement_price":49.95,"settlement_price_original":49.95,"settlement_subtotal":49.95,"settlement_subtotal_original":49.95,"settlement_discount":0,"settlement_tax":0,"settlement_tax_original":0,"settlement_total":49.95,"settlement_total_original":49.95,"fulfilled":true,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription":null,"subscription_terms":null,"shipments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/items/1/shipments","license":null,"download":"https://api.comecero.com/api/v1/downloads/0093717990011DlR4kQp2a","meta":null}],"shipping_item":null,"customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","cart":"https://api.comecero.com/api/v1/carts/0093717976083CaO5bXdLA","payments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/payments","payment":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/payments","subscription":null,"refunds":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/refunds","fee_summary":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/fee_summary","invoice":null,"promotions":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/promotions","shipments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/shipments","meta":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"payment:completed":{"post":{"operationId":"event_payment_completed","summary":"Payment completed","description":"Fires when a payment's status becomes `completed`: when it is made as a sale, or when an authorization is captured (together with `payment:captured_success`). The body is an event object with the payment in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"payment:completed"},"data":{"description":"The payment the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/payment"}]}}}]},"examples":{"event":{"summary":"A payment:completed event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"payment:completed","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"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}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"payment:created_success":{"post":{"operationId":"event_payment_created_success","summary":"Payment succeeded","description":"Fires when a payment attempt succeeds. Its `status` is `completed` for a sale or `pending` for an authorization to capture later. The body is an event object with the payment in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"payment:created_success"},"data":{"description":"The payment the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/payment"}]}}}]},"examples":{"event":{"summary":"A payment:created_success event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"payment:created_success","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"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}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"payment:created_failure":{"post":{"operationId":"event_payment_created_failure","summary":"Payment failed","description":"Fires when a payment attempt fails, for example a decline. The `data` holds the failed payment with its response code and message. The body is an event object with the payment in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"payment:created_failure"},"data":{"description":"The payment the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/payment"}]}}}]},"examples":{"event":{"summary":"A payment:created_failure event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"payment:created_failure","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"payment","url":"https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC","payment_id":"0090460891496PyrYzd9DC","account_id":"AB1234","success":true,"status":"failed","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}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"payment:captured_success":{"post":{"operationId":"event_payment_captured_success","summary":"Payment captured","description":"Fires when an authorized payment is captured. `payment:completed` fires with it. The body is an event object with the payment in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"payment:captured_success"},"data":{"description":"The payment the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/payment"}]}}}]},"examples":{"event":{"summary":"A payment:captured_success event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"payment:captured_success","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"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}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"payment:captured_failure":{"post":{"operationId":"event_payment_captured_failure","summary":"Payment capture failed","description":"Fires when capturing an authorized payment fails. The body is an event object with the payment in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"payment:captured_failure"},"data":{"description":"The payment the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/payment"}]}}}]},"examples":{"event":{"summary":"A payment:captured_failure event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"payment:captured_failure","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"payment","url":"https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC","payment_id":"0090460891496PyrYzd9DC","account_id":"AB1234","success":true,"status":"pending","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}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"payment:voided":{"post":{"operationId":"event_payment_voided","summary":"Payment voided","description":"Fires when an authorized payment is voided, so no money is taken. It also fires when Comecero finds an Amazon Pay capture with no order and voids it. The body is an event object with the payment in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"payment:voided"},"data":{"description":"The payment the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/payment"}]}}}]},"examples":{"event":{"summary":"A payment:voided event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"payment:voided","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"payment","url":"https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC","payment_id":"0090460891496PyrYzd9DC","account_id":"AB1234","success":true,"status":"cancelled","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}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"product:created":{"post":{"operationId":"event_product_created","summary":"Product created","description":"Fires when a product is created. The body is an event object with the product in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"product:created"},"data":{"description":"The product the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/product"}]}}}]},"examples":{"event":{"summary":"A product:created event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"product:created","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"product","url":"https://api.comecero.com/api/v1/products/widget.test","product_id":"widget.test","date_created":"2026-11-02T14:36:52Z","date_modified":"2026-11-02T14:36:52Z","test":true,"account_id":"AB1234","name":"Widget","price":49.95,"currency":"USD","compare_at_price":59.95,"type":"physical","description":"A simple widget for everyday use.","headline":"The widget you will use every day","tax_code":null,"prices":[{"price":49.95,"currency":"USD"},{"price":45.95,"currency":"EUR"}],"compare_at_prices":[{"price":59.95,"currency":"USD"}],"volume_prices":[{"low":10,"high":null,"prices":[{"price":39.95,"currency":"USD"}]}],"effective_volume_prices":[{"low":1,"high":9,"price":49.95,"currency":"USD","discount_percent":0,"discount_amount":0},{"low":10,"high":null,"price":39.95,"currency":"USD","discount_percent":0.2,"discount_amount":10}],"inventory":{"in_stock":true,"quantity":120,"allow_oversells":false,"low_quantity_notification":10},"bundle_items":[],"weight":{"amount":3,"unit":"lb"},"active":true,"deleted":false,"hidden":false,"date_deleted":null,"file":null,"has_file":false,"license_service":null,"has_license_service":false,"subscription_plan":null,"subscription_terms":null,"images":[{"object":"image","url":"https://api.comecero.com/api/v1/images/0099844605810ImLAMbo73","image_id":"0099844605810ImLAMbo73","date_created":"2026-11-02T14:36:45Z","date_modified":"2026-11-02T14:36:45Z","test":true,"account_id":"AB1234","link":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/widget.png","link_small":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sm_widget.png","link_medium":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/md_widget.png","link_large":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/lg_widget.png","link_square":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sq_widget.png","filename":"widget.png"}],"video_url":null,"related_products":"https://api.comecero.com/api/v1/products/widget.test/related_products","subscription_change_products":"https://api.comecero.com/api/v1/products/widget.test/subscription_change_products","subscription_term_change_products":"https://api.comecero.com/api/v1/products/widget.test/subscription_term_change_products","meta":null,"translations":{"de":{"name":"Widget","headline":"Das Widget fur jeden Tag","description":"Ein einfaches Widget fur jeden Tag."}}}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"product:modified":{"post":{"operationId":"event_product_modified","summary":"Product modified","description":"Fires when a product is changed. The body is an event object with the product in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"product:modified"},"data":{"description":"The product the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/product"}]}}}]},"examples":{"event":{"summary":"A product:modified event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"product:modified","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"product","url":"https://api.comecero.com/api/v1/products/widget.test","product_id":"widget.test","date_created":"2026-11-02T14:36:52Z","date_modified":"2026-11-02T14:36:52Z","test":true,"account_id":"AB1234","name":"Widget","price":49.95,"currency":"USD","compare_at_price":59.95,"type":"physical","description":"A simple widget for everyday use.","headline":"The widget you will use every day","tax_code":null,"prices":[{"price":49.95,"currency":"USD"},{"price":45.95,"currency":"EUR"}],"compare_at_prices":[{"price":59.95,"currency":"USD"}],"volume_prices":[{"low":10,"high":null,"prices":[{"price":39.95,"currency":"USD"}]}],"effective_volume_prices":[{"low":1,"high":9,"price":49.95,"currency":"USD","discount_percent":0,"discount_amount":0},{"low":10,"high":null,"price":39.95,"currency":"USD","discount_percent":0.2,"discount_amount":10}],"inventory":{"in_stock":true,"quantity":120,"allow_oversells":false,"low_quantity_notification":10},"bundle_items":[],"weight":{"amount":3,"unit":"lb"},"active":true,"deleted":false,"hidden":false,"date_deleted":null,"file":null,"has_file":false,"license_service":null,"has_license_service":false,"subscription_plan":null,"subscription_terms":null,"images":[{"object":"image","url":"https://api.comecero.com/api/v1/images/0099844605810ImLAMbo73","image_id":"0099844605810ImLAMbo73","date_created":"2026-11-02T14:36:45Z","date_modified":"2026-11-02T14:36:45Z","test":true,"account_id":"AB1234","link":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/widget.png","link_small":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sm_widget.png","link_medium":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/md_widget.png","link_large":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/lg_widget.png","link_square":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sq_widget.png","filename":"widget.png"}],"video_url":null,"related_products":"https://api.comecero.com/api/v1/products/widget.test/related_products","subscription_change_products":"https://api.comecero.com/api/v1/products/widget.test/subscription_change_products","subscription_term_change_products":"https://api.comecero.com/api/v1/products/widget.test/subscription_term_change_products","meta":null,"translations":{"de":{"name":"Widget","headline":"Das Widget fur jeden Tag","description":"Ein einfaches Widget fur jeden Tag."}}}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"product:deleted":{"post":{"operationId":"event_product_deleted","summary":"Product deleted","description":"Fires when a product is deleted. The `data` is the product as it was. The body is an event object with the product in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"product:deleted"},"data":{"description":"The product the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/product"}]}}}]},"examples":{"event":{"summary":"A product:deleted event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"product:deleted","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"product","url":"https://api.comecero.com/api/v1/products/widget.test","product_id":"widget.test","date_created":"2026-11-02T14:36:52Z","date_modified":"2026-11-02T14:36:52Z","test":true,"account_id":"AB1234","name":"Widget","price":49.95,"currency":"USD","compare_at_price":59.95,"type":"physical","description":"A simple widget for everyday use.","headline":"The widget you will use every day","tax_code":null,"prices":[{"price":49.95,"currency":"USD"},{"price":45.95,"currency":"EUR"}],"compare_at_prices":[{"price":59.95,"currency":"USD"}],"volume_prices":[{"low":10,"high":null,"prices":[{"price":39.95,"currency":"USD"}]}],"effective_volume_prices":[{"low":1,"high":9,"price":49.95,"currency":"USD","discount_percent":0,"discount_amount":0},{"low":10,"high":null,"price":39.95,"currency":"USD","discount_percent":0.2,"discount_amount":10}],"inventory":{"in_stock":true,"quantity":120,"allow_oversells":false,"low_quantity_notification":10},"bundle_items":[],"weight":{"amount":3,"unit":"lb"},"active":true,"deleted":false,"hidden":false,"date_deleted":null,"file":null,"has_file":false,"license_service":null,"has_license_service":false,"subscription_plan":null,"subscription_terms":null,"images":[{"object":"image","url":"https://api.comecero.com/api/v1/images/0099844605810ImLAMbo73","image_id":"0099844605810ImLAMbo73","date_created":"2026-11-02T14:36:45Z","date_modified":"2026-11-02T14:36:45Z","test":true,"account_id":"AB1234","link":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/widget.png","link_small":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sm_widget.png","link_medium":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/md_widget.png","link_large":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/lg_widget.png","link_square":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sq_widget.png","filename":"widget.png"}],"video_url":null,"related_products":"https://api.comecero.com/api/v1/products/widget.test/related_products","subscription_change_products":"https://api.comecero.com/api/v1/products/widget.test/subscription_change_products","subscription_term_change_products":"https://api.comecero.com/api/v1/products/widget.test/subscription_term_change_products","meta":null,"translations":{"de":{"name":"Widget","headline":"Das Widget fur jeden Tag","description":"Ein einfaches Widget fur jeden Tag."}}}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"product:low_inventory":{"post":{"operationId":"event_product_low_inventory","summary":"Product low on inventory","description":"Fires when an order takes a product's inventory from above to at or below its low inventory level (the product's `low_quantity_notification`, or the account default in fulfillment settings). New accounts get an email subscription to this event by default. The body is an event object with the product in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"product:low_inventory"},"data":{"description":"The product the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/product"}]}}}]},"examples":{"event":{"summary":"A product:low_inventory event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"product:low_inventory","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"product","url":"https://api.comecero.com/api/v1/products/widget.test","product_id":"widget.test","date_created":"2026-11-02T14:36:52Z","date_modified":"2026-11-02T14:36:52Z","test":true,"account_id":"AB1234","name":"Widget","price":49.95,"currency":"USD","compare_at_price":59.95,"type":"physical","description":"A simple widget for everyday use.","headline":"The widget you will use every day","tax_code":null,"prices":[{"price":49.95,"currency":"USD"},{"price":45.95,"currency":"EUR"}],"compare_at_prices":[{"price":59.95,"currency":"USD"}],"volume_prices":[{"low":10,"high":null,"prices":[{"price":39.95,"currency":"USD"}]}],"effective_volume_prices":[{"low":1,"high":9,"price":49.95,"currency":"USD","discount_percent":0,"discount_amount":0},{"low":10,"high":null,"price":39.95,"currency":"USD","discount_percent":0.2,"discount_amount":10}],"inventory":{"in_stock":true,"quantity":120,"allow_oversells":false,"low_quantity_notification":10},"bundle_items":[],"weight":{"amount":3,"unit":"lb"},"active":true,"deleted":false,"hidden":false,"date_deleted":null,"file":null,"has_file":false,"license_service":null,"has_license_service":false,"subscription_plan":null,"subscription_terms":null,"images":[{"object":"image","url":"https://api.comecero.com/api/v1/images/0099844605810ImLAMbo73","image_id":"0099844605810ImLAMbo73","date_created":"2026-11-02T14:36:45Z","date_modified":"2026-11-02T14:36:45Z","test":true,"account_id":"AB1234","link":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/widget.png","link_small":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sm_widget.png","link_medium":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/md_widget.png","link_large":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/lg_widget.png","link_square":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sq_widget.png","filename":"widget.png"}],"video_url":null,"related_products":"https://api.comecero.com/api/v1/products/widget.test/related_products","subscription_change_products":"https://api.comecero.com/api/v1/products/widget.test/subscription_change_products","subscription_term_change_products":"https://api.comecero.com/api/v1/products/widget.test/subscription_term_change_products","meta":null,"translations":{"de":{"name":"Widget","headline":"Das Widget fur jeden Tag","description":"Ein einfaches Widget fur jeden Tag."}}}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"refund:created_success":{"post":{"operationId":"event_refund_created_success","summary":"Refund succeeded","description":"Fires when a refund completes. The body is an event object with the refund in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"refund:created_success"},"data":{"description":"The refund the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/refund"}]}}}]},"examples":{"event":{"summary":"A refund:created_success event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"refund:created_success","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"refund","url":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5","refund_id":"0090374314462Rec3PffZ5","account_id":"AB1234","success":true,"status":"completed","reference":null,"date_created":"2026-11-03T10:12:40Z","date_modified":"2026-11-03T10:12:41Z","date_completed":"2026-11-03T10:12:41Z","test":true,"currency":"USD","subtotal":49.95,"shipping":0,"tax":0,"total":49.95,"reason":"Customer request","apply_to_balance":false,"is_chargeback":false,"record_only":false,"record_only_memo":null,"response_code":"OK","response_message":"OK","gateway_transaction_id":"re_test_3PffZ5","gateway_error_code":null,"gateway_error_message":null,"gateway":"https://api.comecero.com/api/v1/gateways/0089584408915Gtf5AsdJ8","comments":null,"payment_method":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/payment_method","settlement_currency":"USD","settlement_subtotal":49.95,"settlement_shipping":0,"settlement_tax":0,"settlement_total":49.95,"fx_rate":1,"reporting_currency":"USD","reporting_subtotal":49.95,"reporting_shipping":0,"reporting_tax":0,"reporting_total":49.95,"reporting_fx_rate":1,"items":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/items","customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","order":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954","payment":"https://api.comecero.com/api/v1/payments/0093717991362PyRYN1qc6","invoice":null,"fees":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fees","fee_summary":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fee_summary","commissions":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/commissions","meta":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"refund:created_failure":{"post":{"operationId":"event_refund_created_failure","summary":"Refund failed","description":"Fires when a refund fails. It also fires when a refund that had completed is reversed later by the payment provider, after `refund:created_success` was sent for it. The body is an event object with the refund in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"refund:created_failure"},"data":{"description":"The refund the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/refund"}]}}}]},"examples":{"event":{"summary":"A refund:created_failure event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"refund:created_failure","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"refund","url":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5","refund_id":"0090374314462Rec3PffZ5","account_id":"AB1234","success":true,"status":"completed","reference":null,"date_created":"2026-11-03T10:12:40Z","date_modified":"2026-11-03T10:12:41Z","date_completed":"2026-11-03T10:12:41Z","test":true,"currency":"USD","subtotal":49.95,"shipping":0,"tax":0,"total":49.95,"reason":"Customer request","apply_to_balance":false,"is_chargeback":false,"record_only":false,"record_only_memo":null,"response_code":"OK","response_message":"OK","gateway_transaction_id":"re_test_3PffZ5","gateway_error_code":null,"gateway_error_message":null,"gateway":"https://api.comecero.com/api/v1/gateways/0089584408915Gtf5AsdJ8","comments":null,"payment_method":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/payment_method","settlement_currency":"USD","settlement_subtotal":49.95,"settlement_shipping":0,"settlement_tax":0,"settlement_total":49.95,"fx_rate":1,"reporting_currency":"USD","reporting_subtotal":49.95,"reporting_shipping":0,"reporting_tax":0,"reporting_total":49.95,"reporting_fx_rate":1,"items":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/items","customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","order":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954","payment":"https://api.comecero.com/api/v1/payments/0093717991362PyRYN1qc6","invoice":null,"fees":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fees","fee_summary":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fee_summary","commissions":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/commissions","meta":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"refund:deleted":{"post":{"operationId":"event_refund_deleted","summary":"Refund deleted","description":"Fires when a refund record is deleted, such as a chargeback entered by mistake. The `data` is the refund as it was. The body is an event object with the refund in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"refund:deleted"},"data":{"description":"The refund the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/refund"}]}}}]},"examples":{"event":{"summary":"A refund:deleted event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"refund:deleted","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"refund","url":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5","refund_id":"0090374314462Rec3PffZ5","account_id":"AB1234","success":true,"status":"completed","reference":null,"date_created":"2026-11-03T10:12:40Z","date_modified":"2026-11-03T10:12:41Z","date_completed":"2026-11-03T10:12:41Z","test":true,"currency":"USD","subtotal":49.95,"shipping":0,"tax":0,"total":49.95,"reason":"Customer request","apply_to_balance":false,"is_chargeback":false,"record_only":false,"record_only_memo":null,"response_code":"OK","response_message":"OK","gateway_transaction_id":"re_test_3PffZ5","gateway_error_code":null,"gateway_error_message":null,"gateway":"https://api.comecero.com/api/v1/gateways/0089584408915Gtf5AsdJ8","comments":null,"payment_method":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/payment_method","settlement_currency":"USD","settlement_subtotal":49.95,"settlement_shipping":0,"settlement_tax":0,"settlement_total":49.95,"fx_rate":1,"reporting_currency":"USD","reporting_subtotal":49.95,"reporting_shipping":0,"reporting_tax":0,"reporting_total":49.95,"reporting_fx_rate":1,"items":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/items","customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","order":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954","payment":"https://api.comecero.com/api/v1/payments/0093717991362PyRYN1qc6","invoice":null,"fees":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fees","fee_summary":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fee_summary","commissions":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/commissions","meta":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"user:created":{"post":{"operationId":"event_user_created","summary":"User created","description":"Fires when a user is added to your account. Known issue: core sends an empty `data` object for this event, so get the user by id from the API. The body is an event object with the user in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"user:created"},"data":{"type":"object","description":"Known issue: core sends an empty object here. Get the user by id from the API."}}}]},"examples":{"event":{"summary":"A user:created event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"user:created","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"user:modified":{"post":{"operationId":"event_user_modified","summary":"User modified","description":"Fires when a user is changed. Known issue: core sends an empty `data` object for this event, so get the user by id from the API. The body is an event object with the user in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"user:modified"},"data":{"type":"object","description":"Known issue: core sends an empty object here. Get the user by id from the API."}}}]},"examples":{"event":{"summary":"A user:modified event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"user:modified","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"shipment:created":{"post":{"operationId":"event_shipment_created","summary":"Shipment created","description":"Fires when a shipment is created on an order. The body is an event object with the shipment in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"shipment:created"},"data":{"description":"The shipment the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/shipment"}]}}}]},"examples":{"event":{"summary":"A shipment:created event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"shipment:created","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"shipment","url":"https://api.comecero.com/api/v1/shipments/0093718200417ShQ2xN8kL","shipment_id":"0093718200417ShQ2xN8kL","date_created":"2026-11-04T09:30:00Z","date_modified":"2026-11-04T09:30:00Z","date_shipped":"2026-11-04T09:30:00Z","test":true,"account_id":"AB1234","items":[{"object":"shipment_item","item_id":"1","product_id":"lens-cloth.test","name":"Lens cleaning cloth","quantity":2,"product":"https://api.comecero.com/api/v1/products/lens-cloth.test"}],"order":"https://api.comecero.com/api/v1/orders/2979-KXVST-674","courier":"UPS","tracking_number":"1Z999AA10123456784","tracking_url":"http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784","notifications":"https://api.comecero.com/api/v1/shipments/0093718200417ShQ2xN8kL/notifications","meta":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"shipment:modified":{"post":{"operationId":"event_shipment_modified","summary":"Shipment modified","description":"Fires when a shipment is changed, for example when tracking is added. The body is an event object with the shipment in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"shipment:modified"},"data":{"description":"The shipment the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/shipment"}]}}}]},"examples":{"event":{"summary":"A shipment:modified event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"shipment:modified","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"shipment","url":"https://api.comecero.com/api/v1/shipments/0093718200417ShQ2xN8kL","shipment_id":"0093718200417ShQ2xN8kL","date_created":"2026-11-04T09:30:00Z","date_modified":"2026-11-04T09:30:00Z","date_shipped":"2026-11-04T09:30:00Z","test":true,"account_id":"AB1234","items":[{"object":"shipment_item","item_id":"1","product_id":"lens-cloth.test","name":"Lens cleaning cloth","quantity":2,"product":"https://api.comecero.com/api/v1/products/lens-cloth.test"}],"order":"https://api.comecero.com/api/v1/orders/2979-KXVST-674","courier":"UPS","tracking_number":"1Z999AA10123456784","tracking_url":"http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784","notifications":"https://api.comecero.com/api/v1/shipments/0093718200417ShQ2xN8kL/notifications","meta":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"shipment:deleted":{"post":{"operationId":"event_shipment_deleted","summary":"Shipment deleted","description":"Fires when a shipment is deleted. The `data` is the shipment as it was. The body is an event object with the shipment in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"shipment:deleted"},"data":{"description":"The shipment the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/shipment"}]}}}]},"examples":{"event":{"summary":"A shipment:deleted event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"shipment:deleted","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"shipment","url":"https://api.comecero.com/api/v1/shipments/0093718200417ShQ2xN8kL","shipment_id":"0093718200417ShQ2xN8kL","date_created":"2026-11-04T09:30:00Z","date_modified":"2026-11-04T09:30:00Z","date_shipped":"2026-11-04T09:30:00Z","test":true,"account_id":"AB1234","items":[{"object":"shipment_item","item_id":"1","product_id":"lens-cloth.test","name":"Lens cleaning cloth","quantity":2,"product":"https://api.comecero.com/api/v1/products/lens-cloth.test"}],"order":"https://api.comecero.com/api/v1/orders/2979-KXVST-674","courier":"UPS","tracking_number":"1Z999AA10123456784","tracking_url":"http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784","notifications":"https://api.comecero.com/api/v1/shipments/0093718200417ShQ2xN8kL/notifications","meta":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"subscription:created":{"post":{"operationId":"event_subscription_created","summary":"Subscription created","description":"Fires when a subscription is created, usually by the first payment for a subscription product. The body is an event object with the subscription in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"subscription:created"},"data":{"description":"The subscription the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/subscription"}]}}}]},"examples":{"event":{"summary":"A subscription:created event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"subscription:created","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"subscription","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_id":"0093799318129SuLByRPW8","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-11-02T15:21:31Z","test":true,"account_id":"AB1234","status":"active","in_grace_period":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"billing_count":2,"end_at_billing_count":null,"currency":"USD","items":[{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}],"shipping_method_id":null,"date_trial_start":null,"date_trial_end":null,"date_current_period_start":"2026-11-02T15:21:28Z","date_current_period_end":"2026-12-02T15:21:28Z","date_next_renewal_notification":"2026-11-29T15:21:28Z","date_cancelled":null,"cancellation_reason":null,"cancel_at_current_period_end":false,"date_ended":null,"add_at_current_period_end":[],"subscription_plan":"https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C","customer":"https://api.comecero.com/api/v1/customers/0093799288003CuGOip8X9","invoices":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/invoices","history":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/history","meta":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"subscription:modified":{"post":{"operationId":"event_subscription_modified","summary":"Subscription modified","description":"Fires when a subscription is changed: by an update, by an item being added, changed or cancelled, or by a cancellation. The body is an event object with the subscription in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"subscription:modified"},"data":{"description":"The subscription the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/subscription"}]}}}]},"examples":{"event":{"summary":"A subscription:modified event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"subscription:modified","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"subscription","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_id":"0093799318129SuLByRPW8","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-11-02T15:21:31Z","test":true,"account_id":"AB1234","status":"active","in_grace_period":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"billing_count":2,"end_at_billing_count":null,"currency":"USD","items":[{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}],"shipping_method_id":null,"date_trial_start":null,"date_trial_end":null,"date_current_period_start":"2026-11-02T15:21:28Z","date_current_period_end":"2026-12-02T15:21:28Z","date_next_renewal_notification":"2026-11-29T15:21:28Z","date_cancelled":null,"cancellation_reason":null,"cancel_at_current_period_end":false,"date_ended":null,"add_at_current_period_end":[],"subscription_plan":"https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C","customer":"https://api.comecero.com/api/v1/customers/0093799288003CuGOip8X9","invoices":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/invoices","history":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/history","meta":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"subscription:cancelled":{"post":{"operationId":"event_subscription_cancelled","summary":"Subscription cancelled","description":"Fires when a subscription is cancelled and ends now (not at the end of the period). The body is an event object with the subscription in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"subscription:cancelled"},"data":{"description":"The subscription the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/subscription"}]}}}]},"examples":{"event":{"summary":"A subscription:cancelled event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"subscription:cancelled","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"subscription","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_id":"0093799318129SuLByRPW8","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-11-02T15:21:31Z","test":true,"account_id":"AB1234","status":"cancelled","in_grace_period":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"billing_count":2,"end_at_billing_count":null,"currency":"USD","items":[{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}],"shipping_method_id":null,"date_trial_start":null,"date_trial_end":null,"date_current_period_start":"2026-11-02T15:21:28Z","date_current_period_end":"2026-12-02T15:21:28Z","date_next_renewal_notification":"2026-11-29T15:21:28Z","date_cancelled":null,"cancellation_reason":null,"cancel_at_current_period_end":false,"date_ended":null,"add_at_current_period_end":[],"subscription_plan":"https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C","customer":"https://api.comecero.com/api/v1/customers/0093799288003CuGOip8X9","invoices":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/invoices","history":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/history","meta":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"subscription:cancellation_scheduled":{"post":{"operationId":"event_subscription_cancellation_scheduled","summary":"Subscription cancellation scheduled","description":"Fires when a subscription is set to cancel at the end of its current period. The body is an event object with the subscription in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"subscription:cancellation_scheduled"},"data":{"description":"The subscription the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/subscription"}]}}}]},"examples":{"event":{"summary":"A subscription:cancellation_scheduled event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"subscription:cancellation_scheduled","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"subscription","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_id":"0093799318129SuLByRPW8","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-11-02T15:21:31Z","test":true,"account_id":"AB1234","status":"active","in_grace_period":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"billing_count":2,"end_at_billing_count":null,"currency":"USD","items":[{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}],"shipping_method_id":null,"date_trial_start":null,"date_trial_end":null,"date_current_period_start":"2026-11-02T15:21:28Z","date_current_period_end":"2026-12-02T15:21:28Z","date_next_renewal_notification":"2026-11-29T15:21:28Z","date_cancelled":null,"cancellation_reason":null,"cancel_at_current_period_end":false,"date_ended":null,"add_at_current_period_end":[],"subscription_plan":"https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C","customer":"https://api.comecero.com/api/v1/customers/0093799288003CuGOip8X9","invoices":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/invoices","history":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/history","meta":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"subscription:cancellation_unscheduled":{"post":{"operationId":"event_subscription_cancellation_unscheduled","summary":"Subscription cancellation unscheduled","description":"Fires when a scheduled cancellation is taken back, so the subscription renews again. The body is an event object with the subscription in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"subscription:cancellation_unscheduled"},"data":{"description":"The subscription the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/subscription"}]}}}]},"examples":{"event":{"summary":"A subscription:cancellation_unscheduled event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"subscription:cancellation_unscheduled","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"subscription","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_id":"0093799318129SuLByRPW8","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-11-02T15:21:31Z","test":true,"account_id":"AB1234","status":"active","in_grace_period":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"billing_count":2,"end_at_billing_count":null,"currency":"USD","items":[{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}],"shipping_method_id":null,"date_trial_start":null,"date_trial_end":null,"date_current_period_start":"2026-11-02T15:21:28Z","date_current_period_end":"2026-12-02T15:21:28Z","date_next_renewal_notification":"2026-11-29T15:21:28Z","date_cancelled":null,"cancellation_reason":null,"cancel_at_current_period_end":false,"date_ended":null,"add_at_current_period_end":[],"subscription_plan":"https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C","customer":"https://api.comecero.com/api/v1/customers/0093799288003CuGOip8X9","invoices":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/invoices","history":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/history","meta":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"subscription:completed":{"post":{"operationId":"event_subscription_completed","summary":"Subscription completed","description":"Fires when a subscription ends because it reached its last billing (its plan's end billing count). The body is an event object with the subscription in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"subscription:completed"},"data":{"description":"The subscription the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/subscription"}]}}}]},"examples":{"event":{"summary":"A subscription:completed event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"subscription:completed","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"subscription","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_id":"0093799318129SuLByRPW8","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-11-02T15:21:31Z","test":true,"account_id":"AB1234","status":"active","in_grace_period":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"billing_count":2,"end_at_billing_count":null,"currency":"USD","items":[{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}],"shipping_method_id":null,"date_trial_start":null,"date_trial_end":null,"date_current_period_start":"2026-11-02T15:21:28Z","date_current_period_end":"2026-12-02T15:21:28Z","date_next_renewal_notification":"2026-11-29T15:21:28Z","date_cancelled":null,"cancellation_reason":null,"cancel_at_current_period_end":false,"date_ended":null,"add_at_current_period_end":[],"subscription_plan":"https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C","customer":"https://api.comecero.com/api/v1/customers/0093799288003CuGOip8X9","invoices":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/invoices","history":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/history","meta":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"subscription:converted":{"post":{"operationId":"event_subscription_converted","summary":"Subscription converted","description":"Fires when a subscription in a trial makes its first paid renewal. The body is an event object with the subscription in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"subscription:converted"},"data":{"description":"The subscription the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/subscription"}]}}}]},"examples":{"event":{"summary":"A subscription:converted event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"subscription:converted","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"subscription","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_id":"0093799318129SuLByRPW8","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-11-02T15:21:31Z","test":true,"account_id":"AB1234","status":"active","in_grace_period":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"billing_count":2,"end_at_billing_count":null,"currency":"USD","items":[{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}],"shipping_method_id":null,"date_trial_start":null,"date_trial_end":null,"date_current_period_start":"2026-11-02T15:21:28Z","date_current_period_end":"2026-12-02T15:21:28Z","date_next_renewal_notification":"2026-11-29T15:21:28Z","date_cancelled":null,"cancellation_reason":null,"cancel_at_current_period_end":false,"date_ended":null,"add_at_current_period_end":[],"subscription_plan":"https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C","customer":"https://api.comecero.com/api/v1/customers/0093799288003CuGOip8X9","invoices":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/invoices","history":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/history","meta":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"subscription_item:added":{"post":{"operationId":"event_subscription_item_added","summary":"Subscription item added","description":"Fires when an item is added to a subscription. The body is an event object with the subscription item in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"subscription_item:added"},"data":{"description":"The subscription item the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/subscription_item"}]}}}]},"examples":{"event":{"summary":"A subscription_item:added event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"subscription_item:added","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"subscription_item:cancelled":{"post":{"operationId":"event_subscription_item_cancelled","summary":"Subscription item cancelled","description":"Fires when an item on a subscription is cancelled and ends now. The body is an event object with the subscription item in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"subscription_item:cancelled"},"data":{"description":"The subscription item the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/subscription_item"}]}}}]},"examples":{"event":{"summary":"A subscription_item:cancelled event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"subscription_item:cancelled","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"subscription_item:cancellation_scheduled":{"post":{"operationId":"event_subscription_item_cancellation_scheduled","summary":"Subscription item cancellation scheduled","description":"Fires when an item on a subscription is set to cancel at the end of the current period. The body is an event object with the subscription item in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"subscription_item:cancellation_scheduled"},"data":{"description":"The subscription item the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/subscription_item"}]}}}]},"examples":{"event":{"summary":"A subscription_item:cancellation_scheduled event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"subscription_item:cancellation_scheduled","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"subscription_item:cancellation_unscheduled":{"post":{"operationId":"event_subscription_item_cancellation_unscheduled","summary":"Subscription item cancellation unscheduled","description":"Fires when a scheduled cancellation of an item is taken back. The body is an event object with the subscription item in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"subscription_item:cancellation_unscheduled"},"data":{"description":"The subscription item the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/subscription_item"}]}}}]},"examples":{"event":{"summary":"A subscription_item:cancellation_unscheduled event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"subscription_item:cancellation_unscheduled","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"subscription_item:modified":{"post":{"operationId":"event_subscription_item_modified","summary":"Subscription item modified","description":"Fires when an item on a subscription is changed, for example its product, price or quantity. The body is an event object with the subscription item in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"subscription_item:modified"},"data":{"description":"The subscription item the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/subscription_item"}]}}}]},"examples":{"event":{"summary":"A subscription_item:modified event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"subscription_item:modified","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"subscription:renewal_success":{"post":{"operationId":"event_subscription_renewal_success","summary":"Subscription renewed","description":"Fires when a renewal payment succeeds. It does not fire for the first payment of a subscription. The body is an event object with the subscription in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"subscription:renewal_success"},"data":{"description":"The subscription the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/subscription"}]}}}]},"examples":{"event":{"summary":"A subscription:renewal_success event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"subscription:renewal_success","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"subscription","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_id":"0093799318129SuLByRPW8","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-11-02T15:21:31Z","test":true,"account_id":"AB1234","status":"active","in_grace_period":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"billing_count":2,"end_at_billing_count":null,"currency":"USD","items":[{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}],"shipping_method_id":null,"date_trial_start":null,"date_trial_end":null,"date_current_period_start":"2026-11-02T15:21:28Z","date_current_period_end":"2026-12-02T15:21:28Z","date_next_renewal_notification":"2026-11-29T15:21:28Z","date_cancelled":null,"cancellation_reason":null,"cancel_at_current_period_end":false,"date_ended":null,"add_at_current_period_end":[],"subscription_plan":"https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C","customer":"https://api.comecero.com/api/v1/customers/0093799288003CuGOip8X9","invoices":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/invoices","history":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/history","meta":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}},"subscription:renewal_failure":{"post":{"operationId":"event_subscription_renewal_failure","summary":"Subscription renewal failed","description":"Fires when a renewal payment fails. The subscription may enter its grace period. The body is an event object with the subscription in `data`.","tags":["event_subscriptions"],"security":[],"parameters":[{"$ref":"#/components/parameters/x_comecero_signature"},{"$ref":"#/components/parameters/webhook_user_agent"}],"requestBody":{"required":true,"description":"The event, sent by POST to your event subscription's `destination` as JSON (`Content-Type: application/json`), XML or an HTML table, following its `format`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/event"},{"type":"object","properties":{"type":{"const":"subscription:renewal_failure"},"data":{"description":"The subscription the event is about, shaped like a GET of it, with the event subscription's `expand`, `show` and `hide` applied.","allOf":[{"$ref":"#/components/schemas/subscription"}]}}}]},"examples":{"event":{"summary":"A subscription:renewal_failure event","value":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"subscription:renewal_failure","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"subscription","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_id":"0093799318129SuLByRPW8","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-11-02T15:21:31Z","test":true,"account_id":"AB1234","status":"active","in_grace_period":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"billing_count":2,"end_at_billing_count":null,"currency":"USD","items":[{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}],"shipping_method_id":null,"date_trial_start":null,"date_trial_end":null,"date_current_period_start":"2026-11-02T15:21:28Z","date_current_period_end":"2026-12-02T15:21:28Z","date_next_renewal_notification":"2026-11-29T15:21:28Z","date_cancelled":null,"cancellation_reason":null,"cancel_at_current_period_end":false,"date_ended":null,"add_at_current_period_end":[],"subscription_plan":"https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C","customer":"https://api.comecero.com/api/v1/customers/0093799288003CuGOip8X9","invoices":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/invoices","history":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/history","meta":null}}}}}}},"responses":{"200":{"$ref":"#/components/responses/WebhookReceived"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"A secret, trusted or limited token. See [Authentication](https://docs.comecero.com/docs/basic-concepts/authentication)."},"oauth":{"type":"oauth2","flows":{"implicit":{"authorizationUrl":"https://signin.comecero.com/oauth/authorize/","scopes":{}}}}},"parameters":{"limit":{"name":"limit","in":"query","description":"How many items to return on one page, from 1 to 100. The default is 100. A value outside 1 to 100, or one that is not a whole number, is a `400`.","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},"after_item":{"name":"after_item","in":"query","description":"For cursor-based lists, return the items after the item with this id. Use `next_page_after_item` (or follow `next_page_url`) from the page you have. You cannot send it together with `before_item` (`400`). An id that does not exist is a `404`.","required":false,"schema":{"type":"string"}},"before_item":{"name":"before_item","in":"query","description":"For cursor-based lists, return the items before the item with this id. Use `previous_page_before_item` (or follow `previous_page_url`) from the page you have. You cannot send it together with `after_item` (`400`). An id that does not exist is a `404`.","required":false,"schema":{"type":"string"}},"desc":{"name":"desc","in":"query","description":"Sort in descending order (newest, largest or last first) when `true`. The default is `false`. A value other than `true` or `false` is a `400`.","required":false,"schema":{"type":"boolean","default":false}},"date_start":{"name":"date_start","in":"query","description":"Only items on or after this date. Send ISO 8601 (`2026-11-01T00:00:00Z` or `2026-11-01T00:00:00-05:00`) or a shorthand: `2026` means the start of 2026, `2026-11` the start of November, `2026-11-01` the start of that day. A date with no offset is read in `timezone`, or in the account's time zone when you send none. It must not be after `date_end` (`400`).","required":false,"schema":{"type":"string","examples":["2026-11-01"]}},"date_end":{"name":"date_end","in":"query","description":"Only items on or before this date. Same formats as `date_start`, but a shorthand means the end of the period: `2026-11` is the last instant of November, `2026-11-30` the last instant of that day. A date with no offset is read in `timezone`, or in the account's time zone when you send none.","required":false,"schema":{"type":"string","examples":["2026-11-30"]}},"date_type":{"name":"date_type","in":"query","description":"Which date `date_start` and `date_end` filter on. The default is `date_created`. Each list names the values it supports. A value that is not one of the values below is a `400`.","required":false,"schema":{"type":"string","enum":["date_created","date_modified","date_current_period_start","date_current_period_end","date_due","date_completed","date_ended"],"default":"date_created"}},"formatted":{"name":"formatted","in":"query","description":"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](https://docs.comecero.com/docs/basic-concepts/localized-formatting).","required":false,"schema":{"type":"boolean","default":false}},"show":{"name":"show","in":"query","description":"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](https://docs.comecero.com/docs/basic-concepts/customizing-output).","required":false,"schema":{"type":"string"}},"hide":{"name":"hide","in":"query","description":"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](https://docs.comecero.com/docs/basic-concepts/customizing-output).","required":false,"schema":{"type":"string"}},"timezone":{"name":"timezone","in":"query","description":"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`.","required":false,"schema":{"type":"string","examples":["America/New_York"]}},"expand":{"name":"expand","in":"query","description":"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](https://docs.comecero.com/docs/basic-concepts/expanding-objects).","required":false,"schema":{"type":"string"}},"offset":{"name":"offset","in":"query","description":"For offset-based lists, how many items to skip before the page starts. Use `next_page_offset` or `previous_page_offset` from the page you have. A value that is not a whole number is a `400`.","required":false,"schema":{"type":"integer","minimum":0,"default":0}},"user_ip_address":{"name":"user_ip_address","in":"query","required":false,"description":"The 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.","schema":{"type":"string","examples":["203.0.113.9"]}},"user_agent":{"name":"user_agent","in":"query","required":false,"description":"The shopper's browser user agent, when your server calls with a secret token on the shopper's behalf. Comecero uses it for fraud checks. Only read for a secret token: for every other token the request's own `User-Agent` header is used.","schema":{"type":"string","examples":["Mozilla/5.0 (Macintosh; Intel Mac OS X 14_0) AppleWebKit/605.1.15"]}},"x_comecero_signature":{"name":"X-Comecero-Signature","in":"header","required":false,"description":"Proof the delivery comes from Comecero and was not changed. It is the HMAC-SHA256 of the raw request body (UTF-8), keyed with the signature key as UTF-8, written as 64 lowercase hex characters. The key is the event subscription's `signature_key`, or the account's signature key (Settings, Technical) when the subscription has none. Every account gets one when it is created, so deliveries are signed unless the key was removed. To check it, compute the HMAC over the body exactly as received, before you parse it, and compare the two strings in constant time. Reject the delivery when they differ. The signature has no timestamp, so to guard against a replayed delivery also skip any `event_id` you already handled. If you cannot check signatures, use the event only as a hint: get the object by its id from the API before you act on it.","schema":{"type":"string","pattern":"^[0-9a-f]{64}$","examples":["5f2b8c0e9a1d4f7b3c6e8a0d2f4b6c8e0a2c4e6f8b0d2f4a6c8e0b2d4f6a8c0e"]}},"webhook_user_agent":{"name":"User-Agent","in":"header","required":false,"description":"Always `Comecero-Event (+https://comecero.com)`.","schema":{"type":"string","examples":["Comecero-Event (+https://comecero.com)"]}}},"headers":{"X-Token-Expires-In-Seconds":{"description":"Seconds left until the token you called with expires, rounded to a whole number. Sent on every response to a request made with a token that expires, such as a limited token; left out when the token does not expire. Browsers may read it on cross-origin calls. Use it to get a new token, or to set how long your own token and cart cookies last.","schema":{"type":"integer","examples":[3540]}}},"schemas":{"list_cursor":{"type":"object","title":"cursor_list","description":"A page of a cursor-based list. There is no total. Move between pages with `after_item` and `before_item`, or follow `next_page_url` and `previous_page_url`, which keep your other query parameters.","required":["next_page_url","next_page_after_item","previous_page_url","previous_page_before_item","data"],"properties":{"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or `null` on the last page."},"next_page_after_item":{"type":["string","null"],"description":"The id to send as `after_item` for the next page, or `null` on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or `null` on the first page."},"previous_page_before_item":{"type":["string","null"],"description":"The id to send as `before_item` for the previous page, or `null` on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page. Only present when the request sent `after_item` or `before_item`; the first page has no `current_page_url`."},"data":{"type":"array","description":"The items on this page.","items":{"type":"object"}}}},"account_meta":{"type":"object","title":"account_meta","description":"Facts about your account that a sign-in page or dashboard needs, for the mode of the token you call with.","readOnly":true,"properties":{"account_id":{"type":"string","description":"The account ID."},"live":{"type":"boolean","description":"True when the account may take live payments."},"alias":{"type":["string","null"],"description":"The account alias."},"reporting_currency_primary":{"type":["string","null"],"description":"The main currency your reports are shown in."},"reporting_currency_secondary":{"type":["string","null"],"description":"The second currency your reports are shown in."},"oauth_authorize_url":{"type":"string","format":"uri","description":"The OAuth authorize URL of your account's sign-in page."},"oauth_callback_url":{"type":"string","format":"uri","description":"The OAuth callback URL of your account's sign-in page."},"contract_select_url":{"type":"string","format":"uri","description":"The page where an account owner picks a plan."},"signin_url":{"type":"string","format":"uri","description":"Your account's sign-in page."},"model":{"type":"string","description":"`reseller` when Comecero is the seller of record for your sales, `agent` when you are.","enum":["reseller","agent"]},"payment_currencies":{"type":"array","description":"The currencies your active gateways take payments in.","items":{"type":"object","properties":{"code":{"type":"string","description":"The ISO 4217 currency code."},"name":{"type":"string","description":"The currency's name."}}}},"default_payment_currency":{"type":["string","null"],"description":"The currency a payment uses when none is given."}},"example":{"account_id":"AB1234","live":true,"alias":"example-shop","reporting_currency_primary":"USD","reporting_currency_secondary":"EUR","oauth_authorize_url":"https://example-shop.auth.comecero.com/oauth/authorize","oauth_callback_url":"https://example-shop.auth.comecero.com/oauth/callback","contract_select_url":"https://example-shop.auth.comecero.com/plan/select","signin_url":"https://example-shop.auth.comecero.com","model":"agent","payment_currencies":[{"code":"USD","name":"US Dollar"},{"code":"EUR","name":"Euro"}],"default_payment_currency":"USD"}},"account":{"type":"object","title":"account","description":"Your Comecero account: your company details, the contact details shoppers see, and whether the account may take live payments. One account holds both your test and your live data.","properties":{"object":{"type":"string","enum":["account"],"description":"The object type. Always `account`.","readOnly":true},"url":{"type":"string","format":"uri","description":"The URL of this account.","readOnly":true},"account_id":{"type":"string","description":"The account ID, two letters and four digits.","readOnly":true},"alias":{"type":["string","null"],"description":"A short name for the account that users may sign in with instead of the account ID. It is also the start of your sign-in page address."},"date_created":{"type":"string","format":"date-time","description":"When the account was created.","readOnly":true},"date_modified":{"type":"string","format":"date-time","description":"When the account was last changed.","readOnly":true},"company_name":{"type":["string","null"],"description":"The legal name of your company.","maxLength":75},"dba":{"type":["string","null"],"description":"The name you trade under, if it differs from `company_name`.","maxLength":75},"name":{"type":["string","null"],"description":"The full name of the main contact.","maxLength":75},"email":{"type":["string","null"],"format":"email","description":"The main contact's email address.","maxLength":75},"website":{"type":["string","null"],"description":"Your website. `https://` is added when you leave out the protocol.","maxLength":75},"phone":{"type":["string","null"],"description":"Your phone number.","maxLength":25},"tax_number":{"type":["string","null"],"description":"Your VAT or tax registration number, printed on invoices. In the EU an invoice needs it.","maxLength":50},"registration_number":{"type":["string","null"],"description":"Your company registration number.","maxLength":50},"logo_url":{"type":["string","null"],"format":"uri","description":"A public `https` URL of your logo, used on invoices and emails. Up to 500 characters.","maxLength":500},"address_1":{"type":["string","null"],"description":"The first line of your address.","maxLength":75},"address_2":{"type":["string","null"],"description":"The second line of your address.","maxLength":75},"city":{"type":["string","null"],"description":"Your city.","maxLength":75},"state_prov":{"type":["string","null"],"description":"Your state or province. For the US and Canada, the standard two-letter code.","maxLength":75},"postal_code":{"type":["string","null"],"description":"Your postal code.","maxLength":75},"country":{"type":["string","null"],"description":"Your country, as an ISO 3166-1 alpha-2 code."},"support_email":{"type":["string","null"],"format":"email","description":"The email address shoppers see for help. Null when you want none shown on your shop.","maxLength":75},"support_website":{"type":["string","null"],"description":"The support page shoppers see. When it is empty, `website` is used.","maxLength":75},"live":{"type":"boolean","description":"True when the account may take live payments. New accounts start with `false` and Comecero sets it once the account is approved.","readOnly":true},"closed":{"type":"boolean","description":"True when the account has been closed.","readOnly":true},"date_closed":{"type":["string","null"],"format":"date-time","description":"When the account was closed. Null for an open account.","readOnly":true},"account_meta":{"description":"The account's meta details, as a URL, or the object when you send `expand=account_meta`.","readOnly":true,"oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/account_meta"}]},"token":{"type":"string","description":"A live trusted token for the account owner, so they are signed in at once. Only in the response to `POST /accounts`.","readOnly":true},"formatted":{"type":"object","description":"Display text for dates and the country. Only present when you send `formatted=true`.","readOnly":true,"properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"},"date_closed":{"type":["string","null"]},"country":{"type":["string","null"],"description":"The country's name."}}}},"example":{"object":"account","url":"https://api.comecero.com/api/v1/accounts/AB1234","account_id":"AB1234","alias":"example-shop","date_created":"2026-03-01T14:36:52Z","date_modified":"2026-10-01T09:20:11Z","company_name":"Example Software Ltd","dba":"Example Software","name":"John Doe","email":"john@example.com","website":"https://www.example.com","phone":"+1 555 0100","tax_number":null,"registration_number":null,"logo_url":"https://www.example.com/logo.png","address_1":"100 Main Street","address_2":null,"city":"Springfield","state_prov":"IL","postal_code":"62701","country":"US","support_email":"support@example.com","support_website":"https://www.example.com/support","live":true,"closed":false,"date_closed":null,"account_meta":"https://api.comecero.com/api/v1/accounts/AB1234/account_meta"}},"account_list":{"title":"account_list","description":"A cursor-based list of accounts.","allOf":[{"$ref":"#/components/schemas/list_cursor"},{"type":"object","properties":{"data":{"type":"array","description":"The accounts on this page.","items":{"$ref":"#/components/schemas/account"}}}}]},"error":{"type":"object","title":"error","description":"Every error response has this body, whatever the status code. Use `status` and `type` for the broad case, `code` for the exact one, and show `message` to a person.","required":["error"],"properties":{"error":{"type":"object","title":"error_details","required":["type","code","message","reference","status","meta"],"properties":{"type":{"type":"string","description":"The broad category. It matches `status`.","enum":["bad_request","unauthorized","transaction_error","forbidden","not_found","conflict","unprocessable","too_many_requests","internal_server_error","external_server_error","external_server_timeout"]},"code":{"type":["string","null"],"description":"The exact error within its type, for example `invalid_input`, `invalid_token`, `payment_declined`, `insufficient_permissions`, `resource_not_found`, `in_use` or `invalid_state`. New codes may be added, so keep a fallback for each status.","examples":["invalid_input"]},"message":{"type":["string","null"],"description":"What went wrong and, often, how to fix it. Written for people, in the shopper's language where a translation exists. Do not parse it."},"reference":{"type":["string","null"],"description":"A 7-character code (some newer ones are longer) that names the exact check in Comecero that refused the request. The same check always gives the same reference, so it is not unique to your request. Quote it when you contact support.","examples":["qh81SPw"]},"status":{"type":"integer","description":"The HTTP status code of the response.","enum":[400,401,402,403,404,409,422,429,500,502,504]},"meta":{"description":"More detail about the error when there is any, such as the payment that was declined. Usually `null`.","type":["object","null"],"additionalProperties":true}}}},"example":{"error":{"type":"not_found","code":"resource_not_found","message":"Event not found: 0059847953278fQmIZHpIYdE does not exist.","reference":"qh81SPw","status":404,"meta":null}}},"account_create_request":{"type":"object","title":"account_create_request","description":"A new account and its first user, who becomes the account owner. The account's country is guessed from your IP address when you leave it out.","required":["name","email","user_id","password"],"properties":{"name":{"type":"string","description":"The owner's full name, at least 4 characters.","minLength":4,"maxLength":75},"email":{"type":"string","format":"email","description":"The owner's email address. It is also the first user's email.","maxLength":75},"user_id":{"type":"string","description":"The first user's sign-in name: at least 5 characters of letters, numbers, underscores, dashes and periods.","minLength":5},"password":{"type":"string","format":"password","description":"The first user's password, at least 8 characters.","minLength":8,"writeOnly":true},"company_name":{"type":"string","description":"The legal name of the company. It is also used as `dba`.","maxLength":75},"website":{"type":"string","maxLength":75,"description":"The company website."},"support_email":{"type":"string","format":"email","maxLength":75,"description":"The email address shoppers see for help."},"support_website":{"type":"string","maxLength":75,"description":"The support page shoppers see. Defaults to `website`."},"phone":{"type":"string","maxLength":25,"description":"A phone number."},"tax_number":{"type":"string","maxLength":50,"description":"The VAT or tax registration number."},"registration_number":{"type":"string","maxLength":50,"description":"The company registration number."},"logo_url":{"type":"string","format":"uri","maxLength":500,"description":"A public `https` URL of the logo."},"address_1":{"type":"string","maxLength":75,"description":"The first line of the address."},"address_2":{"type":"string","maxLength":75,"description":"The second line of the address."},"city":{"type":"string","maxLength":75,"description":"The city."},"state_prov":{"type":"string","maxLength":75,"description":"The state or province."},"postal_code":{"type":"string","maxLength":75,"description":"The postal code."},"country":{"type":"string","description":"The country, as an ISO 3166-1 alpha-2 code."},"signup_terms_version":{"type":"string","description":"The version of the Comecero terms of service and privacy policy the person accepted, up to 50 characters. Saved with the time.","maxLength":50}},"example":{"name":"John Doe","email":"john@example.com","user_id":"john.doe","password":"correct-horse-battery","company_name":"Example Software Ltd","website":"www.example.com","country":"US"}},"account_request":{"type":"object","title":"account_request","description":"The account fields to change. Fields you leave out keep their value. An empty string clears most text fields, but not `email` or `website`.","properties":{"company_name":{"type":"string","description":"The legal name of your company.","maxLength":75},"dba":{"type":"string","description":"The name you trade under.","maxLength":75},"name":{"type":"string","description":"The full name of the main contact, at least 4 characters.","minLength":4,"maxLength":75},"email":{"type":"string","format":"email","description":"The main contact's email address.","maxLength":75},"website":{"type":"string","description":"Your website. `https://` is added when you leave out the protocol.","maxLength":75},"phone":{"type":"string","description":"Your phone number.","maxLength":25},"tax_number":{"type":"string","description":"Your VAT or tax registration number.","maxLength":50},"registration_number":{"type":"string","description":"Your company registration number.","maxLength":50},"logo_url":{"type":"string","format":"uri","description":"A public `https` URL of your logo. Comecero fetches it to print invoices, so it must be reachable from the internet (`400` otherwise).","maxLength":500},"address_1":{"type":"string","maxLength":75,"description":"The first line of your address."},"address_2":{"type":"string","maxLength":75,"description":"The second line of your address."},"city":{"type":"string","maxLength":75,"description":"Your city."},"state_prov":{"type":"string","maxLength":75,"description":"Your state or province. For the US and Canada it must be the standard two-letter code (`400` otherwise)."},"postal_code":{"type":"string","maxLength":75,"description":"Your postal code."},"country":{"type":"string","description":"Your country, as an ISO 3166-1 alpha-2 code."},"support_email":{"type":"string","format":"email","description":"The email address shoppers see for help. Send an empty string to show none.","maxLength":75},"support_website":{"type":"string","description":"The support page shoppers see.","maxLength":75},"alias":{"type":"string","description":"A new alias: 5 to 25 characters, not in the account ID format, not a reserved word, without `comecero`, and not used by another account (`400`).","minLength":5,"maxLength":25}},"example":{"support_email":"help@example.com","tax_number":"GB123456789"}},"list_offset":{"type":"object","title":"offset_list","description":"A page of an offset-based list. Move between pages with `offset`, or follow `next_page_url` and `previous_page_url`, which keep your other query parameters.","required":["total_items","total_pages","current_page","next_page_url","next_page_offset","previous_page_url","previous_page_offset","current_page_url","data"],"properties":{"total_items":{"type":"integer","description":"How many items match, across all pages."},"total_pages":{"type":"integer","description":"How many pages there are at this `limit`. `0` when nothing matches."},"current_page":{"type":"integer","description":"The number of this page, starting at 1. `0` when nothing matches."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or `null` on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or `null` on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or `null` on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or `null` on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The items on this page.","items":{"type":"object"}}}},"address":{"type":"object","title":"address","x-limited":true,"x-response":true,"description":"A postal address, as it comes back on a customer (`billing_address`, `shipping_address`), on a saved card or wallet, and on the customer of a cart, invoice or order. An address that was never set still comes back as an object, with every field `null`.","properties":{"object":{"type":"string","enum":["address"],"description":"The object type. Always `address`."},"name":{"type":["string","null"],"description":"The name of the person at the address. When you leave it out on a new address, the customer's name is used."},"address_1":{"type":["string","null"],"description":"The first line of the street address."},"address_2":{"type":["string","null"],"description":"The second line of the street address."},"city":{"type":["string","null"],"description":"The city."},"state_prov":{"type":["string","null"],"description":"The state or province. For a US or Canadian address with a known postal code, Comecero sets this from the postal code."},"postal_code":{"type":["string","null"],"description":"The postal or zip code, cleaned of stray spaces and characters."},"country":{"type":["string","null"],"description":"The two-letter ISO 3166-1 alpha-2 country code, for example `US`."},"email":{"type":["string","null"],"format":"email","description":"The email address of the person at the address."},"meta":{"description":"Your own data for this address, as an object or a string."},"formatted":{"type":"object","description":"Only when you send `formatted=true`. Display text for the address.","properties":{"country":{"type":["string","null"],"description":"The country name, for example `United States`."}}}},"example":{"object":"address","name":"John Doe","address_1":"123 Main St.","address_2":null,"city":"New York","state_prov":"NY","postal_code":"10019","country":"US","email":"john@example.com","meta":null},"required":["object","name","address_1","address_2","city","state_prov","postal_code","country","email","meta"]},"payment_method_card":{"type":"object","title":"payment_method_card","x-limited":true,"x-response":true,"description":"The `data` of a saved card (`type: credit_card`). Comecero keeps the card number encrypted in its vault and never returns it. The security code (CVV) is never stored.","properties":{"object":{"type":"string","enum":["credit_card"],"description":"The object type. Always `credit_card`."},"mask":{"type":["string","null"],"description":"The card number with all but the first digit and last four hidden."},"fingerprint":{"type":["string","null"],"description":"An id for the card number, the same every time the same card is used on your account. Use it to spot the same card on two customers."},"exp_month":{"type":"integer","minimum":1,"maximum":12,"description":"The expiry month."},"exp_year":{"type":"integer","description":"The expiry year, as two digits (`28` for 2028)."},"cardholder_name":{"type":["string","null"],"description":"The name on the card."},"ending":{"type":["string","null"],"description":"The last four digits of the card number."},"type":{"type":["string","null"],"description":"The card brand, for example `Visa`, `MasterCard` or `American Express`."},"label":{"type":"string","description":"A name for the card. When none was set, it is the brand and last four, for example `Visa 1111`."},"billing_address":{"$ref":"#/components/schemas/address"}},"example":{"object":"credit_card","mask":"4***********1111","fingerprint":"2321657x8123834dc21ea08f","exp_month":12,"exp_year":28,"cardholder_name":"John Doe","ending":"1111","type":"Visa","label":"Visa 1111","billing_address":{"object":"address","name":"John Doe","address_1":"123 Main St.","address_2":null,"city":"New York","state_prov":"NY","postal_code":"10019","country":"US","email":null,"meta":null}}},"payment_method_ach":{"type":"object","title":"payment_method_ach","x-limited":true,"x-response":true,"description":"The `data` of a saved US bank account (`type: ach`). The routing and account numbers are kept encrypted in the vault and only their masks are returned.","properties":{"object":{"type":"string","enum":["ach"],"description":"The object type. Always `ach`."},"routing_number_mask":{"type":["string","null"],"description":"The routing number with most digits hidden."},"account_number_mask":{"type":["string","null"],"description":"The account number with most digits hidden."},"account_type":{"type":["string","null"],"enum":["checking","savings",null],"description":"The kind of bank account."}},"example":{"object":"ach","routing_number_mask":"****0021","account_number_mask":"****6789","account_type":"checking"}},"payment_method_paypal":{"type":"object","title":"payment_method_paypal","x-limited":true,"x-response":true,"description":"The `data` of a PayPal payment method (`type: paypal`). A saved PayPal method is a billing agreement the customer accepted.","properties":{"object":{"type":"string","enum":["paypal"],"description":"The object type. Always `paypal`."},"billing_agreement_id":{"type":["string","null"],"description":"The PayPal billing agreement id, when the customer accepted one."}},"example":{"object":"paypal","billing_agreement_id":"B-5YM72137N1234567X"}},"payment_method_amazon_pay":{"type":"object","title":"payment_method_amazon_pay","x-limited":true,"x-response":true,"description":"The `data` of an Amazon Pay payment method (`type: amazon_pay`).","properties":{"object":{"type":"string","enum":["amazon_pay"],"description":"The object type. Always `amazon_pay`."},"charge_permission_id":{"type":["string","null"],"description":"The Amazon Pay charge permission id, used to charge again later."},"checkout_session_id":{"type":["string","null"],"description":"The Amazon Pay checkout session id."},"merchant_id":{"type":["string","null"],"description":"The Amazon Pay merchant id the method belongs to."}},"example":{"object":"amazon_pay","charge_permission_id":"S01-1234567-1234567","checkout_session_id":"bd504926-f659-4ad7-a1a9-9a747aaf5275","merchant_id":"A1EXAMPLE2MERCH"}},"payment_method_stripe":{"type":"object","title":"payment_method_stripe","x-limited":true,"x-response":true,"description":"The `data` of a Comecero Express Payments method (`type: stripe`). The shopper enters the details on your page and Comecero fills these fields in from the payment once it is confirmed.","properties":{"object":{"type":"string","enum":["stripe"],"description":"The object type. Always `stripe`."},"selected_payment_method":{"type":["string","null"],"description":"The method the shopper used, for example `card`."},"wallet":{"type":["string","null"],"description":"The wallet the method came through, for example `apple_pay` or `google_pay`."},"mask":{"type":["string","null"],"description":"The account number with most digits hidden, when the method has one."},"ending":{"type":["string","null"],"description":"The last four digits, when the method has them."},"type":{"type":["string","null"],"description":"The card brand or method name, for example `Visa`."},"label":{"type":["string","null"],"description":"A name for the method to show on receipts, for example `Visa 4242`."}},"example":{"object":"stripe","selected_payment_method":"card","wallet":null,"mask":null,"ending":"4242","type":"Visa","label":"Visa 4242"}},"payment_method_wallet":{"type":"object","title":"payment_method_wallet","x-limited":true,"x-response":true,"description":"The `data` of a device wallet payment method (`type: wallet`), Google Pay or Apple Pay. The wallet token is never returned.","properties":{"object":{"type":"string","enum":["wallet"],"description":"The object type. Always `wallet`."},"wallet":{"type":["string","null"],"enum":["google_pay","apple_pay",null],"description":"Which wallet."},"cardholder_name":{"type":["string","null"],"description":"The name on the wallet's card."},"type":{"type":["string","null"],"description":"The card brand, for example `Visa`."},"ending":{"type":["string","null"],"description":"The last four digits of the card the wallet handed over."},"label":{"type":["string","null"],"description":"A name for the method to show on receipts, for example `Google Pay, Visa 4242`."},"billing_address":{"$ref":"#/components/schemas/address"}},"example":{"object":"wallet","wallet":"google_pay","cardholder_name":"John Doe","type":"Visa","ending":"4242","label":"Google Pay, Visa 4242","billing_address":{"object":"address","name":"John Doe","address_1":"123 Main St.","address_2":null,"city":"New York","state_prov":"NY","postal_code":"10019","country":"US","email":null,"meta":null}}},"payment_method":{"type":"object","title":"payment_method","x-limited":true,"x-response":true,"description":"A payment method saved to a customer, used again for later payments and subscription renewals. What `data` holds depends on `type`. Card and bank numbers are kept encrypted in Comecero's vault and are never returned; only masks, the last four digits and the brand come back. A card's security code is never stored.","properties":{"object":{"type":"string","enum":["payment_method"],"description":"The object type. Always `payment_method`."},"url":{"type":["string","null"],"description":"The full URL of the payment method."},"payment_method_id":{"type":"string","description":"The id of the payment method."},"date_created":{"type":"string","format":"date-time","description":"When the payment method was saved."},"date_modified":{"type":"string","format":"date-time","description":"When the payment method was last changed."},"test":{"type":"boolean","description":"True for a test payment method. Always matches the customer."},"type":{"type":"string","enum":["credit_card","ach","paypal","amazon_pay","apple_pay","stripe","wallet"],"description":"The kind of payment method. `stripe` is Comecero Express Payments. `wallet` is Google Pay or Apple Pay."},"data":{"description":"The details for this `type`. Not present for `apple_pay`.","anyOf":[{"$ref":"#/components/schemas/payment_method_card"},{"$ref":"#/components/schemas/payment_method_ach"},{"$ref":"#/components/schemas/payment_method_paypal"},{"$ref":"#/components/schemas/payment_method_amazon_pay"},{"$ref":"#/components/schemas/payment_method_stripe"},{"$ref":"#/components/schemas/payment_method_wallet"}]},"is_default":{"type":"boolean","description":"True for the customer's default payment method, the one used when a payment, renewal or new subscription names the customer but no payment method. The first method saved becomes the default."},"date_last_used":{"type":["string","null"],"format":"date-time","description":"When the payment method was last used for a successful payment."},"formatted":{"type":"object","description":"Only when you send `formatted=true`. Display text.","properties":{"type":{"type":"string","description":"The kind of payment method in words, for example `Credit card`."}}}},"example":{"url":"https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/payment_methods/0092503470929PmEP0ivO4","object":"payment_method","payment_method_id":"0092503470929PmEP0ivO4","date_created":"2026-11-02T18:20:31Z","date_modified":"2026-11-02T18:20:31Z","test":true,"type":"credit_card","data":{"object":"credit_card","mask":"4***********1111","fingerprint":"2321657x8123834dc21ea08f","exp_month":12,"exp_year":28,"cardholder_name":"John Doe","ending":"1111","type":"Visa","label":"Visa 1111","billing_address":{"object":"address","name":"John Doe","address_1":"123 Main St.","address_2":null,"city":"New York","state_prov":"NY","postal_code":"10019","country":"US","email":null,"meta":null}},"is_default":true,"date_last_used":"2026-11-02T18:20:31Z"},"required":["object","url","payment_method_id","date_created","date_modified","test","type","is_default","date_last_used"]},"payment_method_list":{"type":"object","title":"payment_method_list","description":"An offset-based list of a customer's payment methods. Every payment method comes back on one page, oldest first.","properties":{"total_items":{"type":"integer","description":"The number of payment methods."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The page number of this page."},"next_page_url":{"type":["string","null"],"description":"The URL of the next page, or `null`."},"next_page_offset":{"type":["integer","null"],"description":"The offset of the next page, or `null`."},"previous_page_url":{"type":["string","null"],"description":"The URL of the previous page, or `null`."},"previous_page_offset":{"type":["integer","null"],"description":"The offset of the previous page, or `null`."},"current_page_url":{"type":"string","description":"The URL of this page."},"data":{"type":"array","description":"The payment methods.","items":{"$ref":"#/components/schemas/payment_method"}}},"required":["total_items","total_pages","current_page","next_page_url","next_page_offset","previous_page_url","previous_page_offset","current_page_url","data"]},"customer_balance":{"type":"object","title":"customer_balance","x-limited":true,"x-response":true,"description":"A customer's store credit. Money comes in from refunds paid to the balance and from payments made with `apply_to_balance: true`, and goes out when the customer pays with the `customer_account_balance` payment method.\n\nThe amount can be below zero. That is expected: when a refund paid to the balance is taken back, or a chargeback lands after the credit was spent, the balance goes negative and stays that way until new credit covers it. A payment from the balance can never take it below zero.\n\nA customer with no balance transactions yet has a balance of `0` in `USD`.","properties":{"object":{"type":"string","enum":["customer_balance"],"description":"The object type. Always `customer_balance`."},"url":{"type":"string","description":"The full URL of the balance."},"customer_id":{"type":"string","description":"The id of the customer."},"account_id":{"type":"string","description":"The id of the account."},"test":{"type":"boolean","description":"True for a test customer."},"amount":{"type":"number","description":"The balance, in `currency`. Can be negative. When you ask for another currency, this is converted at the account's exchange rate."},"currency":{"type":"string","description":"The currency of `amount`. The balance is kept in the currency of its first transaction. You can ask for another with the `currency` parameter."},"date_last_transaction":{"type":["string","null"],"format":"date-time","description":"When the balance last changed, or `null` if it never has."},"transactions":{"type":["string","object"],"description":"The URL of the balance transactions, or the list when expanded (`expand=transactions`). Only present when your token may read them.","x-expandable-url":true},"formatted":{"type":"object","description":"Only when you send `formatted=true`. Display text.","properties":{"amount":{"type":"string"},"date_last_transaction":{"type":["string","null"]}}}},"example":{"object":"customer_balance","url":"https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/balance","customer_id":"0091304300408CuoxY9Pf3","account_id":"AB1234","test":true,"amount":25,"currency":"USD","date_last_transaction":"2026-11-04T15:02:11Z","transactions":"https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/balance/transactions"},"required":["object","url","customer_id","account_id","test","amount","currency","date_last_transaction"]},"customer":{"type":"object","title":"customer","x-limited":true,"x-response":true,"description":"A customer: the person or company who buys. Holds contact details, the billing and shipping address, an optional username for sign-in, and links to the customer's payment methods, store credit and history.\n\nThe links (`payment_methods`, `payments`, `refunds`, `orders`, `subscriptions`, `invoices`, `balance`) are only present when your token may read that resource. Send `expand` to get any of them in full. In a list of customers, `orders` is left out and `payments`, `refunds`, `subscriptions` and `invoices` are never expanded.","properties":{"object":{"type":"string","enum":["customer"],"description":"The object type. Always `customer`."},"url":{"type":"string","description":"The full URL of the customer."},"customer_id":{"type":"string","description":"The id of the customer."},"date_created":{"type":"string","format":"date-time","description":"When the customer was created."},"date_modified":{"type":"string","format":"date-time","description":"When the customer was last changed."},"account_id":{"type":"string","description":"The id of the account the customer belongs to."},"test":{"type":"boolean","description":"True for a test customer, false for a live one."},"company_name":{"type":["string","null"],"description":"The customer's company name."},"name":{"type":["string","null"],"description":"The customer's name."},"email":{"type":["string","null"],"format":"email","description":"The customer's email address."},"phone":{"type":["string","null"],"description":"The customer's phone number."},"billing_address":{"$ref":"#/components/schemas/address"},"shipping_address":{"$ref":"#/components/schemas/address"},"username":{"type":["string","null"],"description":"The username the customer signs in with (see Log in a customer). Always lower case. The password is never returned."},"tax_number":{"type":["string","null"],"description":"The customer's tax or VAT number."},"tax_exempt":{"type":"boolean","description":"True when no tax is charged to the customer. For a customer in an EU country (not GB), this is true exactly when a valid VAT number is on file."},"has_payments":{"type":"boolean","description":"True once the customer has made at least one successful payment."},"locale":{"type":["string","null"],"description":"The customer's language and region, for example `en-US`. Used for the emails the customer gets."},"meta":{"description":"Your own data for this customer, as an object or a string."},"payment_methods":{"description":"The URL of the customer's saved payment methods, or the list itself when expanded.","x-expandable-url":true,"oneOf":[{"type":"string"},{"$ref":"#/components/schemas/payment_method_list"}]},"payments":{"type":["string","object"],"description":"The URL of the customer's payments, or the list when expanded.","x-expandable-url":true},"refunds":{"type":["string","object"],"description":"The URL of the customer's refunds, or the list when expanded.","x-expandable-url":true},"orders":{"type":["string","object"],"description":"The URL of the customer's orders, or the list when expanded. Not present in a list of customers.","x-expandable-url":true},"subscriptions":{"type":["string","object"],"description":"The URL of the customer's subscriptions, or the list when expanded.","x-expandable-url":true},"invoices":{"type":["string","object"],"description":"The URL of the customer's invoices, or the list when expanded.","x-expandable-url":true},"balance":{"description":"The URL of the customer's store credit balance, or the balance itself when expanded.","x-expandable-url":true,"oneOf":[{"type":"string"},{"$ref":"#/components/schemas/customer_balance"}]},"formatted":{"type":"object","description":"Only when you send `formatted=true`. Dates as display text.","properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"}}}},"example":{"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":"123 Main St.","address_2":null,"city":"New York","state_prov":"NY","postal_code":"10019","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"},"required":["object","url","customer_id","date_created","date_modified","account_id","test","company_name","name","email","phone","billing_address","shipping_address","username","tax_number","tax_exempt","has_payments","locale","meta"]},"role_permission":{"type":"object","title":"permission","description":"One rule that allows methods on one resource. Tokens, users and roles all hold a list of these. Call `GET /auths/options?type=secret` for the resources and methods each token type may be given.","required":["resource","methods"],"properties":{"resource":{"type":"string","description":"The resource the rule is for, such as `orders` or `customers`. `*` means every resource the token type may use.","examples":["orders"]},"methods":{"type":"array","description":"The methods allowed on the resource. `*` means every method the token type may use on it.","items":{"type":"string","enum":["create","read","update","delete","*"]},"examples":[["read","update"]]},"allow":{"type":"boolean","description":"True to allow the methods. Send `true`.","examples":[true]}},"example":{"resource":"orders","methods":["read"],"allow":true}},"role_effective_permissions":{"type":"object","title":"effective_permissions","description":"What the token or user may really do, after its roles and permissions are combined and cut down to what its token type allows. Each key is a resource and each value says which methods are allowed on it.","readOnly":true,"additionalProperties":{"type":"object","properties":{"create":{"type":"boolean"},"read":{"type":"boolean"},"update":{"type":"boolean"},"delete":{"type":"boolean"}}},"example":{"orders":{"create":false,"read":true,"update":true,"delete":false},"customers":{"create":false,"read":true,"update":false,"delete":false}}},"user":{"type":"object","title":"user","description":"A person who can sign in to your dashboard. Users are kept per mode: test users and live users are separate, and a test user's `user_id` ends in `.test`. When a user signs in, they get a trusted token with the user's permissions.","properties":{"object":{"type":"string","enum":["user"],"description":"The object type. Always `user`.","readOnly":true},"url":{"type":"string","format":"uri","description":"The URL of this user.","readOnly":true},"user_id":{"type":"string","description":"The user's sign-in name, in lower case. A test user's ends in `.test`.","readOnly":true},"test":{"type":"boolean","description":"True for a test user.","readOnly":true},"date_created":{"type":"string","format":"date-time","description":"When the user was created.","readOnly":true},"date_modified":{"type":"string","format":"date-time","description":"When the user was last changed.","readOnly":true},"account_id":{"type":"string","description":"The account the user belongs to.","readOnly":true},"account_alias":{"type":["string","null"],"description":"The alias of your account, which users may sign in with instead of the account ID.","readOnly":true},"account_live":{"type":"boolean","description":"True when your account may take live payments.","readOnly":true},"name":{"type":"string","description":"The user's full name.","maxLength":75},"email":{"type":"string","format":"email","description":"The user's email address. Each user needs their own, across test and live users.","maxLength":100},"is_account_owner":{"type":"boolean","description":"True for an owner of the account. The user who signed up is an owner."},"language":{"type":["string","null"],"description":"The user's language, as a two-letter ISO 639-1 code in lower case."},"locale":{"type":["string","null"],"description":"The locale of the user's browser, such as `en-US`, saved each time they sign in. Null until they first sign in.","readOnly":true},"date_last_login":{"type":["string","null"],"format":"date-time","description":"When the user last signed in. Null if they never have.","readOnly":true},"allow_test_transactions":{"type":"boolean","description":"True when the user may work in test mode."},"roles":{"type":"array","description":"The `role_id` of each role given to the user.","items":{"type":"string"}},"permissions":{"type":"array","description":"The permissions given to the user directly. Where a role and a permission disagree, the more generous one wins.","items":{"$ref":"#/components/schemas/role_permission"}},"effective_permissions":{"$ref":"#/components/schemas/role_effective_permissions"},"meta":{"description":"Your own data about the user, any JSON up to 2,048 characters.","type":["object","null"],"additionalProperties":true},"formatted":{"type":"object","description":"Display text for the dates. Only present when you send `formatted=true`.","readOnly":true,"properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"},"date_last_login":{"type":["string","null"]}}}},"example":{"object":"user","url":"https://api.comecero.com/api/v1/users/jane.smith.test","user_id":"jane.smith.test","test":true,"date_created":"2026-10-01T14:36:52Z","date_modified":"2026-10-01T14:36:52Z","account_id":"AB1234","account_alias":"example-shop","account_live":true,"name":"Jane Smith","email":"jane@example.com","is_account_owner":false,"language":"en","locale":"en-US","date_last_login":"2026-11-06T09:12:40Z","allow_test_transactions":true,"roles":["support"],"permissions":[],"effective_permissions":{"orders":{"create":false,"read":true,"update":true,"delete":false}},"meta":null}},"auth":{"type":"object","title":"auth","description":"An API token. The full token is shown only once, in the response that creates it. After that `token` holds a masked copy. A token's `auth_id` is the SHA-256 hash of the full token, so you can look a token up without sending it.\n\nTest or live mode comes from the token. A token whose `test` is true reads and writes only test data, and a live token only live data. There is no test header. The `test` query parameter only counts when you create a token (such as `POST /auths/secret` or `POST /auths/limited`), where it picks the mode of the new token.","properties":{"object":{"type":"string","enum":["auth"],"description":"The object type. Always `auth`.","readOnly":true},"url":{"type":"string","format":"uri","description":"The URL of this token.","readOnly":true},"auth_id":{"type":"string","description":"The SHA-256 hash of the full token, in lower-case hex.","readOnly":true},"test":{"type":"boolean","description":"True for a test token. A test token reads and writes only test data.","readOnly":true},"account_id":{"type":"string","description":"The account the token belongs to.","readOnly":true},"account_alias":{"type":["string","null"],"description":"The alias of the account the token belongs to.","readOnly":true},"type":{"type":"string","description":"The token type. `secret` is for your server. `trusted` belongs to a signed-in dashboard user and is used in the browser. `limited` is used in the browser by shoppers. `admin`, `app` and `service` are used by Comecero itself and are not issued to integrators.","enum":["secret","trusted","limited","admin","app","service"],"readOnly":true},"ip_address":{"type":["string","null"],"description":"The IP address the token was issued to. Set for trusted and limited tokens, null for secret tokens.","readOnly":true},"token":{"type":"string","description":"The full token in the response that creates it. Every other response gives a masked copy, such as `secret.live.Kd4...9f2a`. The full token starts with its type and its mode, for example `secret.live.` or `limited.test.`.","readOnly":true},"expires":{"type":["string","null"],"format":"date-time","description":"When the token stops working. Null when it never expires. Trusted and limited tokens move this date forward each time they are used."},"expires_in_seconds":{"type":["integer","null"],"description":"Seconds until `expires`. Null when the token never expires.","readOnly":true},"date_last_used":{"type":["string","null"],"format":"date-time","description":"The day a secret token was last used, updated at most once a day. Null for other token types and for a token never used.","readOnly":true},"comments":{"type":["string","null"],"description":"Your own label for the token, up to 250 characters.","maxLength":250},"date_created":{"type":"string","format":"date-time","description":"When the token was created.","readOnly":true},"date_modified":{"type":"string","format":"date-time","description":"When the token was last changed.","readOnly":true},"customer":{"description":"The customer a limited token was made for, as a URL, or the customer object when you send `expand=customer`. Only present on a token made for a customer.","readOnly":true,"oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/customer"}]},"user":{"description":"The user a trusted token belongs to, as a URL, or the user object when you send `expand=user`. Only present on a token tied to a user.","readOnly":true,"oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/user"}]},"roles":{"type":"array","description":"The `role_id` of each role given to the token.","items":{"type":"string"}},"permissions":{"type":"array","description":"The permissions given to the token directly.","items":{"$ref":"#/components/schemas/role_permission"}},"effective_permissions":{"$ref":"#/components/schemas/role_effective_permissions"},"browser_info":{"type":"object","description":"Details about the caller's browser, read from the request headers. Only in the response that creates a token, and only when you send `browser_info=true`.","readOnly":true,"additionalProperties":true},"formatted":{"type":"object","description":"Display text for the dates. Only present when you send `formatted=true`.","readOnly":true,"properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"},"date_closed":{"type":["string","null"],"description":"The day the token was last used, as display text."}}}},"example":{"object":"auth","url":"https://api.comecero.com/api/v1/auths/9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","auth_id":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","test":true,"account_id":"AB1234","account_alias":"example-shop","type":"secret","ip_address":null,"token":"secret.test.Hq7...4c1e","expires":null,"expires_in_seconds":null,"date_last_used":"2026-11-06T00:00:00Z","comments":"Order sync server","date_created":"2026-10-01T14:36:52Z","date_modified":"2026-10-01T14:36:52Z","roles":[],"permissions":[{"resource":"orders","methods":["read"],"allow":true}],"effective_permissions":{"orders":{"create":false,"read":true,"update":false,"delete":false}}}},"auth_list":{"title":"auth_list","description":"An offset-based list of tokens.","allOf":[{"$ref":"#/components/schemas/list_offset"},{"type":"object","properties":{"data":{"type":"array","description":"The tokens on this page.","items":{"$ref":"#/components/schemas/auth"}}}}]},"auth_limited_request":{"type":"object","title":"auth_limited_request","description":"Optional. Send it only to make a token for one customer.","properties":{"customer_id":{"type":"string","description":"Make the token for this customer, so it can read and update that customer. Needs a secret or trusted token that may create tokens and update customers (`403` otherwise)."}},"example":{"customer_id":"0106784119870CueWmZ9P7"}},"auth_options":{"type":"object","title":"auth_options","description":"The permissions a token of one type may be given.","properties":{"account_id":{"type":"string","description":"The account of the token you called with.","readOnly":true},"test":{"type":"boolean","description":"True when you called with a test token.","readOnly":true},"permissions":{"type":"array","description":"Each resource the token type may be given, with the methods it may have on it. Empty when you leave out `type`.","readOnly":true,"items":{"type":"object","properties":{"resource":{"type":"string"},"methods":{"type":"array","items":{"type":"string","enum":["create","read","update","delete"]}}}}}},"example":{"account_id":"AB1234","test":true,"permissions":[{"resource":"carts","methods":["create","read","update","delete"]},{"resource":"products","methods":["read"]}]}},"auth_secret_request":{"type":"object","title":"auth_secret_request","description":"The settings of a secret token. A new token needs at least one role or one permission. The token you call with must itself hold every permission you ask for (`403` otherwise).","properties":{"comments":{"type":["string","null"],"description":"Your own label for the token, up to 250 characters.","maxLength":250},"expires":{"type":["string","null"],"format":"date-time","description":"When the token stops working, in ISO 8601. It must be in the future. Leave it out for a token that never expires. On an update, send null or an empty string to remove the expiry."},"roles":{"type":"array","description":"The `role_id` of each role to give the token. Each must exist (`400`).","items":{"type":"string"}},"permissions":{"type":"array","description":"Permissions to give the token directly. Only resources and methods a secret token may have are accepted (`403`).","items":{"$ref":"#/components/schemas/role_permission"}}},"example":{"comments":"Order sync server","permissions":[{"resource":"orders","methods":["read"],"allow":true}]}},"cart_item":{"type":"object","title":"cart_item","description":"One line in a cart. A limited token does not see `reference_price`, `reference_currency`, `tax_code` or the settlement amounts.","x-limited":true,"x-response":true,"properties":{"object":{"type":"string","enum":["cart_item"],"description":"The object type. Always `cart_item`."},"url":{"type":"string","format":"uri","description":"The full URL of the item."},"item_id":{"type":"string","description":"The id of the item in the cart. For a product this is the product_id, so a product is in a cart at most once. Items made for a bundle's products get their own ids."},"cross_sell_id":{"type":["string","null"],"description":"The cross-sell offer the item was added from, if any."},"up_sell_id":{"type":["string","null"],"description":"The up-sell offer the item was added from, if any."},"bundle_id":{"type":["string","null"],"description":"The product_id of the bundle this item belongs to, if any."},"bundle_group_id":{"type":["string","null"],"description":"Shared by the bundle's own item and the items for its products. Items in a bundle cannot be changed one by one: delete one to remove the whole bundle."},"date_created":{"type":"string","format":"date-time","description":"When the item was added."},"date_modified":{"type":"string","format":"date-time","description":"When the item was last changed."},"product_id":{"type":["string","null"],"description":"The product this item is for."},"cart_id":{"type":"string","description":"The cart the item is in."},"name":{"type":["string","null"],"description":"The product name."},"type":{"type":["string","null"],"description":"The product type, for example `digital`, `physical`, `service` or `bundle`."},"quantity":{"type":"number","description":"How many units. A whole number in a cart."},"currency":{"type":"string","description":"The currency of the cart."},"price":{"type":"number","description":"The price of one unit with discounts, in `currency`."},"price_original":{"type":"number","description":"The price of one unit before discounts, in `currency`."},"reference_price":{"type":["number","null"],"description":"The unit price you set for this item instead of the product's price, in `reference_currency`. Null when the product's own price is used. Not returned to a limited token.","x-exclude-limited":true},"reference_currency":{"type":["string","null"],"description":"The currency of `reference_price`. Not returned to a limited token.","x-exclude-limited":true},"subtotal":{"type":"number","description":"`price` times `quantity`, without tax, in `currency`."},"subtotal_original":{"type":"number","description":"`price_original` times `quantity`, without tax, in `currency`."},"discount":{"type":"number","description":"The discount on one unit, in `currency`."},"discount_percent":{"type":"number","description":"The discount as a fraction of the original price, for example `0.2` for 20%."},"tax":{"type":"number","description":"The tax on this line, in `currency`."},"tax_original":{"type":"number","description":"The tax on this line before discounts, in `currency`."},"total":{"type":"number","description":"`subtotal` plus `tax`, in `currency`."},"total_original":{"type":"number","description":"`subtotal_original` plus `tax_original`, in `currency`."},"tax_rate":{"type":"number","description":"The tax rate applied, as a fraction, for example `0.075` for 7.5%."},"tax_code":{"type":["string","null"],"description":"The product's tax code. Not returned to a limited token.","x-exclude-limited":true},"settlement_currency":{"type":"string","description":"The settlement currency. Not returned to a limited token.","x-exclude-limited":true},"settlement_price":{"type":"number","description":"`price` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_price_original":{"type":"number","description":"`price_original` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_subtotal":{"type":"number","description":"`subtotal` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_subtotal_original":{"type":"number","description":"`subtotal_original` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_discount":{"type":"number","description":"`discount` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_tax":{"type":"number","description":"`tax` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_tax_original":{"type":"number","description":"`tax_original` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_total":{"type":"number","description":"`total` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_total_original":{"type":"number","description":"`total_original` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"product":{"type":["string","object","null"],"description":"The URL of the product, or the product itself with `expand=items.product`.","x-expandable-url":true},"subscription_plan":{"type":["string","object","null"],"description":"The URL of the product's subscription plan, or the plan itself with `expand=items.subscription_plan`. Null when the product is not a subscription.","x-expandable-url":true},"subscription_terms":{"type":["string","object","null"],"description":"The URL of the subscription terms this item would start, or the terms with `expand=items.subscription_terms`. Null when the product is not a subscription.","x-expandable-url":true},"meta":{"description":"Your own data for the item, a string or an object, up to 2048 characters.","type":["object","string","null"]},"formatted":{"type":"object","description":"Money amounts, the tax rate and dates as display strings. Only present with `formatted=true`.","additionalProperties":{"type":["string","null"]}}},"required":["object","url","item_id","date_created","date_modified","product_id","cart_id","name","type","quantity","currency","price","price_original","subtotal","subtotal_original","discount","discount_percent","tax","tax_original","total","total_original","tax_rate","subscription_terms","meta"],"example":{"object":"cart_item","url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/items/pdf-pro.test","item_id":"pdf-pro.test","cross_sell_id":null,"up_sell_id":null,"bundle_id":null,"bundle_group_id":null,"date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:19:12Z","product_id":"pdf-pro.test","cart_id":"0091307952465CafhFSTa1","name":"PDF Viewer Pro","type":"digital","quantity":2,"currency":"USD","price":99.95,"price_original":99.95,"reference_price":null,"reference_currency":null,"subtotal":199.9,"subtotal_original":199.9,"discount":0,"discount_percent":0,"tax":14.99,"tax_original":14.99,"total":214.89,"total_original":214.89,"tax_rate":0.075,"tax_code":null,"settlement_currency":"USD","settlement_price":99.95,"settlement_price_original":99.95,"settlement_subtotal":199.9,"settlement_subtotal_original":199.9,"settlement_discount":0,"settlement_tax":14.99,"settlement_tax_original":14.99,"settlement_total":214.89,"settlement_total_original":214.89,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription_plan":null,"subscription_terms":null,"meta":null}},"shipping_item":{"type":"object","title":"shipping_item","description":"The shipping line of a cart or order, made from the selected shipping method. Inside a cart or order it has no `object`, `product_id`, `cart_id` or `product`. `GET /carts/{cart_id}/shipping_item` returns it shaped as a cart item, with `object` `cart_item`, `product_id` null and `cart_id`. The `settlement_` fields, `reference_price`, `reference_currency` and `tax_code` are not returned to a limited token.","x-limited":true,"x-response":true,"properties":{"object":{"type":"string","enum":["cart_item"],"description":"Only from `GET /carts/{cart_id}/shipping_item`. Always `cart_item`."},"url":{"type":"string","format":"uri","description":"The full URL of the shipping item."},"item_id":{"type":"string","description":"The shipping_method_id of the selected shipping method."},"cross_sell_id":{"type":["string","null"],"description":"Always null for shipping."},"up_sell_id":{"type":["string","null"],"description":"Always null for shipping."},"bundle_id":{"type":["string","null"],"description":"Always null for shipping."},"bundle_group_id":{"type":["string","null"],"description":"Always null for shipping."},"date_created":{"type":"string","format":"date-time","description":"When shipping was worked out."},"date_modified":{"type":"string","format":"date-time","description":"When shipping was last worked out."},"product_id":{"type":"null","description":"Only from `GET /carts/{cart_id}/shipping_item`. Always null."},"cart_id":{"type":"string","description":"Only from `GET /carts/{cart_id}/shipping_item`. The cart."},"name":{"type":"string","description":"The description of the shipping method."},"type":{"type":"string","enum":["shipping"],"description":"Always `shipping`."},"quantity":{"type":"number","description":"Always 1."},"currency":{"type":"string","description":"The currency of the cart or order."},"price":{"type":"number","description":"The shipping price with discounts, without tax, in `currency`."},"price_original":{"type":"number","description":"The shipping price before discounts, in `currency`."},"reference_price":{"type":["number","null"],"description":"Always null for shipping. Not returned to a limited token.","x-exclude-limited":true},"reference_currency":{"type":["string","null"],"description":"Always null for shipping. Not returned to a limited token.","x-exclude-limited":true},"subtotal":{"type":"number","description":"The shipping price, without tax, in `currency`."},"subtotal_original":{"type":"number","description":"The shipping price before discounts, without tax, in `currency`."},"discount":{"type":"number","description":"The shipping discount, in `currency`."},"discount_percent":{"type":"number","description":"The discount as a fraction of the original price."},"tax":{"type":"number","description":"The tax on shipping, in `currency`."},"tax_original":{"type":"number","description":"The tax on shipping before discounts, in `currency`."},"total":{"type":"number","description":"`subtotal` plus `tax`, in `currency`."},"total_original":{"type":"number","description":"`subtotal_original` plus `tax_original`, in `currency`."},"tax_rate":{"type":"number","description":"The tax rate on shipping, as a fraction."},"tax_code":{"type":"string","description":"Always `shipping`. Not returned to a limited token.","x-exclude-limited":true},"settlement_currency":{"type":"string","description":"The settlement currency. Not returned to a limited token.","x-exclude-limited":true},"settlement_price":{"type":"number","description":"`price` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_price_original":{"type":"number","description":"`price_original` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_subtotal":{"type":"number","description":"`subtotal` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_subtotal_original":{"type":"number","description":"`subtotal_original` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_discount":{"type":"number","description":"`discount` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_tax":{"type":"number","description":"`tax` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_tax_original":{"type":"number","description":"`tax_original` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_total":{"type":"number","description":"`total` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_total_original":{"type":"number","description":"`total_original` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"product":{"type":"null","description":"Only from `GET /carts/{cart_id}/shipping_item`. Always null."},"subscription_plan":{"type":"null","description":"Only from `GET /carts/{cart_id}/shipping_item`. Always null."},"subscription_terms":{"type":"null","description":"Only from `GET /carts/{cart_id}/shipping_item`. Always null."},"meta":{"description":"Always null for shipping.","type":["object","string","null"]},"formatted":{"type":"object","description":"Money amounts and dates as display strings. Only present with `formatted=true`.","additionalProperties":{"type":["string","null"]}}},"required":["url","item_id","date_created","date_modified","name","type","quantity","currency","price","price_original","subtotal","subtotal_original","discount","discount_percent","tax","tax_original","total","total_original","tax_rate","meta"],"example":{"object":"cart_item","url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/items/standard-us","item_id":"standard-us","cross_sell_id":null,"up_sell_id":null,"bundle_id":null,"bundle_group_id":null,"date_created":"2026-11-07T19:21:40Z","date_modified":"2026-11-07T19:21:40Z","product_id":null,"cart_id":"0091307952465CafhFSTa1","name":"Standard Shipping","type":"shipping","quantity":1,"currency":"USD","price":5,"price_original":5,"reference_price":null,"reference_currency":null,"subtotal":5,"subtotal_original":5,"discount":0,"discount_percent":0,"tax":0,"tax_original":0,"total":5,"total_original":5,"tax_rate":0,"tax_code":"shipping","settlement_currency":"USD","settlement_price":5,"settlement_price_original":5,"settlement_subtotal":5,"settlement_subtotal_original":5,"settlement_discount":0,"settlement_tax":0,"settlement_tax_original":0,"settlement_total":5,"settlement_total_original":5,"product":null,"subscription_plan":null,"subscription_terms":null,"meta":null}},"payment_option":{"type":"object","title":"payment_option","description":"One payment method type the shopper can pay with, plus what the browser needs to set it up. The setup fields appear only for their own type.","x-limited":true,"x-response":true,"properties":{"payment_method_type":{"type":"string","enum":["credit_card","paypal","amazon_pay","apple_pay","ach","stripe","wallet","customer_account_balance"],"description":"The payment method type to send in `payment_method.type`."},"surcharge":{"type":"number","description":"An extra amount for this method, in `currency`. Always 0 today."},"currency":{"type":["string","null"],"description":"The currency of `surcharge`."},"amazon_pay_merchant_id":{"type":["string","null"],"description":"Only for `amazon_pay`. Your Amazon Pay merchant id."},"amazon_pay_public_key_id":{"type":["string","null"],"description":"Only for `amazon_pay`. The public key id for the Amazon Pay button."},"amazon_pay_store_id":{"type":["string","null"],"description":"Only for `amazon_pay`. The Amazon Pay store id."},"amazon_pay_region":{"type":["string","null"],"description":"Only for `amazon_pay`. `US`, `EU` or `JP`, which picks the Amazon Pay script."},"paypal_fraudnet_source_id":{"type":["string","null"],"description":"Only for `credit_card`. Set when a PayPal card gateway may take the card. Load PayPal FraudNet with it and send `risk_session_id` with the payment."},"stripe_publishable_key":{"type":["string","null"],"description":"For `stripe`, the key to load Stripe.js with. For `credit_card`, set when the checkout should make a fraud session for the card."},"stripe_account_id":{"type":["string","null"],"description":"For `stripe` and `credit_card`. The account to pass to Stripe.js with the key above."},"stripe_api_version":{"type":["string","null"],"description":"Only for `stripe`. The API version for Stripe.js, when one is needed."},"stripe_betas":{"type":["string","null"],"description":"Only for `stripe`. The betas value for Stripe.js, when one is needed."},"stripe_payment_method_types":{"type":["array","null"],"items":{"type":"string"},"description":"Only for `stripe`. The methods that can be offered in this currency. Null means not known: offer nothing."},"stripe_eligible_by_currency":{"type":["object","null"],"additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Only for `stripe`. The same list keyed by currency, for older checkouts."},"finix_card_form":{"type":["object","null"],"description":"Only for `credit_card`. Set when every card gateway is a Finix gateway: show the Finix card form and send its token as `payment_method.data.token`.","properties":{"environment":{"type":"string"},"application_id":{"type":"string"}}},"require_ssnl4":{"type":"boolean","description":"Only for `ach`. True when the last four digits of the SSN are required."},"require_license":{"type":"boolean","description":"Only for `ach`. True when a driver's license is required."},"wallets":{"type":["array","null"],"items":{"type":"string","enum":["google_pay","apple_pay"]},"description":"Only for `wallet`. The device wallets to show."},"google_pay":{"type":["object","null"],"description":"Only for `wallet`. What the Google Pay API needs in the browser. Null when Google Pay is not offered.","properties":{"environment":{"type":"string","description":"`TEST` or `PRODUCTION`."},"gateway":{"type":"string"},"gateway_merchant_id":{"type":"string"},"merchant_id":{"type":["string","null"]},"merchant_name":{"type":"string"},"allowed_card_networks":{"type":"array","items":{"type":"string"}},"allowed_auth_methods":{"type":"array","items":{"type":"string"}},"country_code":{"type":"string"},"domains":{"type":["array","null"],"items":{"type":"string"},"description":"In live mode, the domains Google Pay may show on. Null in test mode."}}},"apple_pay":{"type":["object","null"],"description":"Only for `wallet`. Apple Pay settings for the browser. Null when Apple Pay is not offered.","properties":{"domains":{"type":"array","items":{"type":"string"},"description":"Show Apple Pay only on one of these domains."},"display_name":{"type":"string"},"supported_networks":{"type":"array","items":{"type":"string"}},"merchant_capabilities":{"type":"array","items":{"type":"string"}},"country_code":{"type":"string"}}},"user_agent_payment_request":{"type":["string","object"],"description":"Only for `apple_pay` on a cart or invoice. The URL of the browser payment request, or the request itself with `expand=payment_methods.user_agent_payment_request`.","x-expandable-url":true},"formatted":{"type":"object","description":"`surcharge` as a display string. Only present with `formatted=true`.","additionalProperties":{"type":"string"}}},"required":["payment_method_type","surcharge","currency"],"example":{"payment_method_type":"credit_card","surcharge":0,"currency":"USD","paypal_fraudnet_source_id":null,"stripe_publishable_key":null,"stripe_account_id":null,"finix_card_form":null}},"shipping_quote":{"type":"object","title":"shipping_quote","description":"A shipping method the shopper can pick for this cart or invoice, priced for its items and the customer's location. Send its `shipping_method_id` as the cart's `shipping_method_id` to select it.","x-limited":true,"x-response":true,"properties":{"shipping_method_id":{"type":"string","description":"The id of the shipping method."},"method_id":{"type":"string","deprecated":true,"description":"The same as `shipping_method_id`. Kept for old clients; use `shipping_method_id`."},"description":{"type":["string","null"],"description":"The name of the shipping method, to show to the shopper."},"details":{"type":["string","null"],"description":"More text about the shipping method, such as delivery times."},"price":{"type":"number","description":"The price with discounts, without tax, in `currency`."},"price_original":{"type":"number","description":"The price before discounts, in `currency`."},"price_pre_tax":{"type":"number","description":"The price without tax, in `currency`. Differs from `price` only when prices include tax."},"price_pre_tax_original":{"type":"number","description":"The price without tax and before discounts, in `currency`."},"discount":{"type":"number","description":"The discount on shipping, in `currency`."},"tax":{"type":"number","description":"The tax on shipping, in `currency`."},"tax_original":{"type":"number","description":"The tax on shipping before discounts, in `currency`."},"total":{"type":"number","description":"The price plus tax, in `currency`."},"tax_rate":{"type":"number","description":"The tax rate on shipping, as a fraction."},"currency":{"type":"string","description":"The currency of the amounts."},"formatted":{"type":"object","description":"Amounts as display strings. Only present with `formatted=true`.","additionalProperties":{"type":"string"}}},"required":["shipping_method_id","method_id","description","details","price","price_original","price_pre_tax","price_pre_tax_original","discount","tax","tax_original","total","tax_rate","currency"],"example":{"shipping_method_id":"standard-us","method_id":"standard-us","description":"Standard Shipping","details":"3 to 5 business days","price":5,"price_original":5,"price_pre_tax":5,"price_pre_tax_original":5,"discount":0,"tax":0,"tax_original":0,"total":5,"tax_rate":0,"currency":"USD"}},"cart_options":{"type":"object","title":"cart_options","description":"What the shopper can choose and must provide to pay for this cart: payment methods, card types, shipping quotes and the customer fields needed. It changes with the items, the currency and the customer's location.","x-limited":true,"x-response":true,"properties":{"cart_id":{"type":"string","description":"The cart the options are for."},"account_id":{"type":"string","description":"The account the cart belongs to."},"test":{"type":"boolean","description":"True for a test cart."},"payment_methods":{"type":"array","description":"The payment method types that can pay for this cart, with their browser setup.","items":{"$ref":"#/components/schemas/payment_option"}},"card_types":{"type":"array","description":"The card brands the card gateways take in the cart currency, for example `Visa`.","items":{"type":"string"}},"shipping_quotes":{"type":"array","description":"The shipping methods the shopper can pick, priced for this cart. Empty when nothing ships.","items":{"$ref":"#/components/schemas/shipping_quote"}},"customer_required_fields":{"type":"array","description":"The customer fields that must be set before a payment can be made, in dot notation, for example `billing_address.postal_code`. They depend on your settings, the items (physical items need an address) and the customer's country.","items":{"type":"string"}},"customer_optional_fields":{"type":"array","description":"The customer fields you may also collect.","items":{"type":"string"}},"allowed_customer_countries":{"type":"array","description":"The ISO 3166-1 alpha-2 countries the shopper may be in or ship to.","items":{"type":"string"}},"require_cardholder_name":{"type":"boolean","description":"True when a card payment must include the cardholder name."}},"required":["cart_id","account_id","test","payment_methods","card_types","shipping_quotes","customer_required_fields","customer_optional_fields","allowed_customer_countries","require_cardholder_name"],"example":{"cart_id":"0091307952465CafhFSTa1","account_id":"AB1234","test":true,"payment_methods":[{"payment_method_type":"credit_card","surcharge":0,"currency":"USD","paypal_fraudnet_source_id":null,"stripe_publishable_key":null,"stripe_account_id":null,"finix_card_form":null},{"payment_method_type":"paypal","surcharge":0,"currency":"USD"}],"card_types":["Visa","MasterCard","American Express"],"shipping_quotes":[{"shipping_method_id":"standard-us","method_id":"standard-us","description":"Standard Shipping","details":"3 to 5 business days","price":5,"price_original":5,"price_pre_tax":5,"price_pre_tax_original":5,"discount":0,"tax":0,"tax_original":0,"total":5,"tax_rate":0,"currency":"USD"}],"customer_required_fields":["name","email","billing_address.country","billing_address.postal_code"],"customer_optional_fields":["phone","company_name"],"allowed_customer_countries":["US","CA"],"require_cardholder_name":false}},"cart":{"type":"object","title":"cart","description":"A shopper's basket: the items, the customer, the totals and links to what the shopper can do next. A limited token does not see the settlement amounts.","x-limited":true,"x-response":true,"properties":{"object":{"type":"string","enum":["cart"],"description":"The object type. Always `cart`."},"url":{"type":"string","format":"uri","description":"The full URL of the cart."},"cart_id":{"type":"string","description":"The id of the cart. Comecero assigns it when the cart is created."},"date_created":{"type":"string","format":"date-time","description":"When the cart was created."},"date_modified":{"type":"string","format":"date-time","description":"When the cart was last changed."},"test":{"type":"boolean","description":"True for a test cart, false for a live one. Set by the token that created it."},"account_id":{"type":"string","description":"The account the cart belongs to."},"order_id":{"type":"string","description":"The id the order gets when the cart is paid. Taken from the request when you create the cart, otherwise assigned by Comecero. Always upper case."},"open":{"type":"boolean","description":"True while the cart can be changed. A cart closes when a payment for it succeeds, and a closed cart cannot be changed or paid again."},"payment_status":{"type":["string","null"],"enum":["pending","completed","refunded","cancelled",null],"description":"Null until a payment for the cart succeeds. `pending` when the payment is authorized but not captured, `completed` when it is captured, `refunded` or `cancelled` after the order is refunded or cancelled."},"currency":{"type":"string","description":"The ISO 4217 currency the shopper sees and pays in. Taken from the request, otherwise guessed from the shopper's location."},"subtotal":{"type":"number","description":"The sum of all items with item discounts, without tax, in `currency`."},"subtotal_original":{"type":"number","description":"The sum of all items without discounts and without tax, in `currency`."},"shipping":{"type":"number","description":"The shipping amount with discounts, without tax, in `currency`."},"shipping_original":{"type":"number","description":"The shipping amount without discounts and without tax, in `currency`."},"discount":{"type":"number","description":"The discount applied to the cart as a whole, in `currency`. Item discounts are not included."},"item_discounts":{"type":"number","description":"The sum of all item discounts, in `currency`."},"total_discounts":{"type":"number","description":"The cart discount plus all item discounts, in `currency`."},"total_discounts_percent":{"type":"number","description":"The total discount as a fraction of the original total, for example `0.1` for 10%."},"tax":{"type":"number","description":"The tax on the cart, in `currency`."},"tax_original":{"type":"number","description":"The tax before discounts, in `currency`."},"total":{"type":"number","description":"What the shopper pays, with discounts and tax, in `currency`."},"total_original":{"type":"number","description":"The total before discounts (`subtotal_original` plus `shipping_original` plus `tax_original`), in `currency`."},"tax_inclusive":{"type":"boolean","description":"True when item prices already include tax."},"total_payments":{"type":"number","description":"The sum of successful payments made for the cart, in `currency`."},"total_remaining":{"type":"number","description":"`total` minus `total_payments`, in `currency`."},"discount_on_gross":{"type":"boolean","description":"True when discounts are worked out on prices that include tax."},"settlement_currency":{"type":"string","description":"The currency the payment will be settled to your account in. Not returned to a limited token.","x-exclude-limited":true},"settlement_subtotal":{"type":"number","description":"`subtotal` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_subtotal_original":{"type":"number","description":"`subtotal_original` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_shipping":{"type":"number","description":"`shipping` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_shipping_original":{"type":"number","description":"`shipping_original` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_discount":{"type":"number","description":"`discount` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_total_discounts":{"type":"number","description":"`total_discounts` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_tax":{"type":"number","description":"`tax` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_tax_original":{"type":"number","description":"`tax_original` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_total":{"type":"number","description":"`total` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_total_original":{"type":"number","description":"`total_original` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"customer_ip_address":{"type":["string","null"],"description":"The IP address of the shopper's last request to the cart."},"customer_ip_country":{"type":["string","null"],"description":"The ISO 3166-1 alpha-2 country of `customer_ip_address`."},"referrer":{"type":["string","null"],"description":"Your own label for where the sale came from, such as a campaign. Up to 256 characters."},"affiliate_id":{"type":["string","null"],"description":"The affiliate or partner credited with the sale. Up to 75 characters."},"promotion_code":{"type":["string","null"],"description":"The coupon code applied to the cart, if any."},"items_count":{"type":"integer","description":"The number of lines in `items`."},"items_quantity":{"type":"number","description":"The sum of the quantities of all items."},"items":{"type":"array","description":"The items in the cart.","items":{"$ref":"#/components/schemas/cart_item"}},"shipping_item":{"description":"The shipping line for the selected shipping method, or null when no shipping applies.","oneOf":[{"$ref":"#/components/schemas/shipping_item"},{"type":"null"}]},"customer":{"description":"The customer on the cart, always in full, or null when there is none yet.","oneOf":[{"$ref":"#/components/schemas/customer"},{"type":"null"}]},"order":{"type":["string","object","null"],"description":"Null while the cart is open. Once paid, the URL of the order, or the order itself with `expand=order`.","x-expandable-url":true},"payments":{"type":["string","object"],"description":"The URL of the payments made for the cart, or an offset list of them with `expand=payments` (not inside a list of carts).","x-expandable-url":true},"promotions":{"type":["string","object"],"description":"The URL of the promotions applied to the cart, or an offset list of them with `expand=promotions` (not inside a list of carts).","x-expandable-url":true},"options":{"description":"The URL of the cart options, or the options object with `expand=options` (not inside a list of carts).","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/cart_options"}],"x-expandable-url":true},"meta":{"description":"Your own data for the cart: a string or an object, up to 2048 characters. Copied to the order when the cart is paid.","type":["object","string","null"]},"related_products":{"type":["string","object"],"description":"The URL of products related to the items in the cart, or an offset list of them with `expand=related_products` (not inside a list of carts).","x-expandable-url":true},"cross_sells":{"type":["string","object"],"description":"The URL of cross-sell offers for the cart, or an offset list of them with `expand=cross_sells` (not inside a list of carts).","x-expandable-url":true},"up_sells":{"type":["string","object"],"description":"The URL of up-sell offers for the cart, or an offset list of them with `expand=up_sells` (not inside a list of carts).","x-expandable-url":true},"formatted":{"type":"object","description":"The money amounts, dates and IP country as display strings in the shopper's locale. Only present with `formatted=true`.","additionalProperties":{"type":["string","null"]}},"warnings":{"type":"array","description":"Only on a cart read. Present when a bundle in the cart holds a product that was since deleted or made inactive. The cart can still be read, but a change or a payment fails until the bundle is removed.","items":{"$ref":"#/components/schemas/error"}}},"required":["object","url","cart_id","date_created","date_modified","test","account_id","order_id","open","payment_status","currency","subtotal","subtotal_original","shipping","shipping_original","discount","item_discounts","total_discounts","total_discounts_percent","tax","tax_original","total","total_original","tax_inclusive","total_payments","total_remaining","discount_on_gross","customer_ip_address","customer_ip_country","referrer","affiliate_id","promotion_code","items_count","items_quantity","items","shipping_item","customer","promotions","options","meta","related_products","cross_sells","up_sells"],"example":{"object":"cart","url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1","cart_id":"0091307952465CafhFSTa1","date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:21:40Z","test":true,"account_id":"AB1234","order_id":"8352-CSGYX-348","open":true,"payment_status":null,"currency":"USD","subtotal":199.9,"subtotal_original":199.9,"shipping":0,"shipping_original":0,"discount":0,"item_discounts":0,"total_discounts":0,"total_discounts_percent":0,"tax":14.99,"tax_original":14.99,"total":214.89,"total_original":214.89,"tax_inclusive":false,"total_payments":0,"total_remaining":214.89,"discount_on_gross":false,"settlement_currency":"USD","settlement_subtotal":199.9,"settlement_subtotal_original":199.9,"settlement_shipping":0,"settlement_shipping_original":0,"settlement_discount":0,"settlement_total_discounts":0,"settlement_tax":14.99,"settlement_tax_original":14.99,"settlement_total":214.89,"settlement_total_original":214.89,"customer_ip_address":"203.0.113.44","customer_ip_country":"US","referrer":"campaign-0044","affiliate_id":null,"promotion_code":null,"items_count":1,"items_quantity":2,"items":[{"object":"cart_item","url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/items/pdf-pro.test","item_id":"pdf-pro.test","cross_sell_id":null,"up_sell_id":null,"bundle_id":null,"bundle_group_id":null,"date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:19:12Z","product_id":"pdf-pro.test","cart_id":"0091307952465CafhFSTa1","name":"PDF Viewer Pro","type":"digital","quantity":2,"currency":"USD","price":99.95,"price_original":99.95,"reference_price":null,"reference_currency":null,"subtotal":199.9,"subtotal_original":199.9,"discount":0,"discount_percent":0,"tax":14.99,"tax_original":14.99,"total":214.89,"total_original":214.89,"tax_rate":0.075,"tax_code":null,"settlement_currency":"USD","settlement_price":99.95,"settlement_price_original":99.95,"settlement_subtotal":199.9,"settlement_subtotal_original":199.9,"settlement_discount":0,"settlement_tax":14.99,"settlement_tax_original":14.99,"settlement_total":214.89,"settlement_total_original":214.89,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription_plan":null,"subscription_terms":null,"meta":null}],"shipping_item":null,"customer":{"object":"customer","url":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1","customer_id":"0091307952481CuXUhvCA1","date_created":"2026-11-07T19:19:12Z","date_modified":"2026-11-07T19:21:40Z","account_id":"AB1234","test":true,"company_name":null,"name":"John Smith","email":"john@example.com","phone":null,"billing_address":{"object":"address","name":null,"address_1":null,"address_2":null,"city":null,"state_prov":null,"postal_code":"27265","country":"US","email":null,"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":null,"tax_number":null,"tax_exempt":false,"has_payments":false,"locale":"en-US","meta":null,"payment_methods":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/payment_methods","payments":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/payments","refunds":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/refunds","orders":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/orders","subscriptions":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/subscriptions","invoices":"https://api.comecero.com/api/v1/customers/0091307952481CuXUhvCA1/invoices"},"order":null,"payments":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/payments","promotions":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/promotions","options":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/options","meta":null,"related_products":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/related_products","cross_sells":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/cross_sells","up_sells":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/up_sells"}},"cart_list":{"type":"object","title":"cart_list","description":"A cursor-based list of carts.","x-response":true,"properties":{"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_after_item":{"type":["string","null"],"description":"The `after_item` value for the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_before_item":{"type":["string","null"],"description":"The `before_item` value for the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page. Only present when you asked for a page with `after_item` or `before_item`."},"data":{"type":"array","description":"The carts on this page.","items":{"$ref":"#/components/schemas/cart"}}},"required":["next_page_url","next_page_after_item","previous_page_url","previous_page_before_item","data"]},"address_request":{"type":"object","title":"address_request","x-limited":true,"x-request":true,"description":"A postal address you send, for example as a customer's `billing_address` or `shipping_address`, or on a card. Every field is optional. On an update, only the fields you send change. Send the whole address as `null` to clear it.","properties":{"name":{"type":["string","null"],"maxLength":75,"description":"The name of the person at the address. When you leave it out on a new address, the customer's name is used."},"address_1":{"type":["string","null"],"maxLength":75,"description":"The first line of the street address."},"address_2":{"type":["string","null"],"maxLength":75,"description":"The second line of the street address."},"city":{"type":["string","null"],"maxLength":75,"description":"The city."},"state_prov":{"type":["string","null"],"maxLength":75,"description":"The state or province. For `US` and `CA` it must be a real state or province, as its abbreviation or full name. When the postal code is known, Comecero replaces it with the state or province of that postal code."},"postal_code":{"type":["string","null"],"maxLength":75,"description":"The postal or zip code. Checked for `US` (`12345` or `12345-6789`) and `CA` (`A1A1A1`) addresses."},"country":{"type":["string","null"],"maxLength":75,"description":"The two-letter ISO 3166-1 alpha-2 country code, for example `US`."},"email":{"type":["string","null"],"format":"email","maxLength":75,"description":"The email address of the person at the address. Must be a valid email."},"meta":{"description":"Your own data for this address, as an object or a string. At most 2,048 characters when serialized."}},"example":{"name":"John Doe","address_1":"123 Main St.","address_2":"Apt 4","city":"New York","state_prov":"NY","postal_code":"10019","country":"US","email":"john@example.com"}},"customer_request":{"type":"object","title":"customer_request","x-limited":true,"x-request":true,"description":"The fields you send to create or update a customer. Every field is optional. On an update, only the fields you send change. The same object is used for the `customer` of a cart, invoice or payment.","properties":{"customer_id":{"type":"string","maxLength":30,"description":"On create only: your own id for the customer. Letters, numbers, underscores, dashes and periods, and it must not be in use. Leave it out and Comecero makes one. On an update it must match the id in the URL. On a cart, invoice or payment, sending the id of an existing customer updates that customer."},"company_name":{"type":["string","null"],"maxLength":75,"description":"The customer's company name."},"name":{"type":["string","null"],"maxLength":75,"description":"The customer's name."},"email":{"type":"string","format":"email","maxLength":75,"description":"The customer's email address. Must be valid. Once set it can be changed but not cleared: `null` on an update is ignored."},"phone":{"type":["string","null"],"maxLength":25,"description":"The customer's phone number."},"billing_address":{"oneOf":[{"$ref":"#/components/schemas/address_request"},{"type":"null"}],"description":"The billing address. On an update, `null` clears it."},"shipping_address":{"oneOf":[{"$ref":"#/components/schemas/address_request"},{"type":"null"}],"description":"The shipping address. On an update, `null` clears it."},"username":{"type":"string","minLength":5,"maxLength":25,"description":"A username so the customer can sign in (see Log in a customer). Stored in lower case. Must not be taken by another customer of the account (`409`). It can be changed later."},"password":{"type":"string","minLength":6,"maxLength":50,"writeOnly":true,"description":"The customer's password, used with the username. Stored hashed, never returned."},"tax_number":{"type":["string","null"],"description":"The customer's tax or VAT number. For a customer in an EU country, the number is checked with the EU VIES service: an invalid number is a `400`, and `422` means the service could not be reached (try again). A valid EU number makes the customer tax exempt. A GB number does not."},"tax_exempt":{"type":"boolean","description":"Set the customer tax exempt. Only a secret token can set this; from a limited token it is ignored. It has no effect for a customer in an EU country (not GB), where `tax_number` decides. On a reseller account only Comecero staff can change it."},"locale":{"type":["string","null"],"description":"The customer's language and region, for example `en-US`. Read on update only. On create, the locale of the request is used."},"meta":{"description":"Your own data for this customer, as an object or a string. At most 2,048 characters when serialized."}},"example":{"name":"John Doe","email":"john@example.com","phone":"555-555-0123","billing_address":{"name":"John Doe","address_1":"123 Main St.","city":"New York","state_prov":"NY","postal_code":"10019","country":"US"},"username":"johndoe","password":"s3cret-pass"}},"cart_item_request":{"type":"object","title":"cart_item_request","description":"An item to add to a cart, or the changes to an item. The price comes from the product unless a secret or trusted token sends `reference_price`.","x-limited":true,"x-request":true,"properties":{"product_id":{"type":"string","description":"The product to add. Required when you add an item (error `BpmhEyl` without it). The product must exist, must not be deleted, must be active and must have stock. A test product cannot go in a live cart. Adding a product that is already in the cart replaces that item. Ignored on an update: the item keeps its product."},"item_id":{"type":"string","description":"Only on an update, and only when it matches the item_id in the URL. Never needed."},"quantity":{"type":"integer","minimum":0,"description":"How many units. A whole number, not negative. Defaults to 1 when you add an item."},"reference_price":{"type":"number","description":"The unit price to charge instead of the product's price, in `reference_currency`. If that currency is not the cart's, the price is converted. A limited token may not send this field: core answers `403` (error `m82tixT`).","x-exclude-limited":true},"reference_currency":{"type":"string","description":"The ISO 4217 currency of `reference_price`. Must be a payment currency of your account. Defaults to the cart currency. A limited token may not send this field: core answers `403` (error `m82tixT`).","x-exclude-limited":true},"cross_sell_id":{"type":"string","description":"The `cross_sell_id` of an offer from `GET /carts/{cart_id}/cross_sells` when the shopper takes it. It applies the offer's discount. An id from another cart is refused."},"up_sell_id":{"type":"string","description":"The `up_sell_id` of an offer from `GET /carts/{cart_id}/up_sells` when the shopper takes it. When you add the item alone, the item the offer upgrades is removed from the cart."},"meta":{"description":"Your own data for the item, a string or an object, up to 2048 characters. Copied to the order item when the cart is paid.","type":["object","string","null"]}},"example":{"product_id":"widget-pro.test","quantity":2}},"cart_request":{"type":"object","title":"cart_request","description":"The fields you can set on a cart. On an update, only the fields you send change, except `items`: sending `items` replaces every item in the cart.","x-limited":true,"x-request":true,"properties":{"order_id":{"type":"string","maxLength":30,"description":"Only when you create the cart. The id the order gets when the cart is paid. Letters, numbers, underscores, dashes and periods only, and not in use by another order or invoice. Stored in upper case. Assigned for you when left out."},"currency":{"type":"string","description":"The ISO 4217 currency the shopper pays in. Must be a currency your account takes. Guessed from the shopper's location when left out on create. Changing it reprices every item."},"customer_id":{"type":["string","null"],"description":"An existing customer to put on the cart. Send this or `customer`, not both. A token made by a customer login always uses its own customer."},"customer":{"$ref":"#/components/schemas/customer_request","description":"The shopper's details. To change an existing customer, include its `customer_id` inside this object. When you send no customer on create, an empty customer is made for the cart."},"items":{"type":"array","description":"The items in the cart. Each needs a `product_id`. On an update this list replaces all items; a reference price set before is kept for an item that is sent again without one.","items":{"$ref":"#/components/schemas/cart_item_request"}},"promotion_code":{"type":["string","null"],"description":"A coupon code. It must be valid for this shopper (error code `invalid_promotion_code`). Send null to remove it."},"shipping_method_id":{"type":["string","null"],"description":"The shipping method the shopper picked. It must exist and ship to the customer's location. Pick one from `shipping_quotes` in the cart options."},"referrer":{"type":["string","null"],"maxLength":256,"description":"Your own label for where the sale came from, such as a campaign."},"affiliate_id":{"type":["string","null"],"maxLength":75,"description":"The affiliate or partner credited with the sale."},"meta":{"description":"Your own data for the cart, a string or an object, up to 2048 characters. Copied to the order when the cart is paid.","type":["object","string","null"]}},"example":{"currency":"USD","items":[{"product_id":"widget-pro.test","quantity":2}],"customer":{"name":"John Smith","email":"john@example.com","billing_address":{"country":"US","postal_code":"27265"}},"referrer":"campaign-0044"}},"cart_cross_sell":{"type":"object","title":"cart_cross_sell","description":"A cross-sell offer for a cart: another product, often at a discount, shown because of what is in the cart. To take it, add the product with this `cross_sell_id`.","x-limited":true,"x-response":true,"properties":{"cross_sell_id":{"type":"string","description":"The id to send as `cross_sell_id` when you add the item. It only works for this cart."},"product_id":{"type":"string","description":"The product offered."},"name":{"type":"string","description":"The product name."},"price":{"type":"number","description":"The offer price of one unit, in `currency`."},"price_original":{"type":"number","description":"The price before the offer discount, in `currency`."},"discount":{"type":"number","description":"The offer discount on one unit, in `currency`."},"discount_percent":{"type":"number","description":"The discount as a fraction, rounded to a whole percent."},"currency":{"type":"string","description":"The cart currency."},"product":{"type":["string","object"],"description":"The URL of the product, or the product with `expand=product` (`expand=cross_sells.product` on a cart).","x-expandable-url":true},"formatted":{"type":"object","description":"Amounts as display strings. Only present with `formatted=true`.","additionalProperties":{"type":"string"}}},"required":["cross_sell_id","product_id","name","price","price_original","discount","discount_percent","currency","product"],"example":{"cross_sell_id":"0091307952500PtXk3Lw-a1b2","product_id":"pdf-fonts.test","name":"Font Pack","price":15.99,"price_original":19.99,"discount":4,"discount_percent":0.2,"currency":"USD","product":"https://api.comecero.com/api/v1/products/pdf-fonts.test"}},"cart_cross_sell_list":{"type":"object","title":"cart_cross_sell_list","description":"An offset-based list of cross-sell offers for a cart. It is one page.","x-response":true,"properties":{"total_items":{"type":"integer","description":"The number of items in the whole list."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The page number of this page, starting at 1."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The offers on this page.","items":{"$ref":"#/components/schemas/cart_cross_sell"}}},"required":["total_items","total_pages","current_page","next_page_url","next_page_offset","previous_page_url","previous_page_offset","current_page_url","data"]},"cart_item_list":{"type":"object","title":"cart_item_list","description":"An offset-based list of the items in a cart.","x-response":true,"properties":{"total_items":{"type":"integer","description":"The number of items in the whole list."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The page number of this page, starting at 1."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The items on this page.","items":{"$ref":"#/components/schemas/cart_item"}}},"required":["total_items","total_pages","current_page","next_page_url","next_page_offset","previous_page_url","previous_page_offset","current_page_url","data"]},"subscription_terms":{"type":"object","title":"subscription_terms","description":"The billing terms of a subscription item: what is billed, how often, any trial and any discount. Also returned for a product or cart item before a subscription exists, so you can show the shopper what they sign up for.","properties":{"object":{"type":"string","enum":["subscription_terms"],"description":"The object type. Always `subscription_terms`."},"price":{"type":"number","description":"The price of one unit for each billing period, in `currency`."},"quantity":{"type":"number","description":"How many units are billed."},"currency":{"type":"string","description":"The three-letter ISO 4217 currency of `price` and `discount`."},"discount":{"type":"number","description":"The discount taken off each unit, in `currency`. `0` when none."},"discount_price":{"type":["number","null"],"description":"The unit price after the discount, in `currency`. `null` when there is no discount."},"discount_apply_count":{"type":["integer","null"],"description":"How many billings the discount applies to. `null` means every billing."},"discount_applied_count":{"type":"integer","description":"How many billings the discount has been applied to so far."},"tax_inclusve":{"type":"boolean","description":"`true` when prices include tax for the customer's location. The field name is spelled this way in the API."},"billing_interval":{"type":"integer","description":"How many `billing_interval_unit` make one billing period."},"billing_interval_unit":{"type":"string","enum":["minute","hour","day","month","year"],"description":"The unit of the billing period."},"billing_interval_description":{"type":"string","description":"The billing period as text, for example `1 month` or `3 months`."},"trial_interval":{"type":["integer","null"],"description":"The trial length in `trial_interval_unit`. `null` when there is no trial."},"trial_interval_unit":{"type":["string","null"],"enum":["minute","hour","day","month","year",null],"description":"The unit of the trial. `null` when there is no trial."},"trial_interval_description":{"type":["string","null"],"description":"The trial length as text, for example `14 days`. `null` when there is no trial."},"date_trial_start":{"type":["string","null"],"format":"date-time","description":"When the trial starts or started. `null` when there is no trial."},"date_trial_end":{"type":["string","null"],"format":"date-time","description":"When the trial ends or ended. `null` when there is no trial."},"end_at_billing_count":{"type":["integer","null"],"description":"The number of billings after which billing stops. `null` means it bills until cancelled."},"date_billing_start":{"type":"string","format":"date-time","description":"When paid billing starts (the end of the trial, or the start date)."},"subscription_id":{"type":["string","null"],"description":"The subscription these terms belong to. `null` before a subscription exists."},"description":{"type":"string","description":"The terms as one sentence in the customer's language, ready to show."},"price_per_day":{"type":"number","description":"The price worked out per day, in `currency`. For display only."},"price_per_month":{"type":"number","description":"The price worked out per month, in `currency`. For display only."},"price_per_year":{"type":"number","description":"The price worked out per year, in `currency`. For display only."},"formatted":{"type":"object","description":"Display text for the prices and dates. Only returned with `formatted=true`."}},"required":["object","price","quantity","currency","discount","discount_price","discount_apply_count","discount_applied_count","tax_inclusve","billing_interval","billing_interval_unit","billing_interval_description","trial_interval","trial_interval_unit","trial_interval_description","date_trial_start","date_trial_end","end_at_billing_count","date_billing_start","subscription_id","description","price_per_day","price_per_month","price_per_year"],"example":{"object":"subscription_terms","price":19.95,"quantity":1,"currency":"USD","discount":0,"discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"tax_inclusve":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"date_trial_start":null,"date_trial_end":null,"end_at_billing_count":null,"date_billing_start":"2026-10-02T15:21:28Z","subscription_id":"0093799318129SuLByRPW8","description":"Acme Pro (monthly) is a subscription that renews every month with a payment of $19.95.","price_per_day":0.66,"price_per_month":19.95,"price_per_year":239.4}},"cart_login_request":{"type":"object","title":"cart_login_request","description":"A customer's sign-in details.","x-limited":true,"x-request":true,"properties":{"username":{"type":"string","description":"The customer's username."},"password":{"type":"string","format":"password","description":"The customer's password."}},"required":["username","password"],"example":{"username":"john@example.com","password":"example-password"}},"response_data":{"type":"object","title":"response_data","description":"What the gateway sent back for a payment, by payment method type. For an `initiated` payment this is where the next step is: `redirect_url` (send the shopper there), `next_action` (run the Comecero Express Payments 3-D Secure check on your own page) or, for `stripe`, the Stripe.js values to confirm with. When the shopper is back, get the payment and commit it only while it is still `initiated`: the Comecero 3-D Secure page commits the payment itself. Wallet, ACH and store credit payments return an empty object.","x-limited":true,"x-response":true,"properties":{"object":{"type":"string","enum":["payment.response_data.credit_card","payment.response_data.paypal","payment.response_data.amazon_pay","payment.response_data.apple_pay","payment.response_data.stripe"],"description":"The object type, by payment method type."},"url":{"type":"string","format":"uri","description":"The full URL of the response data."},"avs_match":{"type":"boolean","description":"Card only. True when the address check passed. Not returned to a limited token.","x-exclude-limited":true},"avs_code":{"type":["string","null"],"description":"Card only. The gateway's address check code. Not returned to a limited token.","x-exclude-limited":true},"avs_message":{"type":["string","null"],"description":"Card only. The address check message. Not returned to a limited token.","x-exclude-limited":true},"cvv_match":{"type":"boolean","description":"Card only. True when the security code check passed. Not returned to a limited token.","x-exclude-limited":true},"cvv_code":{"type":["string","null"],"description":"Card only. The gateway's security code check code. Not returned to a limited token.","x-exclude-limited":true},"cvv_message":{"type":["string","null"],"description":"Card only. The security code check message. Not returned to a limited token.","x-exclude-limited":true},"gateway_order_id":{"type":"string","description":"Card only, PayPal card gateway. PayPal's order id. Only present when set. Not returned to a limited token.","x-exclude-limited":true},"gateway_error_debug_id":{"type":"string","description":"Card only, PayPal card gateway. PayPal's debug id of the last failed call, for PayPal support. Only present when set. Not returned to a limited token.","x-exclude-limited":true},"three_ds_liability_shift":{"type":["string","null"],"description":"Card only. The 3-D Secure liability shift result. Only present after a 3-D Secure check. Not returned to a limited token.","x-exclude-limited":true},"three_ds_enrollment_status":{"type":["string","null"],"description":"Card only. The 3-D Secure enrollment status. Only present after a 3-D Secure check. Not returned to a limited token.","x-exclude-limited":true},"three_ds_authentication_status":{"type":["string","null"],"description":"Card only. The 3-D Secure authentication status. Only present after a 3-D Secure check. Not returned to a limited token.","x-exclude-limited":true},"redirect_url":{"type":["string","null"],"format":"uri","description":"For a card payment, only present while a 3-D Secure check is waiting: the Comecero-hosted check page, or the gateway's own page (PayPal card). For PayPal, the page where the buyer approves, also when a commit asks the buyer to approve a changed total. Send the shopper there. The Comecero-hosted check page commits the payment itself when the check ends. So when the shopper is back, get the payment and call `POST /payments/{payment_id}/commit` only while it is still `initiated` (PayPal and the PayPal card page always need it)."},"next_action":{"type":"object","description":"Card only, only present while a Comecero Express Payments 3-D Secure check is waiting. Lets your own page run the check with Stripe.js (`handleNextAction` with `client_secret`) instead of following `redirect_url`. Then get the payment and call `POST /payments/{payment_id}/commit` only while it is still `initiated`.","properties":{"type":{"type":"string","enum":["stripe_3ds"]},"client_secret":{"type":"string"},"publishable_key":{"type":"string"},"stripe_account":{"type":"string"}}},"billing_agreement_accept_status":{"type":"boolean","description":"PayPal only. True when the buyer accepted a billing agreement for later payments."},"charge_id":{"type":["string","null"],"description":"Amazon Pay only. Amazon's charge id."},"charge_permission_id":{"type":["string","null"],"description":"Amazon Pay only. Amazon's charge permission id."},"refund_id":{"type":["string","null"],"description":"Amazon Pay only. Amazon's refund id, if any."},"committed":{"type":"boolean","description":"Amazon Pay only. True once the payment was committed."},"eligible_payment_method_types":{"type":["array","null"],"items":{"type":"string"},"description":"Stripe only. The methods the shopper can pay with on this payment."},"client_secret":{"type":["string","null"],"description":"Stripe only. The client secret to confirm the payment with in Stripe.js. Returned while the payment is `initiated`, `processing` or `pending`."},"publishable_key":{"type":["string","null"],"description":"Stripe only. The key to load Stripe.js with. Same rule as `client_secret`."},"stripe_account":{"type":["string","null"],"description":"Stripe only. The account to pass to Stripe.js. Same rule as `client_secret`."},"api_version":{"type":["string","null"],"description":"Stripe only. The API version for Stripe.js, when needed. Same rule as `client_secret`."},"betas":{"type":["string","null"],"description":"Stripe only. The betas value for Stripe.js, when needed. Same rule as `client_secret`."},"selected_payment_method":{"type":["string","null"],"description":"Stripe only. The method the shopper paid with, once known."}},"example":{"object":"payment.response_data.credit_card","url":"https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC/response_data","avs_match":true,"avs_code":"M","avs_message":null,"cvv_match":true,"cvv_code":"M","cvv_message":null}},"payment_fee_summary":{"type":"object","title":"payment_fee_summary","description":"The fees charged on a payment, added up. Each currency's sums are kept apart in `totals`; the top-level amounts are those of the first currency.","x-response":true,"properties":{"object":{"type":"string","enum":["fee_summary"],"description":"The object type. Always `fee_summary`."},"url":{"type":["string","null"],"format":"uri","description":"The full URL of the summary. Null when the payment has no fees yet."},"fixed_amount":{"type":"number","description":"The sum of fixed fees, in `currency`."},"percentage_amount":{"type":"number","description":"The sum of percentage fees, in `currency`."},"total":{"type":"number","description":"All fees, in `currency`."},"currency":{"type":["string","null"],"description":"The currency of the top-level amounts. Null when there are no fees."},"totals":{"type":"array","description":"The sums for each currency, the top-level currency first.","items":{"type":"object","properties":{"currency":{"type":"string"},"fixed_amount":{"type":"number"},"percentage_amount":{"type":"number"},"total":{"type":"number"},"formatted":{"type":"object","description":"`total` as a display string. Only with `formatted=true`.","properties":{"total":{"type":"string"}}}}}},"formatted":{"type":"object","description":"The amounts as display strings. Only present with `formatted=true`.","additionalProperties":{"type":"string"}}},"required":["object","url","fixed_amount","percentage_amount","total","currency","totals"],"example":{"object":"fee_summary","url":"https://api.comecero.com/api/v1/payments/0090460891496PyrYzd9DC/fee_summary","fixed_amount":0.3,"percentage_amount":6.23,"total":6.53,"currency":"USD","totals":[{"currency":"USD","fixed_amount":0.3,"percentage_amount":6.23,"total":6.53}]}},"payment":{"type":"object","title":"payment","description":"Money taken, or being taken, from a customer. `status` says where the payment is. A payment that needs the shopper to act (PayPal approval, a 3-D Secure check, a Comecero Express Payments confirmation) comes back `initiated` with what to do in `response_data`; you finish it with `POST /payments/{payment_id}/commit`. A limited token does not see the gateway fields or the settlement amounts.","x-limited":true,"x-response":true,"properties":{"object":{"type":"string","enum":["payment"],"description":"The object type. Always `payment`."},"url":{"type":"string","format":"uri","description":"The full URL of the payment."},"payment_id":{"type":"string","description":"The id of the payment."},"account_id":{"type":"string","description":"The account the payment belongs to."},"success":{"type":"boolean","description":"True when the gateway accepted the payment or the step so far. True for `initiated`, `processing`, `pending`, `completed` and `cancelled`; false for `failed`."},"status":{"type":"string","enum":["initiated","processing","pending","completed","failed","cancelled","refunded","retry"],"description":"`initiated`: created, waiting for the shopper to approve or pass a check; commit it when they are done. `processing`: the gateway has it and will answer later (for example ACH); the cart or invoice cannot change meanwhile. `pending`: authorized, not yet captured; capture or void it. `completed`: captured. `failed`: declined or in error. `cancelled`: voided. `refunded` and `retry` are also valid values of the status filter."},"date_created":{"type":"string","format":"date-time","description":"When the payment was created."},"date_modified":{"type":"string","format":"date-time","description":"When the payment was last changed."},"date_completed":{"type":["string","null"],"format":"date-time","description":"When the payment was captured, or null if it is not."},"test":{"type":"boolean","description":"True for a test payment."},"currency":{"type":"string","description":"The ISO 4217 currency of the payment."},"subtotal":{"type":"number","description":"The amount without tax and shipping, in `currency`."},"shipping":{"type":"number","description":"The shipping amount without tax, in `currency`."},"tax":{"type":"number","description":"The tax, in `currency`."},"total":{"type":"number","description":"The amount charged, in `currency`."},"customer_ip_address":{"type":["string","null"],"description":"The IP address the payment was made from."},"customer_ip_country":{"type":["string","null"],"description":"The ISO 3166-1 alpha-2 country of `customer_ip_address`."},"description":{"type":["string","null"],"description":"Your description of the payment."},"reference":{"type":["string","null"],"description":"Your own reference for the payment. You can filter lists on it."},"merchant_descriptor":{"type":["string","null"],"description":"What appears on the shopper's card statement."},"merchant_contact":{"type":["string","null"],"description":"The contact shown with the statement descriptor, such as a phone number or web address."},"apply_to_balance":{"type":"boolean","description":"True when the captured total is added to the customer's store credit balance."},"response_code":{"type":"string","description":"`OK` for a successful step, otherwise a code for why the payment failed. Not returned to a limited token.","x-exclude-limited":true},"response_message":{"type":"string","description":"A readable message for `response_code`. Not returned to a limited token.","x-exclude-limited":true},"gateway_transaction_id":{"type":["string","null"],"description":"The gateway's own id for the transaction. Not returned to a limited token.","x-exclude-limited":true},"gateway_error_code":{"type":["string","null"],"description":"The gateway's error code when the payment failed. Not returned to a limited token.","x-exclude-limited":true},"gateway_error_message":{"type":["string","null"],"description":"The gateway's error message when the payment failed. Not returned to a limited token.","x-exclude-limited":true},"risk_decline":{"type":"boolean","description":"True when the payment was declined for fraud risk. Not returned to a limited token.","x-exclude-limited":true},"gateway":{"type":["string","object"],"description":"The URL of the gateway used, or the gateway with `expand=gateway`. Only for a token that may read gateways. Not returned to a limited token.","x-exclude-limited":true,"x-expandable-url":true},"debug":{"type":"string","format":"uri","description":"Only on accounts on the agent model. The URL of the raw gateway exchanges for this payment, for troubleshooting. Not returned to a limited token.","x-exclude-limited":true},"app_id":{"type":["string","null"],"description":"The hosted app the payment came from, if any. Not returned to a limited token.","x-exclude-limited":true},"app_version":{"type":["string","null"],"description":"The version of that app. Not returned to a limited token.","x-exclude-limited":true},"payment_method":{"type":["string","object"],"description":"The URL of the payment method used, or the method itself with `expand=payment_method`.","x-expandable-url":true},"response_data":{"description":"The URL of the payment's response data, or the data itself with `expand=response_data`. This is where a redirect, a 3-D Secure step or the Stripe.js values for an `initiated` payment are.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/response_data"}],"x-expandable-url":true},"reporting_currency":{"type":["string","null"],"description":"Your account's reporting currency."},"reporting_subtotal":{"type":"number","description":"`subtotal` in `reporting_currency`."},"reporting_shipping":{"type":"number","description":"`shipping` in `reporting_currency`."},"reporting_tax":{"type":"number","description":"`tax` in `reporting_currency`."},"reporting_total":{"type":"number","description":"`total` in `reporting_currency`."},"reporting_fx_rate":{"type":"number","description":"The rate from the settlement currency to `reporting_currency`."},"reporting_alt_currency":{"type":"string","description":"Your second reporting currency. Only present when you set one."},"reporting_alt_subtotal":{"type":"number","description":"`subtotal` in `reporting_alt_currency`. Only present with a second reporting currency."},"reporting_alt_shipping":{"type":"number","description":"`shipping` in `reporting_alt_currency`. Only present with a second reporting currency."},"reporting_alt_tax":{"type":"number","description":"`tax` in `reporting_alt_currency`. Only present with a second reporting currency."},"reporting_alt_total":{"type":"number","description":"`total` in `reporting_alt_currency`. Only present with a second reporting currency."},"reporting_alt_fx_rate":{"type":"number","description":"The rate to `reporting_alt_currency`. Only present with a second reporting currency."},"settlement_currency":{"type":"string","description":"The currency the payment settles to your account in. Not returned to a limited token.","x-exclude-limited":true},"settlement_subtotal":{"type":"number","description":"`subtotal` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_shipping":{"type":"number","description":"`shipping` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_tax":{"type":"number","description":"`tax` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"settlement_total":{"type":"number","description":"`total` in `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"fx_rate":{"type":"number","description":"The rate from `currency` to `settlement_currency`. Not returned to a limited token.","x-exclude-limited":true},"customer":{"type":["string","object"],"description":"The URL of the customer, or the customer with `expand=customer`.","x-expandable-url":true},"order":{"type":["string","object","null"],"description":"The URL of the order the payment paid for, the order with `expand=order`, or null.","x-expandable-url":true},"cart":{"type":["string","object","null"],"description":"The URL of the cart the payment was for, the cart with `expand=cart`, or null.","x-expandable-url":true},"invoice":{"type":["string","object","null"],"description":"The URL of the invoice the payment was for, the invoice with `expand=invoice`, or null.","x-expandable-url":true},"refunds":{"type":["string","object"],"description":"The URL of the payment's refunds, or an offset list of them with `expand=refunds` (not inside a list).","x-expandable-url":true},"fees":{"type":["string","object"],"description":"The URL of the payment's fees, or an offset list of them with `expand=fees` (not inside a list). Not returned to a limited token.","x-exclude-limited":true,"x-expandable-url":true},"fee_summary":{"description":"The URL of the payment's fee summary, or the summary with `expand=fee_summary`. Not returned to a limited token.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/payment_fee_summary"}],"x-exclude-limited":true,"x-expandable-url":true},"commissions":{"type":["string","object"],"description":"The URL of the payment's commissions, or an offset list of them with `expand=commissions` (not inside a list). Not returned to a limited token.","x-exclude-limited":true,"x-expandable-url":true},"failed_gateway_attempts":{"type":["string","object"],"description":"The URL of the gateways that declined before this one took the payment. For staff troubleshooting. Not returned to a limited token.","x-exclude-limited":true},"meta":{"description":"Your own data for the payment, a string or an object.","type":["object","string","null"]},"formatted":{"type":"object","description":"Money amounts and dates as display strings. Only present with `formatted=true`.","additionalProperties":{"type":["string","null"]}}},"required":["object","url","payment_id","account_id","success","status","date_created","date_modified","date_completed","test","currency","subtotal","shipping","tax","total","customer_ip_address","customer_ip_country","description","reference","merchant_descriptor","merchant_contact","apply_to_balance","payment_method","response_data","reporting_currency","reporting_subtotal","reporting_shipping","reporting_tax","reporting_total","reporting_fx_rate","meta"],"example":{"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}},"cart_payment_list":{"type":"object","title":"cart_payment_list","description":"An offset-based list of the payments made for a cart.","x-response":true,"properties":{"total_items":{"type":"integer","description":"The number of items in the whole list."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The page number of this page, starting at 1."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The payments on this page.","items":{"$ref":"#/components/schemas/payment"}}},"required":["total_items","total_pages","current_page","next_page_url","next_page_offset","previous_page_url","previous_page_offset","current_page_url","data"]},"payment_method_card_request":{"type":"object","title":"payment_method_card_request","x-limited":true,"x-request":true,"description":"The `data` you send for a card (`type: credit_card`). Send either `number` with the expiry, or `token` alone, never both. Comecero vaults the number and drops the security code once the card has been checked.","properties":{"number":{"type":"string","maxLength":20,"writeOnly":true,"description":"The card number. Spaces and dashes are removed. Must pass the card number check. Required unless you send `token`."},"token":{"type":"string","writeOnly":true,"description":"Instead of `number`, `cvv` and the expiry: the one-time token (`TK` followed by 8 to 40 letters and digits) from the processor's card form, when the shop's card option offers it. Only that processor can charge it."},"cvv":{"type":"string","writeOnly":true,"description":"The card security code. Never stored."},"exp_month":{"type":"integer","minimum":1,"maximum":12,"description":"The expiry month. Required with `number`."},"exp_year":{"type":"integer","description":"The expiry year, as two or four digits. Required with `number`. The card must not have expired and the year must be at most 20 years ahead."},"cardholder_name":{"type":"string","maxLength":100,"description":"The name on the card."},"label":{"type":"string","maxLength":100,"description":"Your name for the card. When left out, the brand and last four are shown."},"billing_address":{"$ref":"#/components/schemas/address_request"}},"example":{"number":"4444555566661111","cvv":"123","exp_month":12,"exp_year":2028,"cardholder_name":"John Doe","billing_address":{"name":"John Doe","address_1":"123 Main St.","city":"New York","state_prov":"NY","postal_code":"10019","country":"US"}}},"payment_method_ach_request":{"type":"object","title":"payment_method_ach_request","x-limited":true,"x-request":true,"description":"The `data` you send for a US bank account (`type: ach`). The routing and account numbers are vaulted and only masks are returned.","properties":{"routing_number":{"type":"string","pattern":"^[0-9]{9}$","writeOnly":true,"description":"The bank's 9-digit routing number."},"account_number":{"type":"string","writeOnly":true,"description":"The bank account number."},"account_type":{"type":"string","enum":["checking","savings"],"description":"The kind of bank account."},"ssnl4":{"type":"string","writeOnly":true,"description":"The last four digits of the account holder's Social Security number, when the processor asks for it."},"license_state":{"type":"string","writeOnly":true,"description":"The state that issued the account holder's driver's license, when the processor asks for it."},"license_number":{"type":"string","writeOnly":true,"description":"The account holder's driver's license number, when the processor asks for it."},"billing_address":{"$ref":"#/components/schemas/address_request"}},"required":["routing_number","account_number","account_type"],"example":{"routing_number":"021000021","account_number":"123456789","account_type":"checking"}},"payment_method_paypal_request":{"type":"object","title":"payment_method_paypal_request","x-limited":true,"x-request":true,"description":"The `data` you send to pay with PayPal (`type: paypal`) on a payment. The payment comes back with a `redirect_url` in its response data: send the shopper there to approve, and PayPal sends them back to `success_url` or `cancel_url`.","properties":{"success_url":{"type":"string","format":"uri","maxLength":2048,"description":"Where PayPal sends the shopper after they approve. Required."},"cancel_url":{"type":"string","format":"uri","maxLength":2048,"description":"Where PayPal sends the shopper if they cancel. Required."},"use_billing_agreement":{"type":"boolean","description":"Ask the shopper to accept a billing agreement, so later payments (such as subscription renewals) can be charged without them."},"no_shipping":{"type":"boolean","default":false,"description":"True when you already collected the shipping address in the cart. PayPal then does not ask for one and does not change the cart's address."}},"required":["success_url","cancel_url"],"example":{"success_url":"https://shop.example.com/checkout/paypal/return","cancel_url":"https://shop.example.com/checkout"}},"payment_method_amazon_pay_request":{"type":"object","title":"payment_method_amazon_pay_request","x-limited":true,"x-request":true,"description":"The `data` you send to pay with Amazon Pay (`type: amazon_pay`) on a payment. Send at least one of `checkout_session_id`, `charge_permission_id` or `buyer_token`.","properties":{"checkout_session_id":{"type":"string","maxLength":255,"description":"The Amazon Pay checkout session id from the Amazon Pay button."},"charge_permission_id":{"type":"string","maxLength":255,"description":"An Amazon Pay charge permission id, to charge again."},"buyer_token":{"type":"string","maxLength":255,"description":"The Amazon Pay buyer token."},"merchant_id":{"type":"string","maxLength":255,"description":"The Amazon Pay merchant id."}},"example":{"checkout_session_id":"bd504926-f659-4ad7-a1a9-9a747aaf5275"}},"payment_method_stripe_request":{"type":"object","title":"payment_method_stripe_request","x-limited":true,"x-request":true,"description":"The `data` you send to pay with Comecero Express Payments (`type: stripe`) on a payment. It carries no card details: the shopper enters them in the payment form on your page. The payment's response data holds what that form needs.","properties":{"return_url":{"type":"string","format":"uri","maxLength":2048,"description":"Where the shopper comes back to after a method that leaves the page, such as a bank redirect or a 3-D Secure check that redirects."},"payment_method_types":{"type":"array","items":{"type":"string"},"description":"Limit the methods offered, for example `[\"card\"]`. Leave out to offer every method the shop takes in the payment's currency."}},"example":{"return_url":"https://shop.example.com/checkout/complete"}},"payment_method_wallet_request":{"type":"object","title":"payment_method_wallet_request","x-limited":true,"x-request":true,"description":"The `data` you send to pay with a device wallet (`type: wallet`) on a payment: the token Google Pay or Apple Pay gave you, which the processor charges as the card it carries.","properties":{"wallet":{"type":"string","enum":["google_pay","apple_pay"],"description":"Which wallet the token came from."},"token":{"type":"string","maxLength":20000,"writeOnly":true,"description":"The wallet's token as the wallet gave it: for Google Pay `tokenizationData.token`, for Apple Pay `payment.token` as JSON. Never returned."},"cardholder_name":{"type":"string","description":"The name on the wallet's card, as the wallet gave it."},"billing_address":{"$ref":"#/components/schemas/address_request"}},"required":["wallet","token"],"example":{"wallet":"google_pay","token":"{\"signature\":\"MEUCIQ...\",\"protocolVersion\":\"ECv2\",\"signedMessage\":\"...\"}","cardholder_name":"John Doe"}},"payment_method_request":{"type":"object","title":"payment_method_request","x-limited":true,"x-request":true,"description":"The payment method you send with a payment, to pay with something that is not already saved. To pay with a saved method, send `payment_method_id` on the payment instead.","properties":{"type":{"type":"string","enum":["credit_card","ach","paypal","amazon_pay","apple_pay","stripe","wallet","customer_account_balance"],"description":"The kind of payment method. `stripe` is Comecero Express Payments. `wallet` is Google Pay or Apple Pay. `customer_account_balance` pays from the customer's store credit, needs no `data`, and fails when the balance does not cover the payment."},"data":{"description":"The details for this `type`. Required for every type except `customer_account_balance`.","anyOf":[{"$ref":"#/components/schemas/payment_method_card_request"},{"$ref":"#/components/schemas/payment_method_ach_request"},{"$ref":"#/components/schemas/payment_method_paypal_request"},{"$ref":"#/components/schemas/payment_method_amazon_pay_request"},{"$ref":"#/components/schemas/payment_method_stripe_request"},{"$ref":"#/components/schemas/payment_method_wallet_request"}]},"save":{"type":"boolean","default":false,"description":"Save the method to the customer for later payments when the payment succeeds. A payment for a cart or invoice with a subscription always saves it."}},"required":["type"],"example":{"type":"credit_card","data":{"number":"4444555566661111","cvv":"123","exp_month":12,"exp_year":2028,"cardholder_name":"John Doe","billing_address":{"name":"John Doe","address_1":"123 Main St.","city":"New York","state_prov":"NY","postal_code":"10019","country":"US"}},"save":true}},"payment_request":{"type":"object","title":"payment_request","description":"A payment to make. For a cart (`POST /carts/{cart_id}/payments`) the amount and currency come from the cart, so you send only who pays and how. For an invoice you may send a `total` to pay part of it. For a payment with no cart or invoice (`POST /payments`) you send the amount and currency.","x-limited":true,"x-request":true,"properties":{"payment_id":{"type":"string","maxLength":30,"description":"Your own id for the payment. Letters, numbers, underscores, dashes and periods, not used before. Assigned for you when left out."},"customer_id":{"type":"string","description":"An existing customer who pays. Send this or `customer`, not both. For a cart or invoice it must be the cart's or invoice's customer, and can be left out."},"customer":{"$ref":"#/components/schemas/customer_request","description":"The customer's details. To change an existing customer, include its `customer_id`. Send this or `customer_id`, not both."},"payment_method_id":{"type":"string","description":"A saved payment method of the customer. Send this or `payment_method`, not both. With neither, the customer's default method is used, and the request fails when there is none."},"payment_method":{"$ref":"#/components/schemas/payment_method_request","description":"How the customer pays: a `type` (`credit_card`, `paypal`, `amazon_pay`, `apple_pay`, `ach`, `stripe`, `wallet` or `customer_account_balance`) and its `data`. Your account needs a gateway for that type in the payment currency."},"currency":{"type":"string","description":"The ISO 4217 currency. Required for a payment with no cart or invoice. Not allowed for a cart or an invoice (error `i1pLDWP` or `DQQa1EN`)."},"total":{"type":"number","minimum":0,"description":"The amount to charge. For a payment with no cart or invoice, send `total`, `subtotal` or `shipping`. For an invoice, an amount up to what is left to pay. Not allowed for a cart (error `i1pLDWP`)."},"subtotal":{"type":"number","minimum":0,"description":"Only for a payment with no cart or invoice. When sent, `total` is worked out as `subtotal` plus `tax` plus `shipping`. When you send both `subtotal` and `total`, the sum must match."},"tax":{"type":"number","minimum":0,"description":"Only for a payment with no cart or invoice. Defaults to 0."},"shipping":{"type":"number","minimum":0,"description":"Only for a payment with no cart or invoice. Defaults to 0."},"capture":{"type":"boolean","description":"For card, PayPal, Amazon Pay, Comecero Express Payments and wallet payments: true to capture at once, false to only authorize (the payment is then `pending`). Left out, your fulfillment settings decide. Ignored for a limited token.","x-exclude-limited":true},"description":{"type":"string","maxLength":256,"description":"Your description of the payment."},"reference":{"type":"string","maxLength":100,"description":"Your own reference for the payment."},"apply_to_balance":{"type":"boolean","description":"Only for a payment with no cart or invoice. True adds the captured total to the customer's store credit balance. Ignored when the payment method is `customer_account_balance`. It is also what lets an account on the reseller model take a payment with no cart or invoice."},"gateway_id":{"type":"string","description":"Use this gateway instead of letting Comecero choose. It must be an active gateway of your own. Not allowed on an account on the reseller model."},"return_url":{"type":"string","format":"uri","maxLength":2000,"description":"Where the shopper's browser comes back to after a bank check on the card gateway's own page (PayPal card payments). `{{payment_id}}` in it is replaced with the payment id. An absolute https address; in test mode http on localhost is allowed too. Without a usable one, a payment that needs such a check is declined. Not stored or returned."},"risk_session_id":{"type":"string","description":"The PayPal FraudNet session id from the browser, when the card option has `paypal_fraudnet_source_id`. 16 to 36 letters, digits or dashes. A value that does not fit is ignored. Not stored or returned."},"device_session_id":{"type":"string","description":"The Stripe Radar session id (`rse_...`) made in the browser, when the card option has `stripe_publishable_key`. A value that does not fit is ignored. Not stored or returned."},"ignore_bad_avs":{"type":"boolean","description":"Only for secret and trusted tokens. True lets a card payment go ahead when the address check fails.","x-exclude-limited":true},"merchant_descriptor":{"type":"string","description":"Only for an account on the agent model with a secret or trusted token. The text on the shopper's card statement. Defaults to your payment settings.","x-exclude-limited":true},"merchant_contact":{"type":"string","description":"Only for an account on the agent model with a secret or trusted token. The contact shown with the statement text.","x-exclude-limited":true},"meta":{"description":"Your own data for the payment, a string or an object, up to 2048 characters.","type":["object","string","null"]}},"example":{"customer":{"name":"John Smith","email":"john@example.com","billing_address":{"address_1":"1 Main St","city":"High Point","state_prov":"NC","postal_code":"27265","country":"US"}},"payment_method":{"type":"credit_card","data":{"number":"4444555566661111","exp_month":12,"exp_year":2030,"cvv":"123","cardholder_name":"John Smith"}}}},"price":{"type":"object","title":"price","description":"A price in one currency.","properties":{"price":{"type":"number","description":"The amount, in the currency given by `currency`."},"currency":{"type":"string","description":"The three-letter ISO 4217 currency code, for example `USD`."},"formatted":{"type":"object","description":"Present only when you send `formatted=true`.","properties":{"price":{"type":"string","description":"The price as display text in the shopper's language, for example `$49.95`."}}}},"required":["price","currency"],"example":{"price":49.95,"currency":"USD"}},"promotion_coupon_config":{"type":"object","title":"promotion_coupon_config","description":"The rules of a coupon. Give exactly one of `discount_percent` and `discount_amount`, and exactly one of `code` and `generator_prefix`.","properties":{"type":{"type":"string","enum":["order","product","shipping"],"description":"What the coupon takes money off: the order subtotal, the products in `product_ids`, or shipping. Order and shipping coupons cannot apply to recurring payments."},"code":{"type":["string","null"],"maxLength":50,"description":"The code shoppers enter. Letters, numbers, dashes, underscores and periods only. Must not be in use and must not look like a generated code. Cannot be changed after the coupon is created."},"generator_prefix":{"type":["string","null"],"maxLength":10,"description":"For codes you generate yourself, one per customer: the letters and numbers every generated code starts with. Must not be in use. Cannot be changed after the coupon is created. Each generated code works once."},"generator_secret_key":{"type":["string","null"],"minLength":12,"maxLength":64,"description":"The secret used to sign generated codes, 12 to 64 letters and numbers. Made for you when you send a `generator_prefix` without one."},"discount_percent":{"type":["number","null"],"exclusiveMinimum":0,"maximum":1,"description":"The discount as a fraction, for example `0.1` for 10%. Greater than 0, at most 1."},"discount_amount":{"type":["array","null"],"description":"A fixed discount, one per currency. Each amount must be greater than 0. Other currencies are converted.","items":{"$ref":"#/components/schemas/price"}},"product_ids":{"type":["array","null"],"maxItems":50,"description":"For a `product` coupon only: the products it applies to, up to 50, or `*` for all. Each must exist, not be deleted and be in the same mode (test or live) as the promotion.","items":{"type":"string"}},"exclude_product_ids":{"type":"boolean","description":"When true, the coupon applies to every product except those in `product_ids`. The default is false."},"max_uses_per_customer":{"type":["integer","null"],"description":"How many times one customer may use the code, or null for no limit. Only for a coupon with a single `code`."},"max_uses_global":{"type":["integer","null"],"description":"How many times the code may be used in all, or null for no limit. Only for a coupon with a single `code`."}},"required":["type"],"example":{"type":"order","code":"SAVE10","generator_prefix":null,"generator_secret_key":null,"discount_percent":0.1,"discount_amount":null,"product_ids":null,"exclude_product_ids":false,"max_uses_per_customer":1,"max_uses_global":null}},"promotion_cross_sell_config":{"type":"object","title":"promotion_cross_sell_config","description":"The rules of a cross-sell: offer `product_id`, optionally at a discount, when the cart holds one of `offer_with_product_ids`. Give at most one of `discount_percent` and `discount_amount`.","properties":{"product_id":{"type":"string","description":"The product to offer. Must exist, not be deleted and be in the same mode as the promotion."},"offer_with_product_ids":{"type":"array","minItems":1,"description":"The products that trigger the offer when they are in the cart, or `[\"*\"]` for any product. `*` cannot be mixed with ids. Must not hold `product_id`.","items":{"type":"string"}},"discount_percent":{"type":["number","null"],"exclusiveMinimum":0,"maximum":1,"description":"The discount on the offered product as a fraction, for example `0.15` for 15%."},"discount_amount":{"type":["array","null"],"description":"A fixed discount on the offered product, one per currency. Each must be greater than 0.","items":{"$ref":"#/components/schemas/price"}},"weight":{"type":"integer","minimum":0,"description":"How much this offer counts when several offers compete. 0 or more."},"sort_priority":{"type":"integer","description":"The order in which offers are listed."}},"required":["product_id","offer_with_product_ids"],"example":{"product_id":"widget-case.test","offer_with_product_ids":["widget.test"],"discount_percent":0.15,"discount_amount":null,"weight":1,"sort_priority":0}},"promotion_up_sell_config":{"type":"object","title":"promotion_up_sell_config","description":"The rules of an up-sell: offer `product_id` in place of `offer_with_product_id` when the cart holds it. If the shopper accepts, the item is swapped. Give at most one of `discount_percent` and `discount_amount`.","properties":{"product_id":{"type":"string","description":"The better product to offer. Must exist, not be deleted and be in the same mode as the promotion."},"offer_with_product_id":{"type":"string","description":"The product in the cart that the offer replaces. Must not be `product_id`."},"discount_percent":{"type":["number","null"],"exclusiveMinimum":0,"maximum":1,"description":"The discount on the offered product as a fraction."},"discount_amount":{"type":["array","null"],"description":"A fixed discount on the offered product, one per currency. Each must be greater than 0.","items":{"$ref":"#/components/schemas/price"}},"weight":{"type":"integer","minimum":0,"description":"How much this offer counts when several offers compete. 0 or more."},"sort_priority":{"type":"integer","description":"The order in which offers are listed."}},"required":["product_id","offer_with_product_id"],"example":{"product_id":"widget-pro.test","offer_with_product_id":"widget.test","discount_percent":null,"discount_amount":[{"price":10,"currency":"USD"}],"weight":1,"sort_priority":0}},"promotion":{"type":"object","title":"promotion","description":"A discount rule: a coupon shoppers enter, a cross-sell offered next to another product, or an up-sell offered in place of one. A limited token gets only `object`, `url`, `promotion_id`, `apply_to_recurring` and `apply_to_recurring_count`.","properties":{"object":{"type":"string","enum":["promotion"],"description":"The object type. Always `promotion`."},"url":{"type":"string","format":"uri","description":"The URL of this promotion in the API."},"promotion_id":{"type":"string","description":"The id of the promotion."},"name":{"type":["string","null"],"description":"Your name for the promotion. Not returned to limited tokens."},"test":{"type":"boolean","description":"True for a test-mode promotion. Not returned to limited tokens."},"account_id":{"type":"string","description":"The account the promotion belongs to. Not returned to limited tokens."},"date_created":{"type":"string","format":"date-time","description":"When the promotion was created. Not returned to limited tokens."},"date_modified":{"type":"string","format":"date-time","description":"When the promotion was last changed. Not returned to limited tokens."},"type":{"type":"string","enum":["coupon","cross_sell","up_sell"],"description":"The kind of promotion. Not returned to limited tokens."},"active":{"type":"boolean","description":"True when the promotion can be used. Not returned to limited tokens."},"apply_to_recurring":{"type":"boolean","description":"True when the discount also applies to a subscription's later billings."},"apply_to_recurring_count":{"type":["integer","null"],"description":"How many later billings get the discount, or null for all of them. Only used when `apply_to_recurring` is true."},"use_count":{"type":"integer","description":"How many times the promotion has been used. Not returned to limited tokens."},"expires":{"type":["string","null"],"format":"date-time","description":"When the promotion stops working, or null for never. Not returned to limited tokens."},"comments":{"type":["string","null"],"description":"Your notes. Not returned to limited tokens."},"config":{"description":"The rules of the promotion, by `type`. Not returned to limited tokens.","oneOf":[{"$ref":"#/components/schemas/promotion_coupon_config"},{"$ref":"#/components/schemas/promotion_cross_sell_config"},{"$ref":"#/components/schemas/promotion_up_sell_config"}]},"formatted":{"type":"object","description":"Present only when you send `formatted=true`.","properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"},"expires":{"type":["string","null"]}}}},"required":["object","url","promotion_id","apply_to_recurring","apply_to_recurring_count"],"example":{"object":"promotion","url":"https://api.comecero.com/api/v1/promotions/0070576784690PtKDqfI","promotion_id":"0070576784690PtKDqfI","name":"Ten percent off","test":true,"account_id":"AB1234","date_created":"2026-11-02T20:13:16Z","date_modified":"2026-11-02T20:13:16Z","type":"coupon","active":true,"apply_to_recurring":false,"apply_to_recurring_count":null,"use_count":4,"expires":"2026-12-31T23:59:59Z","comments":null,"config":{"type":"order","code":"SAVE10","generator_prefix":null,"generator_secret_key":null,"discount_percent":0.1,"discount_amount":null,"product_ids":null,"exclude_product_ids":false,"max_uses_per_customer":1,"max_uses_global":null}}},"promotion_list":{"type":"object","title":"promotion_list","description":"A page of promotions. An offset-based list.","properties":{"total_items":{"type":"integer","description":"The number of items that match, across all pages."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The number of this page."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The items on this page.","items":{"$ref":"#/components/schemas/promotion"}}},"required":["total_items","total_pages","current_page","next_page_url","next_page_offset","previous_page_url","previous_page_offset","current_page_url","data"]},"product_volume_price":{"type":"object","title":"product_volume_price","description":"A quantity tier with its own unit price. A tier applies from `low` up to the next tier's `low` minus one.","properties":{"low":{"type":"integer","minimum":2,"description":"The lowest quantity this tier applies to. Must be 2 or more, and each tier's `low` must be different. Tiers are sorted by `low` when saved."},"high":{"type":["integer","null"],"readOnly":true,"description":"The highest quantity this tier applies to, or null for the last tier. Worked out from the next tier."},"prices":{"type":"array","description":"The unit price in this tier, one per currency. Each price must be greater than 0 and each currency may appear only once.","items":{"$ref":"#/components/schemas/price"}}},"required":["low","prices"],"example":{"low":10,"high":null,"prices":[{"price":39.95,"currency":"USD"}]}},"product_effective_volume_price":{"type":"object","title":"product_effective_volume_price","description":"A quantity tier priced in the currency of the response. The first tier always starts at 1 with the regular price.","properties":{"low":{"type":"integer","description":"The lowest quantity this tier applies to."},"high":{"type":["integer","null"],"description":"The highest quantity this tier applies to, or null for the last tier."},"price":{"type":"number","description":"The unit price in this tier, in `currency`."},"currency":{"type":"string","description":"The currency of `price`, the same as the product's `currency`."},"discount_percent":{"type":"number","description":"The saving against the regular price as a fraction, for example `0.2` for 20%."},"discount_amount":{"type":"number","description":"The saving per unit against the regular price, in `currency`."},"formatted":{"type":"object","description":"Present only when you send `formatted=true`.","properties":{"price":{"type":"string"},"discount_percent":{"type":"string"},"discount_amount":{"type":"string"}}}},"required":["low","high","price","currency","discount_percent","discount_amount"],"example":{"low":1,"high":9,"price":49.95,"currency":"USD","discount_percent":0,"discount_amount":0}},"product_inventory":{"type":["object","null"],"title":"product_inventory","description":"Stock tracking for the product. Null when the product does not track stock.","properties":{"in_stock":{"type":"boolean","description":"True when `quantity` is greater than 0."},"quantity":{"type":"number","description":"The units in stock now. Goes down as orders are placed."},"allow_oversells":{"type":"boolean","description":"When true, shoppers may buy more than `quantity`. When false, a cart that asks for more than is in stock is refused."},"low_quantity_notification":{"type":["number","null"],"description":"The stock level at which the `product.low_inventory` event fires. Not returned to limited tokens."}},"example":{"in_stock":true,"quantity":120,"allow_oversells":false,"low_quantity_notification":10}},"product_bundle_item":{"type":"object","title":"product_bundle_item","description":"One product inside a bundle, and how many of it the bundle holds.","properties":{"product_id":{"type":"string","description":"The product in the bundle. It must exist, be active, not be deleted, not be a bundle itself and not have a subscription plan."},"quantity":{"type":"number","exclusiveMinimum":0,"description":"How many units of the product one bundle holds. Must be greater than 0."}},"required":["product_id","quantity"],"example":{"product_id":"1001.test","quantity":2}},"weight":{"type":"object","title":"weight","description":"The weight of one unit of a product, used to price weight-based shipping.","properties":{"amount":{"type":"number","exclusiveMinimum":0,"description":"The weight amount. Must be greater than 0."},"unit":{"type":"string","enum":["oz","lb","g","kg"],"description":"The unit of `amount`."}},"required":["amount","unit"],"example":{"amount":3,"unit":"lb"}},"file":{"type":"object","title":"file","description":"A file you uploaded to sell as a download, such as an installer. Give it to a product with `file_id`, and each buyer gets a download link to it.","properties":{"object":{"type":"string","enum":["file"],"description":"The object type. Always `file`."},"url":{"type":"string","format":"uri","description":"The URL of this file in the API."},"file_id":{"type":"string","description":"The id of the file."},"date_created":{"type":"string","format":"date-time","description":"When the file was uploaded."},"date_modified":{"type":"string","format":"date-time","description":"When the file was last changed."},"test":{"type":"boolean","description":"True for a test-mode file."},"account_id":{"type":"string","description":"The account the file belongs to."},"name":{"type":"string","description":"Your name for the file. The file name when you gave none."},"description":{"type":["string","null"],"description":"Your notes about the file."},"filename":{"type":"string","description":"The file name customers download, cleaned to letters, numbers, dashes, underscores and periods."},"bytes":{"type":"integer","description":"The size of the file in bytes."},"version":{"type":["string","null"],"description":"A version label, for example `2.1`."},"expires_in_days":{"type":"integer","description":"How many days a new download link to this file works. The default is 7."},"expires_in_clicks":{"type":"integer","description":"How many clicks a new download link to this file allows. The default is 10."},"formatted":{"type":"object","description":"Present only when you send `formatted=true`.","properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"}}}},"required":["object","url","file_id","date_created","date_modified","test","account_id","name","description","filename","bytes","version","expires_in_days","expires_in_clicks"],"example":{"object":"file","url":"https://api.comecero.com/api/v1/files/0095012700001FiQ2xT7Ab","file_id":"0095012700001FiQ2xT7Ab","date_created":"2026-11-01T10:12:40Z","date_modified":"2026-11-01T10:12:40Z","test":true,"account_id":"AB1234","name":"Widget Pro installer","description":null,"filename":"widget-pro-setup.zip","bytes":24518301,"version":"2.1","expires_in_days":7,"expires_in_clicks":10}},"license_service_remote_url_config":{"type":"object","title":"license_service_remote_url_config","description":"Where to get license keys for a `remote_url` service. Comecero sends a license request (with the order and customer) by HTTP POST to `url` and saves the response body as the license.","properties":{"url":{"type":"string","format":"uri","maxLength":256,"description":"Your license server. Must be a public address, not localhost or a private network."},"format":{"type":"string","enum":["json","xml"],"description":"The format of the request body Comecero sends."},"http_authorization_username":{"type":["string","null"],"maxLength":75,"description":"A user name for HTTP basic authentication, if your server needs one."},"http_authorization_password":{"type":["string","null"],"maxLength":75,"description":"The password for HTTP basic authentication. It is returned as you saved it."},"custom_header_name":{"type":["string","null"],"maxLength":75,"description":"The name of an extra header to send with each request."},"custom_header_value":{"type":["string","null"],"maxLength":75,"description":"The value of that header."}},"example":{"url":"https://licenses.example.com/issue","format":"json","http_authorization_username":null,"http_authorization_password":null,"custom_header_name":"X-Shop-Key","custom_header_value":"abc123"}},"license_service_list_config":{"type":"object","title":"license_service_list_config","description":"The stored keys of a `list` service, handed out one at a time.","properties":{"licenses":{"type":"array","description":"The keys to hand out, at most about 256 kB in all. On create at least one is required; on update the list replaces the old one. In a list of services, or when the service is expanded inside another object, only the first 15 keys come back when there are more than 20, followed by a note of how many more there are.","items":{"type":"string"}},"license_count":{"type":"integer","readOnly":true,"description":"The number of keys left in the list."},"per_quantity":{"type":"boolean","description":"When true, a buyer of several units gets one key per unit. When false, one key per order item. The default is false."},"remove_after_use":{"type":"boolean","description":"When true, a key is removed from the list once it is handed out. A new service always starts with true, even when you send false; send false in an update to keep keys in the list."},"notify_at_count":{"type":"integer","minimum":0,"description":"When the keys left fall to this number, the `license_service.low_licenses` event fires. The default is 100."}},"example":{"licenses":["AAAA-BBBB-CCCC-0001","AAAA-BBBB-CCCC-0002"],"license_count":2,"per_quantity":false,"remove_after_use":true,"notify_at_count":100}},"license_service":{"type":"object","title":"license_service","description":"The source of license keys for a product: a list of keys you upload, or your own license server that Comecero calls after each sale.","properties":{"object":{"type":"string","enum":["license_service"],"description":"The object type. Always `license_service`."},"url":{"type":"string","format":"uri","description":"The URL of this license service in the API."},"license_service_id":{"type":"string","description":"The id of the license service."},"date_created":{"type":"string","format":"date-time","description":"When the service was created."},"date_modified":{"type":"string","format":"date-time","description":"When the service was last changed."},"test":{"type":"boolean","description":"True for a test-mode service."},"account_id":{"type":"string","description":"The account the service belongs to."},"name":{"type":"string","maxLength":75,"description":"Your name for the service."},"label":{"type":"string","maxLength":75,"description":"What the key is called when shown to the customer, for example `License Code` or `Registration Code`."},"description":{"type":["string","null"],"maxLength":256,"description":"Your notes about the service."},"instructions":{"type":["string","null"],"maxLength":1024,"description":"How to use the key, shown to the customer with it. Basic HTML is kept; anything else is stripped."},"type":{"type":"string","enum":["remote_url","list"],"description":"Where keys come from: `remote_url` asks your license server, `list` hands out keys you uploaded."},"expand":{"type":["string","null"],"description":"For `remote_url`: the child objects to expand in the order sent to your server, as in the `expand` query parameter. `customer` is always expanded."},"show":{"type":["string","null"],"description":"For `remote_url`: the only order fields to send to your server. Cannot be used with `hide`."},"hide":{"type":["string","null"],"description":"For `remote_url`: order fields to leave out of what is sent to your server. Cannot be used with `show`."},"configuration":{"description":"The settings for the service's `type`.","anyOf":[{"$ref":"#/components/schemas/license_service_remote_url_config"},{"$ref":"#/components/schemas/license_service_list_config"}]},"formatted":{"type":"object","description":"Present only when you send `formatted=true`.","properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"}}}},"required":["object","url","license_service_id","date_created","date_modified","test","account_id","name","label","description","instructions","type","expand","show","hide","configuration"],"example":{"object":"license_service","url":"https://api.comecero.com/api/v1/license_services/0095012789659LsuOeAWLC","license_service_id":"0095012789659LsuOeAWLC","date_created":"2026-11-02T16:26:29Z","date_modified":"2026-11-02T16:45:25Z","test":true,"account_id":"AB1234","name":"Widget Pro keys","label":"License Code","description":null,"instructions":"Open Widget Pro, choose Help, then Enter License, and paste the code.","type":"remote_url","expand":null,"show":null,"hide":null,"configuration":{"url":"https://licenses.example.com/issue","format":"json","http_authorization_username":null,"http_authorization_password":null,"custom_header_name":null,"custom_header_value":null}}},"subscription_plan":{"type":"object","title":"subscription_plan","description":"The billing rules a subscription product follows: how often it bills, any free trial, and how many billings before it stops. A subscription copies these values when it is made, so later changes to a plan only affect new subscriptions.","properties":{"object":{"type":"string","enum":["subscription_plan"],"description":"The object type. Always `subscription_plan`."},"url":{"type":"string","format":"uri","description":"The full URL of this plan."},"subscription_plan_id":{"type":"string","description":"The plan id."},"date_created":{"type":"string","format":"date-time","description":"When the plan was created."},"date_modified":{"type":"string","format":"date-time","description":"When the plan was last changed."},"test":{"type":"boolean","description":"`true` for a test plan, `false` for a live one."},"account_id":{"type":"string","description":"The account the plan belongs to."},"name":{"type":"string","description":"The plan name, for your own reference. Not returned to a limited token."},"description":{"type":["string","null"],"description":"A description, for your own reference. Not returned to a limited token."},"billing_interval":{"type":"integer","description":"How many `billing_interval_unit` make one billing period."},"billing_interval_unit":{"type":"string","enum":["minute","hour","day","month","year"],"description":"The unit of the billing period. `hour` and `minute` are only allowed on test plans, and `minute` only outside production."},"billing_interval_description":{"type":"string","description":"The billing period as text, for example `1 month` or `3 months`."},"end_at_billing_count":{"type":["integer","null"],"description":"The number of billings after which a subscription completes. `null` means it bills until cancelled."},"trial_interval":{"type":["integer","null"],"description":"The trial length in `trial_interval_unit`. `null` when there is no trial."},"trial_interval_unit":{"type":["string","null"],"enum":["minute","hour","day","month","year",null],"description":"The unit of the trial. `null` when there is no trial."},"trial_interval_description":{"type":["string","null"],"description":"The trial length as text, for example `14 days`. `null` when there is no trial."},"deleted":{"type":"boolean","description":"`true` once the plan is deleted. Not returned to a limited token."},"date_deleted":{"type":["string","null"],"format":"date-time","description":"When the plan was deleted. Not returned to a limited token."},"meta":{"description":"Any data you stored on the plan. Not returned to a limited token."},"formatted":{"type":"object","description":"The dates as display text. Only returned with `formatted=true`."}},"required":["object","url","subscription_plan_id","date_created","date_modified","test","account_id","billing_interval","billing_interval_unit","billing_interval_description","end_at_billing_count","trial_interval","trial_interval_unit","trial_interval_description"],"example":{"object":"subscription_plan","url":"https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C","subscription_plan_id":"0093472113202Spzs4AV8C","date_created":"2026-09-18T20:28:33Z","date_modified":"2026-09-18T20:28:33Z","test":true,"account_id":"AB1234","name":"Monthly, 14-day trial","description":null,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","end_at_billing_count":null,"trial_interval":14,"trial_interval_unit":"day","trial_interval_description":"14 days","deleted":false,"date_deleted":null,"meta":null}},"product_subscription_terms":{"type":"object","title":"subscription_terms","description":"What a subscription for this product would cost and when it would bill, if a customer bought one unit now. Worked out from the product's prices and its subscription plan. Nothing is created.","properties":{"object":{"type":"string","enum":["subscription_terms"],"description":"The object type. Always `subscription_terms`."},"price":{"type":"number","description":"The price of each billing, in `currency`, before any discount."},"quantity":{"type":"number","description":"The quantity the terms are for. Always 1 here."},"currency":{"type":"string","description":"The currency of the amounts."},"discount":{"type":"number","description":"The discount on each discounted billing, in `currency`."},"discount_price":{"type":["number","null"],"description":"The price after `discount`, or null when there is no discount."},"discount_apply_count":{"type":["integer","null"],"description":"How many billings get the discount, or null for every billing."},"discount_applied_count":{"type":"integer","description":"How many discounted billings have run. Always 0 here."},"tax_inclusve":{"type":"boolean","description":"Whether the price includes tax. Always false here. The field name is spelled this way in the API."},"billing_interval":{"type":"integer","description":"The number of `billing_interval_unit` between billings."},"billing_interval_unit":{"type":"string","enum":["minute","hour","day","month","year"],"description":"The unit of `billing_interval`. Minute and hour are for test plans only."},"billing_interval_description":{"type":"string","description":"The billing interval as text, for example `month` or `3 months`."},"trial_interval":{"type":["integer","null"],"description":"The length of the free trial, or null when there is none."},"trial_interval_unit":{"type":["string","null"],"description":"The unit of `trial_interval`."},"trial_interval_description":{"type":["string","null"],"description":"The trial length as text, or null when there is no trial."},"date_trial_start":{"type":["string","null"],"format":"date-time","description":"When the trial would start (now), or null when there is no trial."},"date_trial_end":{"type":["string","null"],"format":"date-time","description":"When the trial would end, or null when there is no trial."},"end_at_billing_count":{"type":["integer","null"],"description":"The number of billings after which the subscription ends, or null to renew until cancelled."},"date_billing_start":{"type":"string","format":"date-time","description":"When the first paid billing would happen."},"subscription_id":{"type":["string","null"],"description":"Always null here, because no subscription exists yet."},"description":{"type":"string","description":"The terms as one sentence for the shopper, in their language."},"price_per_day":{"type":"number","description":"The price spread over one day, for display."},"price_per_month":{"type":"number","description":"The price spread over one month, for display."},"price_per_year":{"type":"number","description":"The price spread over one year, for display."},"formatted":{"type":"object","description":"Present only when you send `formatted=true`. The amounts and dates as display text.","additionalProperties":{"type":["string","null"]}}},"example":{"object":"subscription_terms","price":9.95,"quantity":1,"currency":"USD","discount":0,"discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"tax_inclusve":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"month","trial_interval":14,"trial_interval_unit":"day","trial_interval_description":"14 days","date_trial_start":"2026-11-07T15:00:00Z","date_trial_end":"2026-11-21T15:00:00Z","end_at_billing_count":null,"date_billing_start":"2026-11-21T15:00:00Z","subscription_id":null,"description":"Widget Pro is a subscription that renews every month with a payment of $9.95.","price_per_day":0.33,"price_per_month":9.95,"price_per_year":119.4}},"image":{"type":"object","title":"image","description":"An image you uploaded, such as a product picture. Comecero stores the original and four resized copies on its CDN.","properties":{"object":{"type":"string","enum":["image"],"description":"The object type. Always `image`."},"url":{"type":"string","format":"uri","description":"The URL of this image in the API."},"image_id":{"type":"string","description":"The id of the image."},"date_created":{"type":"string","format":"date-time","description":"When the image was uploaded."},"date_modified":{"type":"string","format":"date-time","description":"When the image was last changed."},"test":{"type":"boolean","description":"True for a test-mode image."},"account_id":{"type":"string","description":"The account the image belongs to."},"link":{"type":"string","format":"uri","description":"The CDN link to the image as uploaded."},"link_small":{"type":"string","format":"uri","description":"The CDN link to the small copy."},"link_medium":{"type":"string","format":"uri","description":"The CDN link to the medium copy."},"link_large":{"type":"string","format":"uri","description":"The CDN link to the large copy."},"link_square":{"type":"string","format":"uri","description":"The CDN link to a square copy, for thumbnails."},"filename":{"type":"string","description":"The file name, cleaned of characters that are not safe in a URL."},"formatted":{"type":"object","description":"Present only when you send `formatted=true`.","properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"}}}},"required":["object","url","image_id","date_created","date_modified","test","account_id","link","link_small","link_medium","link_large","link_square","filename"],"example":{"object":"image","url":"https://api.comecero.com/api/v1/images/0099844605810ImLAMbo73","image_id":"0099844605810ImLAMbo73","date_created":"2026-11-02T14:36:45Z","date_modified":"2026-11-02T14:36:45Z","test":true,"account_id":"AB1234","link":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/widget.png","link_small":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sm_widget.png","link_medium":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/md_widget.png","link_large":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/lg_widget.png","link_square":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sq_widget.png","filename":"widget.png"}},"product":{"type":"object","title":"product","description":"Something you sell: a physical item, a digital download, a service or a bundle of other products. A product with a subscription plan starts a subscription every time it is bought. Limited tokens see only active, visible products and do not get the fields marked as not returned to them.","properties":{"object":{"type":"string","enum":["product"],"description":"The object type. Always `product`."},"url":{"type":"string","format":"uri","description":"The URL of this product in the API."},"product_id":{"type":"string","description":"The id of the product. Always lower case. Test products end in `.test`."},"date_created":{"type":"string","format":"date-time","description":"When the product was created."},"date_modified":{"type":"string","format":"date-time","description":"When the product was last changed."},"test":{"type":"boolean","description":"True for a test-mode product."},"account_id":{"type":"string","description":"The account the product belongs to."},"name":{"type":"string","description":"The name of the product. When the shopper's language has a translation, the translated name is returned."},"price":{"type":"number","description":"The unit price in `currency`. The currency comes from the `cart_id`, `invoice_id` or `currency` you send, or from the shopper's country or IP address, or else the account's default payment currency. When the product has no price in that currency, it is converted at the current exchange rate."},"currency":{"type":"string","description":"The currency of `price`, `compare_at_price` and `effective_volume_prices`."},"compare_at_price":{"type":["number","null"],"description":"A higher \"was\" price to show next to `price`, in `currency`, or null when the product has none."},"type":{"type":"string","enum":["physical","digital","service","bundle"],"description":"The kind of product. It decides how tax is worked out and what the shopper must give at checkout (a shipping address for physical goods, an email address for digital ones)."},"description":{"type":["string","null"],"description":"A description of the product, translated when a translation exists."},"headline":{"type":["string","null"],"description":"A short line about the product, translated when a translation exists."},"tax_code":{"type":["string","null"],"description":"The tax code that decides how the product is taxed, or null for the default."},"prices":{"type":"array","description":"The prices you set, one per currency. A price set here is always used for that currency. Other currencies are converted at the current exchange rate.","items":{"$ref":"#/components/schemas/price"}},"compare_at_prices":{"type":"array","description":"The \"was\" prices you set, one per currency. Not returned to limited tokens.","items":{"$ref":"#/components/schemas/price"}},"volume_prices":{"type":"array","description":"The quantity tiers you set, with their prices in each currency.","items":{"$ref":"#/components/schemas/product_volume_price"}},"effective_volume_prices":{"type":"array","description":"The quantity tiers priced in `currency`, starting from a tier of 1 at the regular price. Empty when the product has no tiers.","items":{"$ref":"#/components/schemas/product_effective_volume_price"}},"inventory":{"$ref":"#/components/schemas/product_inventory"},"bundle_items":{"type":"array","description":"For a bundle, the products it holds. Empty for other types.","items":{"$ref":"#/components/schemas/product_bundle_item"}},"weight":{"description":"The weight of one unit, or null. Not returned to limited tokens.","anyOf":[{"$ref":"#/components/schemas/weight"},{"type":"null"}]},"active":{"type":"boolean","description":"True when the product is for sale. Inactive products cannot be added to a cart and are not shown to shoppers. Not returned to limited tokens."},"deleted":{"type":"boolean","description":"True when the product was deleted. Not returned to limited tokens."},"hidden":{"type":"boolean","description":"True when the product is left out of the product list for shoppers. A shopper can still read it and buy it by its id. Not returned to limited tokens."},"date_deleted":{"type":["string","null"],"format":"date-time","description":"When the product was deleted, or null. Not returned to limited tokens."},"file":{"description":"The file a buyer may download, as a link, or the full object when you send `expand=file`. Null when the product has none. Left out for tokens that may not read files, such as limited tokens.","anyOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/file"},{"type":"null"}]},"has_file":{"type":"boolean","description":"True when the product has a file. Returned to every token."},"license_service":{"description":"The license service that issues license keys for this product, as a link, or the full object when you send `expand=license_service`. Null when the product has none. Left out for tokens that may not read license services, such as limited tokens.","anyOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/license_service"},{"type":"null"}]},"has_license_service":{"type":"boolean","description":"True when the product has a license service. Returned to every token."},"subscription_plan":{"description":"The subscription plan, as a link, or the full object when you send `expand=subscription_plan`. Null when the product is not a subscription.","anyOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/subscription_plan"},{"type":"null"}]},"subscription_terms":{"description":"For a subscription product, a link to its subscription terms, or the terms when you send `expand=subscription_terms`. Null for other products.","anyOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/product_subscription_terms"},{"type":"null"}]},"images":{"type":"array","description":"The product's images, in the order you gave their ids.","items":{"$ref":"#/components/schemas/image"}},"video_url":{"type":["string","null"],"format":"uri","description":"A link to a video about the product."},"related_products":{"description":"A link to the related products, or the list when you send `expand=related_products` on a single product. Inactive and deleted products are left out.","anyOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/product_list"}]},"subscription_change_products":{"description":"A link to the products a subscriber may switch to on the same plan, or the list when you send `expand=subscription_change_products` on a single product.","anyOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/product_list"}]},"subscription_term_change_products":{"description":"A link to the products a subscriber may switch to on a different plan, or the list when you send `expand=subscription_term_change_products` on a single product.","anyOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/product_list"}]},"meta":{"description":"Your own data for the product, a string or an object, up to 2048 characters.","type":["object","string","null"]},"translations":{"type":["object","null"],"description":"The product's text in other languages, keyed by language code such as `de` or `ja-JP`. Not returned to limited tokens. The translation that matches the shopper's language (from `user_locale` or the `Accept-Language` header) replaces `name`, `headline` and `description`.","additionalProperties":{"$ref":"#/components/schemas/product_translation"}},"formatted":{"type":"object","description":"Present only when you send `formatted=true`.","properties":{"price":{"type":"string"},"compare_at_price":{"type":["string","null"]},"date_created":{"type":"string"},"date_modified":{"type":"string"},"date_deleted":{"type":["string","null"]}}}},"required":["object","url","product_id","date_created","date_modified","test","account_id","name","price","currency","compare_at_price","type","description","headline","tax_code","prices","volume_prices","effective_volume_prices","inventory","bundle_items","has_file","has_license_service","subscription_terms","images","video_url","related_products","subscription_change_products","subscription_term_change_products","meta"],"example":{"object":"product","url":"https://api.comecero.com/api/v1/products/widget.test","product_id":"widget.test","date_created":"2026-11-02T14:36:52Z","date_modified":"2026-11-02T14:36:52Z","test":true,"account_id":"AB1234","name":"Widget","price":49.95,"currency":"USD","compare_at_price":59.95,"type":"physical","description":"A simple widget for everyday use.","headline":"The widget you will use every day","tax_code":null,"prices":[{"price":49.95,"currency":"USD"},{"price":45.95,"currency":"EUR"}],"compare_at_prices":[{"price":59.95,"currency":"USD"}],"volume_prices":[{"low":10,"high":null,"prices":[{"price":39.95,"currency":"USD"}]}],"effective_volume_prices":[{"low":1,"high":9,"price":49.95,"currency":"USD","discount_percent":0,"discount_amount":0},{"low":10,"high":null,"price":39.95,"currency":"USD","discount_percent":0.2,"discount_amount":10}],"inventory":{"in_stock":true,"quantity":120,"allow_oversells":false,"low_quantity_notification":10},"bundle_items":[],"weight":{"amount":3,"unit":"lb"},"active":true,"deleted":false,"hidden":false,"date_deleted":null,"file":null,"has_file":false,"license_service":null,"has_license_service":false,"subscription_plan":null,"subscription_terms":null,"images":[{"object":"image","url":"https://api.comecero.com/api/v1/images/0099844605810ImLAMbo73","image_id":"0099844605810ImLAMbo73","date_created":"2026-11-02T14:36:45Z","date_modified":"2026-11-02T14:36:45Z","test":true,"account_id":"AB1234","link":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/widget.png","link_small":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sm_widget.png","link_medium":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/md_widget.png","link_large":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/lg_widget.png","link_square":"https://cdn.comecero.net/AB1234/0099844605810ImLAMbo73/sq_widget.png","filename":"widget.png"}],"video_url":null,"related_products":"https://api.comecero.com/api/v1/products/widget.test/related_products","subscription_change_products":"https://api.comecero.com/api/v1/products/widget.test/subscription_change_products","subscription_term_change_products":"https://api.comecero.com/api/v1/products/widget.test/subscription_term_change_products","meta":null,"translations":{"de":{"name":"Widget","headline":"Das Widget fur jeden Tag","description":"Ein einfaches Widget fur jeden Tag."}}}},"product_list":{"type":"object","title":"product_list","description":"A page of products. An offset-based list.","properties":{"total_items":{"type":"integer","description":"The number of items that match, across all pages."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The number of this page."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The items on this page.","items":{"$ref":"#/components/schemas/product"}}},"required":["total_items","total_pages","current_page","next_page_url","next_page_offset","previous_page_url","previous_page_offset","current_page_url","data"]},"product_translation":{"type":"object","title":"product_translation","description":"The product's text in one language. Empty fields fall back to the base text.","properties":{"name":{"type":["string","null"],"maxLength":75},"headline":{"type":["string","null"],"maxLength":100},"description":{"type":["string","null"],"maxLength":2048}},"example":{"name":"Widget","headline":"Das praktische Widget","description":"Ein einfaches Widget fur jeden Tag."}},"cart_product_list":{"type":"object","title":"cart_product_list","description":"An offset-based list of products related to the items in a cart. Up to 3 products on one page.","x-response":true,"properties":{"total_items":{"type":"integer","description":"The number of items in the whole list."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The page number of this page, starting at 1."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The products on this page.","items":{"$ref":"#/components/schemas/product"}}},"required":["total_items","total_pages","current_page","next_page_url","next_page_offset","previous_page_url","previous_page_offset","current_page_url","data"]},"cart_up_sell":{"type":"object","title":"cart_up_sell","description":"An up-sell offer for a cart: a better product in place of one already in the cart. To take it, add the product with this `up_sell_id`; the item it replaces is removed.","x-limited":true,"x-response":true,"properties":{"up_sell_id":{"type":"string","description":"The id to send as `up_sell_id` when you add the item. It only works for this cart."},"product_id":{"type":"string","description":"The product offered."},"name":{"type":"string","description":"The product name."},"price":{"type":"number","description":"The offer price of one unit, in `currency`."},"price_original":{"type":"number","description":"The price before the offer discount, in `currency`."},"discount":{"type":"number","description":"The offer discount on one unit, in `currency`."},"discount_percent":{"type":"number","description":"The discount as a fraction, rounded to a whole percent."},"currency":{"type":"string","description":"The cart currency."},"up_sell_from_product":{"type":["string","object"],"description":"The URL of the product in the cart that this offer replaces, or that product with `expand=up_sell_from_product`.","x-expandable-url":true},"additional_amount":{"type":"number","description":"How much more the shopper pays for the swap, at the quantity of the item in the cart, without tax, in `currency`."},"product":{"type":["string","object"],"description":"The URL of the product offered, or the product with `expand=product`.","x-expandable-url":true},"formatted":{"type":"object","description":"Amounts as display strings. Only present with `formatted=true`.","additionalProperties":{"type":"string"}}},"required":["up_sell_id","product_id","name","price","price_original","discount","discount_percent","currency","additional_amount","product"],"example":{"up_sell_id":"0091307952511PtR8sQm-c3d4","product_id":"pdf-pro-plus.test","name":"PDF Viewer Pro Plus","price":119.95,"price_original":129.95,"discount":10,"discount_percent":0.08,"currency":"USD","up_sell_from_product":"https://api.comecero.com/api/v1/products/pdf-pro.test","additional_amount":40,"product":"https://api.comecero.com/api/v1/products/pdf-pro-plus.test"}},"cart_up_sell_list":{"type":"object","title":"cart_up_sell_list","description":"An offset-based list of up-sell offers for a cart. It is one page.","x-response":true,"properties":{"total_items":{"type":"integer","description":"The number of items in the whole list."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The page number of this page, starting at 1."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The offers on this page.","items":{"$ref":"#/components/schemas/cart_up_sell"}}},"required":["total_items","total_pages","current_page","next_page_url","next_page_offset","previous_page_url","previous_page_offset","current_page_url","data"]},"cart_user_agent_payment_amount":{"type":"object","properties":{"currency":{"type":"string"},"value":{"type":"string","description":"The amount as a decimal string."}}},"cart_user_agent_payment_item":{"type":"object","properties":{"label":{"type":"string"},"amount":{"$ref":"#/components/schemas/cart_user_agent_payment_amount"},"pending":{"type":"boolean"}}},"cart_user_agent_payment_request":{"type":"object","title":"cart_user_agent_payment_request","description":"The arguments for the browser's Payment Request API (`new PaymentRequest(methodData, details, paymentOptions)`) for this cart, built from its items, tax, shipping quotes and required customer fields. Only Apple Pay (`apple_pay`) is built this way. The field names inside follow the W3C Payment Request API, so they are camel case.","x-limited":true,"x-response":true,"properties":{"url":{"type":"string","format":"uri","description":"The URL of this payment request."},"payment_url":{"type":"string","format":"uri","description":"Where to send the payment when the shopper approves, `POST /carts/{cart_id}/payments`."},"methodData":{"type":"array","description":"The payment methods the browser may offer.","items":{"type":"object","properties":{"supportedMethods":{"type":"string","description":"For Apple Pay, `https://apple.com/apple-pay`."},"data":{"type":"object","description":"The method's own settings. For Apple Pay: `version`, `merchantIdentifier`, `merchantCapabilities`, `supportedNetworks` (from the gateway's card types), `countryCode` and `requiredBillingContactFields`.","additionalProperties":true}}}},"details":{"type":"object","description":"What the payment sheet shows.","properties":{"displayItems":{"type":"array","description":"One line per item, then shipping and tax when there are any.","items":{"$ref":"#/components/schemas/cart_user_agent_payment_item"}},"shippingOptions":{"type":"array","description":"One option per shipping quote, `selected` on the current one. With no quotes, one `digital` option, or a `placeholder` option when the cart has physical items.","items":{"type":"object","properties":{"id":{"type":"string","description":"The shipping_method_id."},"label":{"type":"string"},"amount":{"$ref":"#/components/schemas/cart_user_agent_payment_amount"},"selected":{"type":"boolean"}}}},"modifiers":{"type":"array","description":"Always empty.","items":{"type":"object"}},"total":{"$ref":"#/components/schemas/cart_user_agent_payment_item"}}},"paymentOptions":{"type":"object","description":"Which shopper details the sheet asks for, from the cart's required customer fields.","properties":{"requestPayerName":{"type":"boolean"},"requestPayerEmail":{"type":"boolean"},"requestPayerPhone":{"type":"boolean"},"requestShipping":{"type":"boolean","description":"True when a postal code, a country or a full address is required."}}},"merchant_validation_url":{"type":"string","format":"uri","description":"Present for Apple Pay. Send the browser's validation URL here from the `onmerchantvalidation` handler."}},"required":["url","payment_url","methodData","details","paymentOptions"],"$defs":{"cart_user_agent_payment_amount":{"type":"object","properties":{"currency":{"type":"string"},"value":{"type":"string","description":"The amount as a decimal string."}}},"cart_user_agent_payment_item":{"type":"object","properties":{"label":{"type":"string"},"amount":{"$ref":"#/components/schemas/cart_user_agent_payment_amount"},"pending":{"type":"boolean"}}}},"example":{"url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/user_agent_payment_request/apple_pay","payment_url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/payments","methodData":[{"supportedMethods":"https://apple.com/apple-pay","data":{"version":1,"merchantIdentifier":"merchant.com.example.shop","merchantCapabilities":["supports3DS","supportsCredit","supportsDebit"],"supportedNetworks":["visa","masterCard","amex"],"countryCode":"US","requiredBillingContactFields":["postalAddress"]}}],"details":{"displayItems":[{"label":"PDF Viewer Pro","amount":{"currency":"USD","value":"199.90"},"pending":false},{"label":"Tax","amount":{"currency":"USD","value":"14.99"},"pending":false}],"shippingOptions":[{"id":"digital","label":"Digital","amount":{"currency":"USD","value":"0.00"},"selected":false}],"modifiers":[],"total":{"label":"Total","amount":{"currency":"USD","value":"214.89"},"pending":false}},"paymentOptions":{"requestPayerName":true,"requestPayerEmail":true,"requestPayerPhone":false,"requestShipping":true},"merchant_validation_url":"https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1/user_agent_payment_request/apple_pay/merchant_validate"}},"cart_user_agent_payment_request_update":{"type":"object","title":"cart_user_agent_payment_request_update","description":"What changed on the browser's payment sheet. Send it from the `shippingaddresschange` and `shippingoptionchange` handlers. The field names follow the W3C Payment Request API.","x-limited":true,"x-request":true,"properties":{"shippingAddress":{"type":"object","description":"The address the shopper picked. It becomes the customer's shipping address, so tax and shipping are worked out again.","properties":{"recipient":{"type":"string"},"addressLine":{"type":"array","items":{"type":"string"}},"city":{"type":"string"},"region":{"type":"string","description":"The state or province."},"postalCode":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2."},"organization":{"type":"string"},"phone":{"type":"string"},"dependentLocality":{"type":"string"},"sortingCode":{"type":"string"}}},"shippingOption":{"type":"string","description":"The `id` of the shipping option the shopper picked. It becomes the cart's shipping_method_id."},"details":{"type":"object","description":"Read but not used."}},"example":{"shippingAddress":{"recipient":"John Smith","addressLine":["1 Main St"],"city":"High Point","region":"NC","postalCode":"27265","country":"US"},"shippingOption":"standard-us"}},"cart_merchant_validate_request":{"type":"object","title":"cart_merchant_validate_request","description":"The validation URL Apple Pay gave the browser.","x-limited":true,"x-request":true,"properties":{"validation_url":{"type":"string","format":"uri","description":"`event.validationURL` from the `onmerchantvalidation` handler. It must be an Apple host."}},"required":["validation_url"],"example":{"validation_url":"https://apple-pay-gateway.apple.com/paymentservices/startSession"}},"cart_merchant_validation":{"type":"object","title":"cart_merchant_validation","description":"Apple Pay's merchant session for this checkout.","x-limited":true,"x-response":true,"properties":{"data":{"type":["object","null"],"description":"The merchant session object from Apple, as Apple returned it. Pass it to `event.complete()` in the `onmerchantvalidation` handler.","additionalProperties":true}},"required":["data"],"example":{"data":{"epochTimestamp":1793990400000,"expiresAt":1793994000000,"merchantSessionIdentifier":"SSH0000000000000000000000000000000000000000","nonce":"0a1b2c3d","merchantIdentifier":0,"domainName":"shop.example.com","displayName":"Example Shop","signature":"308006092a864886f70d0107"}}},"gateway":{"type":"object","title":"gateway","description":"A payment provider connection that takes payments for your account. Gateways are kept per mode: test gateways only take test payments. When a payment ran through a gateway Comecero owns (on accounts where Comecero is the seller), a gateway in that payment shows only `object`, `url`, `gateway_id`, `test`, `name` (`Comecero`) and `provider_id` (`comecero`).","properties":{"object":{"type":"string","enum":["gateway"],"description":"The object type. Always `gateway`.","readOnly":true},"url":{"type":"string","format":"uri","description":"The URL of this gateway.","readOnly":true},"gateway_id":{"type":"string","description":"The gateway's ID.","readOnly":true},"test":{"type":"boolean","description":"True for a test gateway.","readOnly":true},"name":{"type":"string","description":"The provider's name, set from the provider.","readOnly":true},"provider_id":{"type":"string","description":"The payment provider. `GET /gateways/options` lists the providers you can add.","readOnly":true},"date_created":{"type":"string","format":"date-time","description":"When the gateway was added.","readOnly":true},"date_modified":{"type":"string","format":"date-time","description":"When the gateway was last changed.","readOnly":true},"account_id":{"type":"string","description":"The account the gateway belongs to.","readOnly":true},"payment_method_types":{"type":"array","description":"The kinds of payment this gateway takes, such as `credit_card`, `paypal`, `amazon_pay`, `apple_pay`, `wallet` or `ach`. Set when the gateway is added. Gateways that Comecero sets up for you may show other values.","readOnly":true,"items":{"type":"string"}},"currencies":{"type":"array","description":"The ISO 4217 currency codes the gateway takes payments in.","items":{"type":"string"}},"card_types":{"type":["array","null"],"description":"The card brands the gateway takes, such as `visa` or `mastercard`. Set on gateways that take cards. `GET /gateways/options` lists the values.","items":{"type":"string"}},"supports_void":{"type":"boolean","description":"True when a payment on this gateway can be voided before it settles.","readOnly":true},"supports_general_credit":{"type":"boolean","description":"True when the gateway can refund more than the payment, or with no payment.","readOnly":true},"active":{"type":"boolean","description":"True when the gateway takes new payments."},"weight":{"type":"integer","description":"How often this gateway is picked, compared to the other active gateways that take the same payment. The default is 1. Use 0 to pick it only when no other gateway can take the payment.","minimum":0},"comments":{"type":["string","null"],"description":"Your own notes about the gateway.","maxLength":1024},"fields":{"type":"object","description":"The provider settings you saved, such as API keys. Only present when you send `show_sensitive=true`. Treat them as secrets.","additionalProperties":true},"formatted":{"type":"object","description":"Display text for the dates. Only present when you send `formatted=true`.","readOnly":true,"properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"}}}},"example":{"object":"gateway","url":"https://api.comecero.com/api/v1/gateways/0070576784690GtKDqfI7c","gateway_id":"0070576784690GtKDqfI7c","test":true,"name":"Test Gateway","provider_id":"test","date_created":"2026-10-01T14:36:52Z","date_modified":"2026-10-01T14:36:52Z","account_id":"AB1234","payment_method_types":["credit_card"],"currencies":["USD","EUR"],"card_types":["visa","mastercard","american_express"],"supports_void":true,"supports_general_credit":false,"active":true,"weight":1,"comments":null}},"subscription_item_change":{"type":"object","title":"subscription_item_change","description":"An item as it will be after a change scheduled for the end of the current billing period. Used in `change_at_current_period_end` on an item and in `add_at_current_period_end` on a subscription. It has no `url` and no cancellation fields because it does not exist as an item yet.","properties":{"object":{"type":"string","enum":["subscription_item"],"description":"The object type. Always `subscription_item`."},"item_id":{"type":"string","description":"The id the item will have."},"date_created":{"type":"string","format":"date-time","description":"When the change was scheduled."},"date_modified":{"type":"string","format":"date-time","description":"When the scheduled change was last changed."},"product_id":{"type":["string","null"],"description":"The product the item will bill for. `null` for a custom item."},"name":{"type":"string","description":"The item name."},"quantity":{"type":"number","description":"How many units will be billed."},"reference_price":{"type":"number","description":"The unit price for each billing period, in `reference_currency`."},"reference_currency":{"type":"string","description":"The three-letter ISO 4217 currency of `reference_price`."},"reference_discount":{"type":"number","description":"The discount taken off each unit, in `reference_currency`."},"reference_discount_price":{"type":["number","null"],"description":"The unit price after the discount. `null` when there is no discount."},"discount_apply_count":{"type":["integer","null"],"description":"How many billings the discount applies to. `null` means every billing."},"tax_code":{"type":["string","null"],"description":"The tax code. Not returned to a limited token."},"type":{"type":"string","enum":["digital","physical","service","bundle"],"description":"The kind of item."},"meta":{"description":"Any data stored on the item."},"formatted":{"type":"object","description":"Display text for the prices. Only returned with `formatted=true`."}},"required":["object","item_id","date_created","date_modified","product_id","name","quantity","reference_price","reference_currency","reference_discount","reference_discount_price","discount_apply_count","type","meta"],"example":{"object":"subscription_item","item_id":"acme-pro.test","date_created":"2026-11-07T10:00:00Z","date_modified":"2026-11-07T10:00:00Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":3,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"tax_code":null,"type":"digital","meta":null}},"subscription_item":{"type":"object","title":"subscription_item","description":"One item a subscription bills for. An item is either a product from your catalog or a custom item with its own name, type and price.","properties":{"object":{"type":"string","enum":["subscription_item"],"description":"The object type. Always `subscription_item`."},"url":{"type":"string","format":"uri","description":"The full URL of this item."},"item_id":{"type":"string","description":"The item id, unique within the subscription. For a product item it is the `product_id`. For a custom item it is the id you sent, or a number core assigns (`1`, `2` and so on)."},"date_created":{"type":"string","format":"date-time","description":"When the item was added to the subscription."},"date_modified":{"type":"string","format":"date-time","description":"When the item was last changed."},"product_id":{"type":["string","null"],"description":"The product this item bills for. `null` for a custom item."},"name":{"type":"string","description":"The item name. For a product item it is copied from the product."},"quantity":{"type":"number","description":"How many units the subscription bills for."},"reference_price":{"type":"number","description":"The price of one unit for each billing period, in `reference_currency`. If `reference_currency` is not the subscription `currency`, the amount billed is converted at each renewal, so it can change with exchange rates."},"reference_currency":{"type":"string","description":"The three-letter ISO 4217 currency of `reference_price`."},"reference_discount":{"type":"number","description":"The discount taken off each unit, in `reference_currency`. `0` when there is no discount."},"reference_discount_price":{"type":["number","null"],"description":"The unit price after the discount (`reference_price` minus `reference_discount`), in `reference_currency`. `null` when there is no discount."},"discount_apply_count":{"type":["integer","null"],"description":"How many billings the discount applies to. `null` means every billing, for as long as the subscription runs."},"discount_applied_count":{"type":"integer","description":"How many billings the discount has been applied to so far."},"cancelled":{"type":"boolean","description":"`true` once the item is cancelled. A cancelled item is no longer billed and cannot be uncancelled."},"cancel_at_current_period_end":{"type":"boolean","description":"`true` when the item is set to be cancelled at the end of the current billing period. It is still billed until then."},"date_cancelled":{"type":["string","null"],"format":"date-time","description":"When the cancellation was asked for. Set as soon as a cancellation at the period end is scheduled, so it can be before `date_ended`."},"date_ended":{"type":["string","null"],"format":"date-time","description":"When the item stopped being billed. `null` while it is active."},"cancellation_reason":{"type":["string","null"],"description":"Why the item was cancelled. Not returned to a limited token."},"tax_code":{"type":["string","null"],"description":"The tax code used for this item. For a product item it is copied from the product. Not returned to a limited token."},"type":{"type":"string","enum":["digital","physical","service","bundle"],"description":"The kind of item. For a product item it is copied from the product, so it can be `bundle`."},"change_at_current_period_end":{"oneOf":[{"$ref":"#/components/schemas/subscription_item_change"},{"type":"null"}],"description":"A change to this item that is scheduled for the end of the current billing period (a new quantity, price, or a replacement product). `null` when no change is scheduled. Remove it with `DELETE /subscriptions/{subscription_id}/items/{item_id}/change_at_current_period_end`."},"product":{"oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/product"},{"type":"null"}],"description":"The product, as a URL, or the full object with `expand=items.product`. `null` for a custom item. Left out when the token may not read products."},"subscription":{"oneOf":[{"type":"string","format":"uri"},{"type":"object"}],"description":"The subscription this item belongs to, as a URL, or the full subscription object with `expand=subscription`."},"subscription_terms":{"oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/subscription_terms"}],"description":"The billing terms of this item, as a URL, or the full object with `expand=subscription_terms`."},"meta":{"description":"Any data you stored on the item."},"formatted":{"type":"object","description":"Display text for `reference_price`, `reference_discount` and `reference_discount_price`. Only returned with `formatted=true`.","properties":{"reference_price":{"type":"string"},"reference_discount":{"type":"string"},"reference_discount_price":{"type":"string"}}}},"required":["object","item_id","date_created","date_modified","product_id","name","quantity","reference_price","reference_currency","reference_discount","reference_discount_price","discount_apply_count","type","meta"],"example":{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}},"subscription_history":{"type":"object","title":"subscription_history","description":"The change log of a subscription: cancellations, scheduled changes, payments for changes, extensions and so on. Core keeps the last 100 entries.","properties":{"object":{"type":"string","enum":["subscription_history"],"description":"The object type. Always `subscription_history`."},"subscription_id":{"type":["string","null"],"description":"The subscription id. `null` when nothing has been logged yet."},"test":{"type":"boolean","description":"`true` for a test subscription."},"entries":{"type":"array","description":"The log entries, oldest first.","items":{"type":"object","properties":{"date_created":{"type":"string","format":"date-time","description":"When the entry was logged."},"initiated_by":{"type":"string","description":"Who made the change: `system` (automatic changes, and tokens not tied to a user), `customer` (a limited token), or `Administrator` (a dashboard user). Comecero staff tokens see the user id instead of `Administrator`."},"description":{"type":"string","description":"What happened, as a sentence."},"formatted":{"type":"object","description":"`date_created` as display text. Only with `formatted=true`.","properties":{"date_created":{"type":"string"}}}},"required":["date_created","initiated_by","description"]}}},"required":["object","subscription_id","test","entries"],"example":{"object":"subscription_history","subscription_id":"0093799318129SuLByRPW8","test":true,"entries":[{"date_created":"2026-11-02T15:21:31Z","initiated_by":"Administrator","description":"The current billing period has been extended by 7 days"},{"date_created":"2026-11-05T09:12:44Z","initiated_by":"customer","description":"The subscription has been scheduled to be cancelled at the end of the current billing period"}]}},"subscription":{"type":"object","title":"subscription","description":"A customer's recurring billing for one or more items. Most subscriptions are made when a cart or invoice with a subscription product is paid. Each billing period an invoice is made and paid from the customer's saved payment method.","properties":{"object":{"type":"string","enum":["subscription"],"description":"The object type. Always `subscription`."},"url":{"type":"string","format":"uri","description":"The full URL of this subscription."},"subscription_id":{"type":"string","description":"The subscription id."},"date_created":{"type":"string","format":"date-time","description":"When the subscription was created."},"date_modified":{"type":"string","format":"date-time","description":"When the subscription was last changed."},"test":{"type":"boolean","description":"`true` for a test subscription, `false` for a live one."},"account_id":{"type":"string","description":"The account the subscription belongs to."},"status":{"type":"string","enum":["trial","active","cancelled","completed"],"description":"`trial` while in a free trial, `active` while billing, `cancelled` once cancelled, and `completed` once the last billing set by `end_at_billing_count` is done."},"in_grace_period":{"type":"boolean","description":"`true` when a renewal payment failed and is being retried. The subscription stays active during the grace period. If no retry succeeds before the grace period in your subscription settings ends, the subscription is cancelled."},"billing_interval":{"type":"integer","description":"How many `billing_interval_unit` make one billing period. Copied from the subscription plan when the subscription was made."},"billing_interval_unit":{"type":"string","enum":["minute","hour","day","month","year"],"description":"The unit of the billing period. `minute` and `hour` are only allowed on test plans."},"billing_interval_description":{"type":"string","description":"The billing period as text, for example `1 month` or `3 months`."},"trial_interval":{"type":["integer","null"],"description":"The trial length in `trial_interval_unit`. `null` when there is no trial."},"trial_interval_unit":{"type":["string","null"],"enum":["minute","hour","day","month","year",null],"description":"The unit of the trial. `null` when there is no trial."},"trial_interval_description":{"type":["string","null"],"description":"The trial length as text, for example `14 days`. `null` when there is no trial."},"billing_count":{"type":"integer","description":"How many times the subscription has been billed (one invoice per billing period). This is not the number of successful payments: a failed renewal still counts. `0` during a trial."},"end_at_billing_count":{"type":["integer","null"],"description":"The number of billings after which the subscription completes. `null` means it bills until cancelled."},"currency":{"type":"string","description":"The three-letter ISO 4217 currency the customer pays in. Item prices in another currency are converted at each renewal."},"items":{"type":"array","description":"The items the subscription bills for, including cancelled ones.","items":{"$ref":"#/components/schemas/subscription_item"}},"shipping_method_id":{"type":["string","null"],"description":"The shipping method used for physical items on each renewal. `null` when nothing is shipped."},"date_trial_start":{"type":["string","null"],"format":"date-time","description":"When the trial started. `null` when there is no trial."},"date_trial_end":{"type":["string","null"],"format":"date-time","description":"When the trial ends, or ended. `null` when there is no trial."},"date_current_period_start":{"type":["string","null"],"format":"date-time","description":"When the current billing period started. `null` once the subscription is cancelled."},"date_current_period_end":{"type":["string","null"],"format":"date-time","description":"When the current billing period ends. The next renewal is billed at this time. `null` once the subscription is cancelled."},"date_next_renewal_notification":{"type":["string","null"],"format":"date-time","description":"When the next renewal reminder is sent to the customer. `null` when reminders are off or none is due. Not returned to a limited token."},"date_cancelled":{"type":["string","null"],"format":"date-time","description":"When the cancellation was asked for. When a cancellation is scheduled for the period end, this is set at once while the subscription stays active until `date_current_period_end`. `null` when not cancelled."},"cancellation_reason":{"type":["string","null"],"description":"Why the subscription was cancelled: the reason sent with the cancellation, or one set automatically (for example when all items were cancelled). Not returned to a limited token."},"cancel_at_current_period_end":{"type":"boolean","description":"`true` when the subscription is set to be cancelled at the end of the current billing period."},"date_ended":{"type":["string","null"],"format":"date-time","description":"When the subscription ended, by cancellation or completion. For an immediate cancellation it equals `date_cancelled`. `null` while the subscription runs."},"add_at_current_period_end":{"type":"array","description":"Items scheduled to be added at the end of the current billing period. Empty when none are scheduled. Remove them all with `DELETE /subscriptions/{subscription_id}/add_at_current_period_end`.","items":{"$ref":"#/components/schemas/subscription_item_change"}},"subscription_plan":{"oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/subscription_plan"}],"description":"The subscription plan, as a URL, or the full object with `expand=subscription_plan`. Later changes to the plan do not change existing subscriptions, so the plan can differ from the values here. Left out when the token may not read subscription plans."},"customer":{"oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/customer"}],"description":"The customer, as a URL, or the full object with `expand=customer`. Left out when the token may not read customers."},"invoices":{"oneOf":[{"type":"string","format":"uri"},{"type":"object"}],"description":"The subscription's invoices, as a URL, or an offset-based list of invoices with `expand=invoices` (only when you get one subscription, not in a list). The invoices are the billing history. Left out when the token may not read invoices."},"history":{"oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/subscription_history"}],"description":"The change log, as a URL, or the full object with `expand=history` (only when you get one subscription). Not returned to a limited token."},"meta":{"description":"Any data you stored on the subscription, up to 2,048 characters."},"formatted":{"type":"object","description":"The dates as display text in the requested locale and time zone. Only returned with `formatted=true`.","properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"},"date_cancelled":{"type":["string","null"]},"date_current_period_start":{"type":["string","null"]},"date_current_period_end":{"type":["string","null"]},"date_ended":{"type":["string","null"]},"date_next_renewal_notification":{"type":["string","null"]},"date_trial_start":{"type":["string","null"]},"date_trial_end":{"type":["string","null"]}}}},"required":["object","url","subscription_id","date_created","date_modified","test","account_id","status","in_grace_period","billing_interval","billing_interval_unit","billing_interval_description","trial_interval","trial_interval_unit","trial_interval_description","billing_count","end_at_billing_count","currency","items","shipping_method_id","date_trial_start","date_trial_end","date_current_period_start","date_current_period_end","date_cancelled","cancel_at_current_period_end","date_ended","add_at_current_period_end","meta"],"example":{"object":"subscription","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_id":"0093799318129SuLByRPW8","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-11-02T15:21:31Z","test":true,"account_id":"AB1234","status":"active","in_grace_period":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"billing_count":2,"end_at_billing_count":null,"currency":"USD","items":[{"object":"subscription_item","url":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test","item_id":"acme-pro.test","date_created":"2026-10-02T15:21:28Z","date_modified":"2026-10-02T15:21:28Z","product_id":"acme-pro.test","name":"Acme Pro (monthly)","quantity":1,"reference_price":19.95,"reference_currency":"USD","reference_discount":0,"reference_discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"cancelled":false,"cancel_at_current_period_end":false,"date_cancelled":null,"date_ended":null,"cancellation_reason":null,"tax_code":null,"type":"digital","change_at_current_period_end":null,"product":"https://api.comecero.com/api/v1/products/acme-pro.test","subscription":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8","subscription_terms":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/items/acme-pro.test/subscription_terms","meta":null}],"shipping_method_id":null,"date_trial_start":null,"date_trial_end":null,"date_current_period_start":"2026-11-02T15:21:28Z","date_current_period_end":"2026-12-02T15:21:28Z","date_next_renewal_notification":"2026-11-29T15:21:28Z","date_cancelled":null,"cancellation_reason":null,"cancel_at_current_period_end":false,"date_ended":null,"add_at_current_period_end":[],"subscription_plan":"https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C","customer":"https://api.comecero.com/api/v1/customers/0093799288003CuGOip8X9","invoices":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/invoices","history":"https://api.comecero.com/api/v1/subscriptions/0093799318129SuLByRPW8/history","meta":null}},"refund_item":{"type":"object","title":"refund_item","description":"One item refunded, with the quantity and amounts given back. Fields marked \"not for limited tokens\" are left out when a limited token reads it.","properties":{"object":{"type":"string","enum":["refund_item"],"description":"The object type. Always `refund_item`."},"url":{"type":"string","format":"uri","description":"The full URL of this refund item."},"item_id":{"type":"string","description":"The `item_id` of the order or invoice item refunded."},"date_created":{"type":"string","format":"date-time","description":"When the item was created."},"date_modified":{"type":"string","format":"date-time","description":"When the item was last changed."},"refund_id":{"type":"string","description":"The refund this item belongs to."},"name":{"type":"string","description":"The product name."},"type":{"type":"string","enum":["digital","physical","service","bundle"],"description":"The product type."},"quantity":{"type":"number","description":"The quantity refunded. Can be a decimal."},"currency":{"type":"string","description":"The refund currency (ISO 4217)."},"price":{"type":"number","description":"The unit price, in `currency`."},"reference_price":{"type":["number","null"],"description":"The price in the reference currency. Not for limited tokens."},"reference_currency":{"type":["string","null"],"description":"The currency of `reference_price`. Not for limited tokens."},"subtotal":{"type":"number","description":"The amount refunded for this item without tax, in `currency`."},"tax":{"type":"number","description":"The tax refunded for this item, in `currency`."},"total":{"type":"number","description":"`subtotal` plus `tax`, in `currency`."},"tax_rate":{"type":"number","description":"The tax rate as a decimal."},"tax_code":{"type":["string","null"],"description":"The tax code of the product. Not for limited tokens."},"settlement_currency":{"type":"string","description":"The settlement currency. Not for limited tokens."},"settlement_price":{"type":"number","description":"`price` in the settlement currency. Not for limited tokens."},"settlement_subtotal":{"type":"number","description":"`subtotal` in the settlement currency. Not for limited tokens."},"settlement_tax":{"type":"number","description":"`tax` in the settlement currency. Not for limited tokens."},"settlement_total":{"type":"number","description":"`total` in the settlement currency. Not for limited tokens."},"fulfilled":{"type":"boolean","description":"Whether the order item was fulfilled when it was refunded."},"product":{"description":"A link to the product, or the product when expanded.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/product"},{"type":"null"}]},"subscription":{"description":"A link to the subscription of the item, or the subscription when expanded. Null when the item is not a subscription.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/subscription"},{"type":"null"}]},"meta":{"description":"Your own data for this item, a string or an object.","type":["object","string","null"]},"formatted":{"type":"object","description":"Display text. Only present when you send `formatted=true`."}},"required":["object","url","item_id","refund_id","name","type","quantity","currency","price","subtotal","tax","total","tax_rate","fulfilled","meta"],"example":{"object":"refund_item","url":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/items/1","item_id":"1","date_created":"2026-11-02T16:46:16Z","date_modified":"2026-11-03T10:12:40Z","refund_id":"0090374314462Rec3PffZ5","name":"PDF Viewer Pro","type":"digital","quantity":1,"currency":"USD","price":49.95,"reference_price":49.95,"reference_currency":"USD","subtotal":49.95,"tax":0,"total":49.95,"tax_rate":0,"tax_code":null,"settlement_currency":"USD","settlement_price":49.95,"settlement_subtotal":49.95,"settlement_tax":0,"settlement_total":49.95,"fulfilled":true,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription":null,"meta":null}},"shipment_item":{"type":"object","title":"shipment_item","description":"One order item in a shipment, with the quantity sent.","properties":{"object":{"type":"string","enum":["shipment_item"],"description":"The object type. Always `shipment_item`."},"item_id":{"type":"string","description":"The `item_id` of the order item."},"product_id":{"type":["string","null"],"description":"The product of the order item."},"name":{"type":"string","description":"The name of the order item."},"quantity":{"type":"integer","description":"The quantity in this shipment."},"product":{"description":"A link to the product, or the product when expanded.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/product"}]}},"required":["object","item_id","product_id","name","quantity"],"example":{"object":"shipment_item","item_id":"1","product_id":"lens-cloth.test","name":"Lens cleaning cloth","quantity":2,"product":"https://api.comecero.com/api/v1/products/lens-cloth.test"}},"order":{"type":"object","title":"order","description":"What a paid cart or invoice becomes. You never create an order yourself: the API makes one when a payment on a cart or invoice succeeds or is authorized. Fields marked \"not for limited tokens\" are left out when a limited token reads the order. Links to other objects only appear when the token may read that object.","properties":{"object":{"type":"string","enum":["order"],"description":"The object type. Always `order`."},"url":{"type":"string","format":"uri","description":"The full URL of the order."},"order_id":{"type":"string","description":"The order id, for example `7393-GMRFY-954`. A cart or invoice can set it before payment; otherwise the API makes one."},"date_created":{"type":"string","format":"date-time","description":"When the order was created."},"date_modified":{"type":"string","format":"date-time","description":"When the order was last changed."},"test":{"type":"boolean","description":"True for a test order."},"account_id":{"type":"string","description":"The account the order belongs to."},"payment_status":{"type":"string","enum":["pending","completed","cancelled","refunded"],"description":"`pending` while the payment is authorized but not captured, `completed` once captured, `cancelled` after the authorization was voided, and `refunded` once the whole order was refunded."},"fulfilled":{"type":"boolean","description":"True when every item on the order is fulfilled."},"currency":{"type":"string","description":"The currency the customer paid in (ISO 4217)."},"subtotal":{"type":"number","description":"The items after item discounts, without shipping and tax, in the order currency."},"subtotal_original":{"type":"number","description":"The items before discounts, without shipping and tax, in the order currency."},"shipping":{"type":"number","description":"Shipping after discounts, without tax, in the order currency."},"shipping_original":{"type":"number","description":"Shipping before discounts, without tax, in the order currency."},"discount":{"type":"number","description":"The discount on the whole order, apart from item discounts, in the order currency."},"item_discounts":{"type":"number","description":"The sum of all item discounts, in the order currency."},"total_discounts":{"type":"number","description":"`discount` plus `item_discounts`, in the order currency."},"total_discounts_percent":{"type":"number","description":"`total_discounts` as a fraction of the original subtotal plus shipping, for example `0.1` for 10%."},"tax":{"type":"number","description":"The tax after discounts, in the order currency."},"tax_original":{"type":"number","description":"The tax before discounts, in the order currency."},"total":{"type":"number","description":"What the customer paid, in the order currency."},"total_original":{"type":"number","description":"`subtotal_original` plus `shipping_original` plus `tax_original`, in the order currency."},"tax_inclusive":{"type":"boolean","description":"True when prices include tax."},"discount_on_gross":{"type":"boolean","description":"True when the order discount was taken from the amount with tax, false when from the amount without tax."},"settlement_currency":{"type":"string","description":"The currency the money settles to your account in. Not for limited tokens."},"settlement_subtotal":{"type":"number","description":"`subtotal` in the settlement currency. Not for limited tokens."},"settlement_subtotal_original":{"type":"number","description":"`subtotal_original` in the settlement currency. Not for limited tokens."},"settlement_shipping":{"type":"number","description":"`shipping` in the settlement currency. Not for limited tokens."},"settlement_shipping_original":{"type":"number","description":"`shipping_original` in the settlement currency. Not for limited tokens."},"settlement_discount":{"type":"number","description":"`discount` in the settlement currency. Not for limited tokens."},"settlement_item_discounts":{"type":"number","description":"`item_discounts` in the settlement currency. Not for limited tokens."},"settlement_total_discounts":{"type":"number","description":"`total_discounts` in the settlement currency. Not for limited tokens."},"settlement_tax":{"type":"number","description":"`tax` in the settlement currency. Not for limited tokens."},"settlement_tax_original":{"type":"number","description":"`tax_original` in the settlement currency. Not for limited tokens."},"settlement_total":{"type":"number","description":"`total` in the settlement currency. Not for limited tokens."},"settlement_total_original":{"type":"number","description":"`total_original` in the settlement currency. Not for limited tokens."},"customer_ip_address":{"type":["string","null"],"description":"The IP address the customer bought from."},"customer_ip_country":{"type":["string","null"],"description":"The country of that IP address (ISO 3166-1 alpha-2)."},"referrer":{"type":["string","null"],"description":"Your own referrer value, copied from the cart or invoice."},"affiliate_id":{"type":["string","null"],"description":"The affiliate or partner id, copied from the cart or invoice."},"promotion_code":{"type":["string","null"],"description":"The coupon code the customer used, if any."},"items_count":{"type":"integer","description":"The number of lines on the order."},"items_quantity":{"type":"number","description":"The sum of the quantities of all lines."},"items":{"type":"array","description":"The lines on the order.","items":{"$ref":"#/components/schemas/order_item"}},"shipping_item":{"description":"The shipping line, or null when nothing ships.","oneOf":[{"$ref":"#/components/schemas/shipping_item"},{"type":"null"}]},"customer":{"description":"A link to the customer, or the customer when you send `expand=customer`.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/customer"}]},"cart":{"description":"A link to the cart the order came from, or the cart when expanded. Null when the order came from an invoice. Carts are deleted after a while; an expanded deleted cart only has `cart_id`.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/cart"},{"type":"null"}]},"payments":{"description":"A link to the order's payments, or the list when you send `expand=payments` on a single order.","oneOf":[{"type":"string","format":"uri"},{"type":"object"}]},"payment":{"deprecated":true,"description":"Old field, kept for older integrations. A link to the order's payments, or the first payment when you send `expand=payment`. Use `payments`.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/payment"}]},"subscription":{"description":"A link to the subscription that made this order (a renewal), or the subscription when expanded. Null otherwise.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/subscription"},{"type":"null"}]},"refunds":{"description":"A link to the order's refunds (successful, failed and pending), or the list when you send `expand=refunds` on a single order.","oneOf":[{"type":"string","format":"uri"},{"type":"object"}]},"fee_summary":{"description":"A link to the order's fee summary, or the summary when you send `expand=fee_summary`. Not for limited tokens.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/order_fee_summary"}]},"invoice":{"description":"A link to the invoice the order came from, or the invoice when expanded. Null when the order came from a cart.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/invoice"},{"type":"null"}]},"promotions":{"description":"A link to the promotions used on the order, or the list when you send `expand=promotions` on a single order.","oneOf":[{"type":"string","format":"uri"},{"type":"object"}]},"shipments":{"description":"A link to the order's shipments, or the list when you send `expand=shipments` on a single order.","oneOf":[{"type":"string","format":"uri"},{"type":"object"}]},"meta":{"description":"Your own data for the order, copied from the cart or invoice. A string or an object.","type":["object","string","null"]},"formatted":{"type":"object","description":"The amounts and dates as display text in the shopper's language. Only present when you send `formatted=true`."}},"required":["object","url","order_id","date_created","date_modified","test","account_id","payment_status","fulfilled","currency","subtotal","subtotal_original","shipping","shipping_original","discount","item_discounts","total_discounts","total_discounts_percent","tax","tax_original","total","total_original","tax_inclusive","discount_on_gross","items_count","items_quantity","items","shipping_item","promotions","meta"],"example":{"object":"order","url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954","order_id":"7393-GMRFY-954","date_created":"2026-11-02T16:46:16Z","date_modified":"2026-11-02T16:46:38Z","test":true,"account_id":"AB1234","payment_status":"completed","fulfilled":true,"currency":"USD","subtotal":49.95,"subtotal_original":49.95,"shipping":0,"shipping_original":0,"discount":0,"item_discounts":0,"total_discounts":0,"total_discounts_percent":0,"tax":0,"tax_original":0,"total":49.95,"total_original":49.95,"tax_inclusive":false,"discount_on_gross":false,"settlement_currency":"USD","settlement_subtotal":49.95,"settlement_subtotal_original":49.95,"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":49.95,"settlement_total_original":49.95,"customer_ip_address":"203.0.113.24","customer_ip_country":"US","referrer":null,"affiliate_id":null,"promotion_code":null,"items_count":1,"items_quantity":1,"items":[{"object":"order_item","url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/items/1","item_id":"1","cross_sell_id":null,"up_sell_id":null,"bundle_id":null,"bundle_group_id":null,"date_created":"2026-11-02T16:46:16Z","date_modified":"2026-11-02T16:46:16Z","product_id":"pdf-pro.test","order_id":"7393-GMRFY-954","name":"PDF Viewer Pro","type":"digital","quantity":1,"currency":"USD","price":49.95,"price_original":49.95,"reference_price":49.95,"reference_currency":"USD","subtotal":49.95,"subtotal_original":49.95,"discount":0,"discount_percent":0,"tax":0,"tax_original":0,"total":49.95,"total_original":49.95,"tax_rate":0,"tax_code":null,"settlement_currency":"USD","settlement_price":49.95,"settlement_price_original":49.95,"settlement_subtotal":49.95,"settlement_subtotal_original":49.95,"settlement_discount":0,"settlement_tax":0,"settlement_tax_original":0,"settlement_total":49.95,"settlement_total_original":49.95,"fulfilled":true,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription":null,"subscription_terms":null,"shipments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/items/1/shipments","license":null,"download":"https://api.comecero.com/api/v1/downloads/0093717990011DlR4kQp2a","meta":null}],"shipping_item":null,"customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","cart":"https://api.comecero.com/api/v1/carts/0093717976083CaO5bXdLA","payments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/payments","payment":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/payments","subscription":null,"refunds":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/refunds","fee_summary":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/fee_summary","invoice":null,"promotions":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/promotions","shipments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/shipments","meta":null}},"shipment":{"type":"object","title":"shipment","description":"A parcel sent for an order: which items and how many, the carrier and the tracking number. Creating shipments marks order items fulfilled.","properties":{"object":{"type":"string","enum":["shipment"],"description":"The object type. Always `shipment`."},"url":{"type":"string","format":"uri","description":"The full URL of the shipment."},"shipment_id":{"type":"string","description":"The shipment id."},"date_created":{"type":"string","format":"date-time","description":"When the shipment was created."},"date_modified":{"type":"string","format":"date-time","description":"When the shipment was last changed."},"date_shipped":{"type":"string","format":"date-time","description":"When the parcel left or will leave. Defaults to the time the shipment was created."},"test":{"type":"boolean","description":"True for a test shipment."},"account_id":{"type":"string","description":"The account the shipment belongs to."},"items":{"type":"array","description":"The order items in this shipment.","items":{"$ref":"#/components/schemas/shipment_item"}},"order":{"description":"A link to the order, or the order when you send `expand=order`. The response has no separate `order_id` field: take it from this link.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/order"}]},"courier":{"type":["string","null"],"description":"The carrier, up to 50 characters. For `UPS`, `FedEx`, `USPS`, `DHL USA`, `DHL eCommerce`, `OnTrac`, `ICC Worldwide`, `LaserShip`, `Canada Post`, `Australia Post` and `Royal Mail` (written exactly so), the API fills in `tracking_url` for you when you leave it empty."},"tracking_number":{"type":["string","null"],"description":"The tracking number."},"tracking_url":{"type":["string","null"],"description":"The tracking page, up to 256 characters. Filled in from `courier` and `tracking_number` when you leave it empty and the carrier is a known one."},"notifications":{"description":"A link to the emails sent about this shipment, or the list when you send `expand=notifications` on a single shipment.","oneOf":[{"type":"string","format":"uri"},{"type":"object"}]},"meta":{"description":"Your own data for the shipment, a string or an object. Not for limited tokens.","type":["object","string","null"]},"formatted":{"type":"object","description":"Display dates. Only present when you send `formatted=true`."}},"required":["object","url","shipment_id","date_created","date_modified","date_shipped","test","account_id","items","courier","tracking_number","tracking_url"],"example":{"object":"shipment","url":"https://api.comecero.com/api/v1/shipments/0093718200417ShQ2xN8kL","shipment_id":"0093718200417ShQ2xN8kL","date_created":"2026-11-04T09:30:00Z","date_modified":"2026-11-04T09:30:00Z","date_shipped":"2026-11-04T09:30:00Z","test":true,"account_id":"AB1234","items":[{"object":"shipment_item","item_id":"1","product_id":"lens-cloth.test","name":"Lens cleaning cloth","quantity":2,"product":"https://api.comecero.com/api/v1/products/lens-cloth.test"}],"order":"https://api.comecero.com/api/v1/orders/2979-KXVST-674","courier":"UPS","tracking_number":"1Z999AA10123456784","tracking_url":"http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784","notifications":"https://api.comecero.com/api/v1/shipments/0093718200417ShQ2xN8kL/notifications","meta":null}},"license":{"type":"object","title":"license","description":"A license key issued for one item of an order, from the product's license service. A limited token may read a license only when it is bound to it, such as the customer's own order.","properties":{"object":{"type":"string","enum":["license"],"description":"The object type. Always `license`."},"url":{"type":"string","format":"uri","description":"The URL of this license in the API."},"license_id":{"type":"string","description":"The id of the license."},"date_created":{"type":"string","format":"date-time","description":"When the license was issued."},"date_modified":{"type":"string","format":"date-time","description":"When the license was last changed."},"test":{"type":"boolean","description":"True for a test-mode license."},"item_id":{"type":"string","description":"The order item the license is for. The same as the product id."},"account_id":{"type":"string","description":"The account the license belongs to."},"label":{"type":"string","description":"What the key is called, copied from the license service, for example `License Code`."},"license_service":{"description":"The license service that issued the key, as a link, or the full object when you send `expand=license_service`. Not returned to limited tokens.","anyOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/license_service"}]},"order":{"description":"The order, as a link, or the full object when you send `expand=order`.","anyOf":[{"type":"string","format":"uri"},{"type":"object","description":"The order object."}]},"product":{"description":"The product, as a link, or the full object when you send `expand=product`.","anyOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/product"}]},"text":{"type":["string","null"],"description":"The key as plain text, with any HTML removed."},"html":{"type":["string","null"],"description":"The key as HTML, with line breaks turned into `<br>`."},"instructions":{"type":["string","null"],"description":"How to use the key, from the license service or your license server."},"formatted":{"type":"object","description":"Present only when you send `formatted=true`.","properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"}}}},"required":["object","url","license_id","date_created","date_modified","test","item_id","account_id","label","text","html","instructions"],"example":{"object":"license","url":"https://api.comecero.com/api/v1/licenses/0142130710581LiRr8sT2c","license_id":"0142130710581LiRr8sT2c","date_created":"2026-11-02T00:45:11Z","date_modified":"2026-11-02T00:45:11Z","test":true,"item_id":"widget-pro.test","account_id":"AB1234","label":"License Code","license_service":"https://api.comecero.com/api/v1/license_services/0095012789659LsuOeAWLC","order":"https://api.comecero.com/api/v1/orders/6622-NXKHE-858","product":"https://api.comecero.com/api/v1/products/widget-pro.test","text":"AAAA-BBBB-CCCC-0001","html":"AAAA-BBBB-CCCC-0001","instructions":"Open Widget Pro, choose Help, then Enter License, and paste the code."}},"download":{"type":"object","title":"download","description":"A download link to one of your files, usually made for an order item when a product with a file is bought. The link stops working after `expires` or after `expires_in_clicks` clicks. A limited token may read a download only when it is bound to it, such as one on the signed-in customer's order.","properties":{"object":{"type":"string","enum":["download"],"description":"The object type. Always `download`."},"url":{"type":"string","format":"uri","description":"The URL of this download in the API."},"download_id":{"type":"string","description":"The id of the download."},"date_created":{"type":"string","format":"date-time","description":"When the download was made."},"date_modified":{"type":"string","format":"date-time","description":"When the download was last changed."},"test":{"type":"boolean","description":"True for a test-mode download."},"account_id":{"type":"string","description":"The account the download belongs to."},"file":{"description":"The file, as a link, or the full object when you send `expand=file`. Left out for tokens that may not read files, such as limited tokens.","anyOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/file"}]},"order":{"description":"The order the download was made for, as a link, or the full object when you send `expand=order`. Null when it is not tied to an order.","anyOf":[{"type":"string","format":"uri"},{"type":"object","description":"The order object."},{"type":"null"}]},"product":{"description":"The product the download was made for, as a link, or the full object when you send `expand=product`. Null when it is not tied to a product.","anyOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/product"},{"type":"null"}]},"link":{"type":"string","format":"uri","description":"The link the customer uses to download the file. It ends in the file name."},"link_short":{"type":"string","format":"uri","description":"The same link, ending in `dl` instead of the file name."},"filename":{"type":"string","description":"The name of the file."},"bytes":{"type":"integer","description":"The size of the file in bytes."},"expired":{"type":"boolean","description":"True when the link no longer works, because it is past `expires` or out of clicks."},"expires":{"type":"string","format":"date-time","description":"When the link stops working. Not returned to limited tokens."},"expires_in_clicks":{"type":"integer","description":"How many clicks the link allows in all. Not returned to limited tokens."},"clicks":{"type":"integer","description":"How many times the link has been used. Not returned to limited tokens."},"formatted":{"type":"object","description":"Present only when you send `formatted=true`.","properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"},"bytes":{"type":"string","description":"The file size as text, for example `24.5 MB`."}}}},"required":["object","url","download_id","date_created","date_modified","test","account_id","order","product","link","link_short","filename","bytes","expired"],"example":{"object":"download","url":"https://api.comecero.com/api/v1/downloads/0142130710600DoT3ka9Lm","download_id":"0142130710600DoT3ka9Lm","date_created":"2026-11-02T00:45:12Z","date_modified":"2026-11-02T00:45:12Z","test":true,"account_id":"AB1234","file":"https://api.comecero.com/api/v1/files/0095012700001FiQ2xT7Ab","order":"https://api.comecero.com/api/v1/orders/6622-NXKHE-858","product":"https://api.comecero.com/api/v1/products/widget-pro.test","link":"https://cdn.comecero.net/sd/0142130710600DoT3ka9Lm/1/3fa9c2d1/widget-pro-setup.zip","link_short":"https://cdn.comecero.net/sd/0142130710600DoT3ka9Lm/1/3fa9c2d1/dl","filename":"widget-pro-setup.zip","bytes":24518301,"expired":false,"expires":"2026-11-09T00:45:12Z","expires_in_clicks":10,"clicks":1}},"order_item":{"type":"object","title":"order_item","description":"One line on an order. Copied from the cart or invoice item when the order was created. Fields marked \"not for limited tokens\" are left out when a limited token reads the order.","properties":{"object":{"type":"string","enum":["order_item"],"description":"The object type. Always `order_item`."},"url":{"type":"string","format":"uri","description":"The full URL of this item."},"item_id":{"type":"string","description":"The id of the item within the order."},"cross_sell_id":{"type":["string","null"],"description":"The cross-sell offer this item was added from, if any."},"up_sell_id":{"type":["string","null"],"description":"The up-sell offer this item was added from, if any."},"bundle_id":{"type":["string","null"],"description":"The product_id of the bundle this item came from. Set on the bundle's own line and on each line inside it."},"bundle_group_id":{"type":["string","null"],"description":"The id shared by every line produced by one bundle."},"date_created":{"type":"string","format":"date-time","description":"When the item was created."},"date_modified":{"type":"string","format":"date-time","description":"When the item was last changed."},"product_id":{"type":["string","null"],"description":"The product this item is for."},"order_id":{"type":"string","description":"The order this item belongs to."},"name":{"type":"string","description":"The product name at the time of sale."},"type":{"type":"string","enum":["digital","physical","service","bundle"],"description":"The product type."},"quantity":{"type":"number","description":"The quantity ordered. Can be a decimal."},"currency":{"type":"string","description":"The currency of the item, always the order currency (ISO 4217)."},"price":{"type":"number","description":"The unit price after discounts, in the order currency."},"price_original":{"type":"number","description":"The unit price before discounts, in the order currency."},"reference_price":{"type":["number","null"],"description":"The price in the reference currency that the order price was worked out from. Not for limited tokens."},"reference_currency":{"type":["string","null"],"description":"The currency of `reference_price`. Not for limited tokens."},"subtotal":{"type":"number","description":"`price` times `quantity`, without tax, in the order currency."},"subtotal_original":{"type":"number","description":"`price_original` times `quantity`, without tax, in the order currency."},"discount":{"type":"number","description":"The discount per unit, in the order currency."},"discount_percent":{"type":"number","description":"The discount as a fraction of `price_original`, for example `0.1` for 10%."},"tax":{"type":"number","description":"The tax on this item after discounts, in the order currency."},"tax_original":{"type":"number","description":"The tax on this item before discounts, in the order currency."},"total":{"type":"number","description":"`subtotal` plus `tax`, in the order currency."},"total_original":{"type":"number","description":"`subtotal_original` plus `tax_original`, in the order currency."},"tax_rate":{"type":"number","description":"The tax rate as a decimal, for example `0.2` for 20%."},"tax_code":{"type":["string","null"],"description":"The tax code of the product. Not for limited tokens."},"settlement_currency":{"type":"string","description":"The currency the money settles to your account in. Not for limited tokens."},"settlement_price":{"type":"number","description":"`price` in the settlement currency. Not for limited tokens."},"settlement_price_original":{"type":"number","description":"`price_original` in the settlement currency. Not for limited tokens."},"settlement_subtotal":{"type":"number","description":"`subtotal` in the settlement currency. Not for limited tokens."},"settlement_subtotal_original":{"type":"number","description":"`subtotal_original` in the settlement currency. Not for limited tokens."},"settlement_discount":{"type":"number","description":"`discount` in the settlement currency. Not for limited tokens."},"settlement_tax":{"type":"number","description":"`tax` in the settlement currency. Not for limited tokens."},"settlement_tax_original":{"type":"number","description":"`tax_original` in the settlement currency. Not for limited tokens."},"settlement_total":{"type":"number","description":"`total` in the settlement currency. Not for limited tokens."},"settlement_total_original":{"type":"number","description":"`total_original` in the settlement currency. Not for limited tokens."},"fulfilled":{"type":"boolean","description":"True when every unit of this item has shipped or was marked fulfilled."},"product":{"description":"A link to the product, or the product when you send `expand=product`. Null when the item has no product.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/product"},{"type":"null"}]},"subscription":{"description":"A link to the subscription this item started or renewed, or the subscription when expanded. Null when the item is not a subscription.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/subscription"},{"type":"null"}]},"subscription_terms":{"description":"For subscription items, a link to the subscription terms, or the terms when you send `expand=subscription_terms`. Null otherwise.","oneOf":[{"type":"string","format":"uri"},{"type":"object"},{"type":"null"}]},"shipments":{"description":"A link to the shipments that contain this item, or the shipments when you send `expand=items.shipments` on a single order or item.","oneOf":[{"type":"string","format":"uri"},{"type":"array","items":{"$ref":"#/components/schemas/shipment"}}]},"license":{"description":"A link to the license key given for this item, or the license when expanded. Null when the item has no license.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/license"},{"type":"null"}]},"license_pending":{"type":"boolean","description":"Present and `true` only when the item should get a license key but has not got one yet."},"download":{"description":"A link to the download for this item, or the download when expanded. Null when the item has no download.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/download"},{"type":"null"}]},"meta":{"description":"Your own data for this item, copied from the cart or invoice item. A string or an object.","type":["object","string","null"]},"formatted":{"type":"object","description":"The amounts and dates as display text. Only present when you send `formatted=true`."}},"required":["object","url","item_id","date_created","date_modified","order_id","name","type","quantity","currency","price","price_original","subtotal","subtotal_original","discount","discount_percent","tax","tax_original","total","total_original","tax_rate","fulfilled","meta"],"example":{"object":"order_item","url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/items/1","item_id":"1","cross_sell_id":null,"up_sell_id":null,"bundle_id":null,"bundle_group_id":null,"date_created":"2026-11-02T16:46:16Z","date_modified":"2026-11-02T16:46:16Z","product_id":"pdf-pro.test","order_id":"7393-GMRFY-954","name":"PDF Viewer Pro","type":"digital","quantity":1,"currency":"USD","price":49.95,"price_original":49.95,"reference_price":49.95,"reference_currency":"USD","subtotal":49.95,"subtotal_original":49.95,"discount":0,"discount_percent":0,"tax":0,"tax_original":0,"total":49.95,"total_original":49.95,"tax_rate":0,"tax_code":null,"settlement_currency":"USD","settlement_price":49.95,"settlement_price_original":49.95,"settlement_subtotal":49.95,"settlement_subtotal_original":49.95,"settlement_discount":0,"settlement_tax":0,"settlement_tax_original":0,"settlement_total":49.95,"settlement_total_original":49.95,"fulfilled":true,"product":"https://api.comecero.com/api/v1/products/pdf-pro.test","subscription":null,"subscription_terms":null,"shipments":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/items/1/shipments","license":null,"download":"https://api.comecero.com/api/v1/downloads/0093717990011DlR4kQp2a","meta":null}},"order_fee_summary":{"type":"object","title":"fee_summary","description":"The Comecero fees charged on a payment, a refund or a whole order, added up. An order's summary adds the fees of all its payments and their refunds. Amounts in different currencies are never added together: the top-level amounts are in `currency`, and `totals` has one entry per currency.","properties":{"object":{"type":"string","enum":["fee_summary"],"description":"The object type. Always `fee_summary`."},"url":{"type":["string","null"],"format":"uri","description":"The URL of this summary. Null when no fees were recorded."},"fixed_amount":{"type":"number","description":"The sum of the fixed fees, in `currency`."},"percentage_amount":{"type":"number","description":"The sum of the percentage fees, in `currency`."},"total":{"type":"number","description":"`fixed_amount` plus `percentage_amount`, in `currency`."},"currency":{"type":["string","null"],"description":"The currency of the top-level amounts (the first payment's fee currency). Null when no fees were recorded."},"totals":{"type":"array","description":"The sums for each currency, the top-level currency first.","items":{"type":"object","properties":{"currency":{"type":"string","description":"The currency of this entry."},"fixed_amount":{"type":"number","description":"The sum of the fixed fees in this currency."},"percentage_amount":{"type":"number","description":"The sum of the percentage fees in this currency."},"total":{"type":"number","description":"The sum of all fees in this currency."},"formatted":{"type":"object","description":"Display text. Only present when you send `formatted=true`."}}}},"formatted":{"type":"object","description":"Display text. Only present when you send `formatted=true`."}},"required":["object","url","fixed_amount","percentage_amount","total","currency","totals"],"example":{"object":"fee_summary","url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954/fee_summary","fixed_amount":0.3,"percentage_amount":2.25,"total":2.55,"currency":"USD","totals":[{"currency":"USD","fixed_amount":0.3,"percentage_amount":2.25,"total":2.55}]}},"invoice_item":{"type":"object","title":"invoice_item","description":"A line on an invoice. It is either a product from your catalog (it has a `product_id`) or a custom item you describe on the invoice itself (no `product_id`). Money fields are in the invoice currency unless the field name starts with `settlement_`.","x-limited":true,"x-response":true,"properties":{"object":{"type":"string","enum":["invoice_item"],"description":"The object type. Always `invoice_item`."},"url":{"type":"string","format":"uri","description":"The full URL of this item."},"item_id":{"type":"string","description":"The item id. For a product it is the `product_id`. For a custom item it is the id you supplied, or a number Comecero assigns (`1`, `2` and so on)."},"invoice_id":{"type":"string","description":"The invoice this item belongs to."},"cross_sell_id":{"type":["string","null"],"description":"The cross-sell promotion that added this item, if any."},"up_sell_id":{"type":["string","null"],"description":"The up-sell promotion that added this item, if any."},"bundle_id":{"type":["string","null"],"description":"When this item comes from a bundle product, the bundle's `product_id`."},"bundle_group_id":{"type":["string","null"],"description":"Shared by the bundle's own item and every item it expands into. Items in a bundle group cannot be changed one at a time: delete any one of them to remove the whole group, then add the bundle again."},"date_created":{"type":"string","format":"date-time","description":"When the item was added."},"date_modified":{"type":"string","format":"date-time","description":"When the item was last changed."},"product_id":{"type":["string","null"],"description":"The product this item is for, or null for a custom item."},"name":{"type":"string","description":"The item name. For a product it is the product name."},"type":{"type":"string","enum":["digital","physical","service","bundle","shipping"],"description":"The item type. `shipping` only on the shipping line (Get the invoice shipping item)."},"quantity":{"type":"number","description":"The quantity. Invoices allow decimal quantities with up to 8 decimal places."},"currency":{"type":"string","description":"The invoice currency, a three-letter ISO 4217 code."},"price":{"type":"number","description":"The unit price after discounts, in the invoice currency."},"price_original":{"type":"number","description":"The unit price before discounts, in the invoice currency."},"reference_price":{"type":["number","null"],"description":"The price you set for this item, in `reference_currency`. Comecero converts it to the invoice currency to get `price`. Null when the product's own price is used. Not returned to limited tokens."},"reference_currency":{"type":["string","null"],"description":"The currency of `reference_price`. Not returned to limited tokens."},"subtotal":{"type":"number","description":"`price` times `quantity`, in the invoice currency."},"subtotal_original":{"type":"number","description":"`price_original` times `quantity`, in the invoice currency."},"discount":{"type":"number","description":"The discount on one unit, in the invoice currency."},"discount_percent":{"type":"number","description":"The unit discount as a fraction of `price_original`, for example `0.1` for 10%."},"tax":{"type":"number","description":"The tax on this line after discounts, in the invoice currency."},"tax_original":{"type":"number","description":"The tax on this line before discounts, in the invoice currency."},"total":{"type":"number","description":"`subtotal` plus `tax`, in the invoice currency."},"total_original":{"type":"number","description":"`subtotal_original` plus `tax_original`, in the invoice currency."},"tax_rate":{"type":"number","description":"The tax rate applied, as a fraction, for example `0.2` for 20%."},"tax_code":{"type":["string","null"],"description":"The tax code used to work out tax. Not returned to limited tokens."},"settlement_currency":{"type":"string","description":"The currency you are paid out in. This and the other `settlement_` fields are not returned to limited tokens."},"settlement_price":{"type":"number","description":"`price` in the settlement currency."},"settlement_price_original":{"type":"number","description":"`price_original` in the settlement currency."},"settlement_subtotal":{"type":"number","description":"`subtotal` in the settlement currency."},"settlement_subtotal_original":{"type":"number","description":"`subtotal_original` in the settlement currency."},"settlement_discount":{"type":"number","description":"`discount` in the settlement currency."},"settlement_tax":{"type":"number","description":"`tax` in the settlement currency."},"settlement_tax_original":{"type":"number","description":"`tax_original` in the settlement currency."},"settlement_total":{"type":"number","description":"`total` in the settlement currency."},"settlement_total_original":{"type":"number","description":"`total_original` in the settlement currency."},"product":{"oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/product"},{"type":"null"}],"description":"A link to the product, or the product itself when you expand `product`. Null for a custom item. Left out when the token may not read products."},"subscription_plan":{"oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/subscription_plan"},{"type":"null"}],"description":"A link to the subscription plan, or the plan itself when you expand `subscription_plan`. Null when the item is not a subscription. Paying the invoice starts the subscription."},"subscription_terms":{"type":["string","object","null"],"description":"For a subscription item, a link to its terms (price, billing interval, trial), or the terms themselves when you expand `subscription_terms`. Null otherwise."},"meta":{"type":["object","null"],"additionalProperties":true,"description":"Your own data for this item, up to 2,048 characters as JSON."},"formatted":{"type":"object","additionalProperties":true,"description":"Only when you send `formatted=true`. The money, percent and date fields above as display text."}},"example":{"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,"settlement_currency":"USD","settlement_price":95,"settlement_price_original":95,"settlement_subtotal":950,"settlement_subtotal_original":950,"settlement_discount":0,"settlement_tax":0,"settlement_tax_original":0,"settlement_total":950,"settlement_total_original":950,"product":null,"subscription_plan":null,"subscription_terms":null,"meta":null}},"invoice_shipping_item":{"type":"object","title":"invoice_shipping_item","description":"The shipping line of an invoice. Comecero adds it when the invoice has physical items and a shipping method. Money fields are in the invoice currency unless the field name starts with `settlement_`. The `settlement_` fields, `reference_price`, `reference_currency` and `tax_code` are not returned to limited tokens.","x-limited":true,"x-response":true,"properties":{"url":{"type":"string","format":"uri","description":"The full URL of the shipping item."},"item_id":{"type":"string","description":"The item id of the shipping line."},"cross_sell_id":{"type":["string","null"],"description":"Always null for shipping."},"up_sell_id":{"type":["string","null"],"description":"Always null for shipping."},"bundle_id":{"type":["string","null"],"description":"Always null for shipping."},"bundle_group_id":{"type":["string","null"],"description":"Always null for shipping."},"date_created":{"type":"string","format":"date-time","description":"When shipping was added."},"date_modified":{"type":"string","format":"date-time","description":"When shipping was last changed."},"name":{"type":"string","description":"The name of the shipping method."},"type":{"type":"string","description":"Always `shipping`."},"quantity":{"type":"number","description":"Always 1."},"currency":{"type":"string","description":"The invoice currency."},"price":{"type":"number","description":"The shipping price after discounts."},"price_original":{"type":"number","description":"The shipping price before discounts."},"reference_price":{"type":["number","null"],"description":"The shipping price in `reference_currency`."},"reference_currency":{"type":["string","null"],"description":"The currency of `reference_price`."},"subtotal":{"type":"number","description":"`price` times `quantity`."},"subtotal_original":{"type":"number","description":"`price_original` times `quantity`."},"discount":{"type":"number","description":"The shipping discount."},"discount_percent":{"type":"number","description":"The discount as a fraction of `price_original`."},"tax":{"type":"number","description":"Tax on shipping after discounts."},"tax_original":{"type":"number","description":"Tax on shipping before discounts."},"total":{"type":"number","description":"`subtotal` plus `tax`."},"total_original":{"type":"number","description":"`subtotal_original` plus `tax_original`."},"tax_rate":{"type":"number","description":"The tax rate, as a fraction."},"tax_code":{"type":["string","null"],"description":"The tax code used for shipping."},"settlement_currency":{"type":"string","description":"The currency you are paid out in."},"settlement_price":{"type":"number","description":"`price` in the settlement currency."},"settlement_price_original":{"type":"number","description":"`price_original` in the settlement currency."},"settlement_subtotal":{"type":"number","description":"`subtotal` in the settlement currency."},"settlement_subtotal_original":{"type":"number","description":"`subtotal_original` in the settlement currency."},"settlement_discount":{"type":"number","description":"`discount` in the settlement currency."},"settlement_tax":{"type":"number","description":"`tax` in the settlement currency."},"settlement_tax_original":{"type":"number","description":"`tax_original` in the settlement currency."},"settlement_total":{"type":"number","description":"`total` in the settlement currency."},"settlement_total_original":{"type":"number","description":"`total_original` in the settlement currency."},"meta":{"type":["object","null"],"additionalProperties":true,"description":"Your own data, if any."}},"example":{"url":"https://api.comecero.com/api/v1/invoices/4827-KTPMW-639/shipping_item","item_id":"2","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","name":"Standard Shipping","type":"shipping","quantity":1,"currency":"USD","price":5,"price_original":5,"reference_price":5,"reference_currency":"USD","subtotal":5,"subtotal_original":5,"discount":0,"discount_percent":0,"tax":0,"tax_original":0,"total":5,"total_original":5,"tax_rate":0,"tax_code":null,"settlement_currency":"USD","settlement_price":5,"settlement_price_original":5,"settlement_subtotal":5,"settlement_subtotal_original":5,"settlement_discount":0,"settlement_tax":0,"settlement_tax_original":0,"settlement_total":5,"settlement_total_original":5,"meta":null}},"invoice_options":{"type":"object","title":"invoice_options","description":"What the customer can do to pay this invoice right now: the payment methods and card types your gateways accept in the invoice currency, the shipping choices, and the customer fields still needed. A payment page reads this before it shows the payment form.","x-limited":true,"x-response":true,"properties":{"invoice_id":{"type":"string","description":"The invoice these options are for."},"account_id":{"type":"string","description":"The account the invoice belongs to."},"test":{"type":"boolean","description":"True for a test invoice."},"payment_methods":{"type":"array","description":"The payment methods the customer can use. Each one has `payment_method_type`, `surcharge` and `currency`, plus the setup data its type needs in the browser (for example `stripe_publishable_key` for `stripe`, `wallets` and `google_pay` or `apple_pay` for `wallet`, `amazon_pay_merchant_id` for `amazon_pay`).","items":{"type":"object","additionalProperties":true,"properties":{"payment_method_type":{"type":"string","enum":["credit_card","paypal","amazon_pay","apple_pay","customer_account_balance","ach","stripe","wallet"],"description":"The payment method type to send in `payment_method.type`."},"surcharge":{"type":"number","description":"An extra amount for this method. Currently always 0."},"currency":{"type":["string","null"],"description":"The currency of `surcharge`."}}}},"card_types":{"type":"array","description":"The card brands accepted, for example `visa` or `mastercard`.","items":{"type":"string"}},"shipping_quotes":{"type":"array","description":"The shipping methods available for the customer's country. Empty when the country is not known yet.","items":{"$ref":"#/components/schemas/shipping_quote"}},"customer_required_fields":{"type":"array","description":"Customer fields that must be filled before payment, from your payment settings and the item types, for example `billing_address.country`.","items":{"type":"string"}},"customer_optional_fields":{"type":"array","description":"Customer fields the payment form may ask for but does not need.","items":{"type":"string"}},"allowed_customer_countries":{"type":"array","description":"The countries the customer may be in, as two-letter ISO 3166 codes.","items":{"type":"string"}},"require_cardholder_name":{"type":"boolean","description":"True when a card gateway in use needs the name on the card."}},"example":{"invoice_id":"4827-KTPMW-639","account_id":"AB1234","test":true,"payment_methods":[{"payment_method_type":"credit_card","surcharge":0,"currency":null},{"payment_method_type":"paypal","surcharge":0,"currency":null}],"card_types":["visa","mastercard","amex"],"shipping_quotes":[],"customer_required_fields":["name","email","billing_address.country"],"customer_optional_fields":["billing_address.postal_code"],"allowed_customer_countries":["US","CA","GB"],"require_cardholder_name":false}},"invoice":{"type":"object","title":"invoice","description":"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_`.","x-limited":true,"x-response":true,"properties":{"object":{"type":"string","enum":["invoice"],"description":"The object type. Always `invoice`."},"url":{"type":"string","format":"uri","description":"The full URL of this invoice."},"date_created":{"type":"string","format":"date-time","description":"When the invoice was created."},"date_modified":{"type":"string","format":"date-time","description":"When the invoice was last changed."},"date_due":{"type":["string","null"],"format":"date-time","description":"When payment is due. Required before the invoice can be published."},"past_due":{"type":"boolean","description":"True when `date_due` has passed and the invoice is still unpaid, scheduled, pending, failed or waiting for a retry."},"invoice_id":{"type":"string","description":"The invoice id. It is also the `order_id` of the order the invoice becomes when paid."},"test":{"type":"boolean","description":"True for a test invoice."},"account_id":{"type":"string","description":"The account the invoice belongs to."},"order_id":{"type":"string","description":"The id the order will have once the invoice is paid. Same as `invoice_id`."},"open":{"type":"boolean","description":"True while the invoice can still be changed or paid. It turns false when the invoice is paid in full."},"payment_status":{"type":"string","enum":["unpaid","scheduled","processing","pending","completed","failed","retry","cancelled","refunded"],"description":"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."},"currency":{"type":"string","description":"The currency the customer pays in, a three-letter ISO 4217 code."},"subtotal":{"type":"number","description":"The sum of the item subtotals after item discounts."},"subtotal_original":{"type":"number","description":"The sum of the item subtotals before discounts."},"shipping":{"type":"number","description":"Shipping after discounts."},"shipping_original":{"type":"number","description":"Shipping before discounts."},"discount":{"type":"number","description":"The discount on the whole invoice, apart from item discounts."},"item_discounts":{"type":"number","description":"The sum of all item discounts."},"total_discounts":{"type":"number","description":"`discount` plus `item_discounts`."},"total_discounts_percent":{"type":"number","description":"The total discount as a fraction of the original total."},"tax":{"type":"number","description":"Tax after discounts."},"tax_original":{"type":"number","description":"Tax before discounts."},"total":{"type":"number","description":"The amount the customer pays."},"total_original":{"type":"number","description":"`subtotal_original` plus `shipping_original` plus `tax_original`."},"tax_inclusive":{"type":"boolean","description":"True when item prices already include tax."},"total_payments":{"type":"number","description":"The amount paid so far."},"total_remaining":{"type":"number","description":"`total` minus `total_payments`: what is still to pay."},"discount_on_gross":{"type":"boolean","description":"True when discounts are taken from the tax-inclusive price."},"autopay":{"type":"boolean","description":"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":{"type":"boolean","description":"True when Comecero made this invoice for a mid-term subscription change."},"autopay_at":{"type":["string","null"],"format":"date-time","description":"When the automatic payment will run. Null when the invoice is not scheduled for automatic payment."},"settlement_currency":{"type":"string","description":"The currency you are paid out in. This and the other `settlement_` fields are not returned to limited tokens."},"settlement_subtotal":{"type":"number","description":"`subtotal` in the settlement currency."},"settlement_subtotal_original":{"type":"number","description":"`subtotal_original` in the settlement currency."},"settlement_shipping":{"type":"number","description":"`shipping` in the settlement currency."},"settlement_shipping_original":{"type":"number","description":"`shipping_original` in the settlement currency."},"settlement_discount":{"type":"number","description":"`discount` in the settlement currency."},"settlement_item_discounts":{"type":"number","description":"`item_discounts` in the settlement currency."},"settlement_total_discounts":{"type":"number","description":"`total_discounts` in the settlement currency."},"settlement_tax":{"type":"number","description":"`tax` in the settlement currency."},"settlement_tax_original":{"type":"number","description":"`tax_original` in the settlement currency."},"settlement_total":{"type":"number","description":"`total` in the settlement currency."},"customer_ip_address":{"type":["string","null"],"description":"The customer's IP address, when known."},"customer_ip_country":{"type":["string","null"],"description":"The country of `customer_ip_address`, a two-letter ISO 3166 code."},"referrer":{"type":["string","null"],"description":"Where the sale came from, as you set it."},"affiliate_id":{"type":["string","null"],"description":"The affiliate credited with the sale, as you set it."},"promotion_code":{"type":["string","null"],"description":"The coupon code applied to the invoice."},"items_count":{"type":"integer","description":"The number of items."},"items_quantity":{"type":"number","description":"The sum of the item quantities."},"draft":{"type":"boolean","description":"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":{"type":"array","description":"The items on the invoice.","items":{"$ref":"#/components/schemas/invoice_item"}},"shipping_item":{"oneOf":[{"$ref":"#/components/schemas/invoice_shipping_item"},{"type":"null"}],"description":"The shipping line, or null when the invoice has no shipping."},"customer":{"oneOf":[{"$ref":"#/components/schemas/customer"},{"type":"null"}],"description":"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":{"oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/order"},{"type":"null"}],"description":"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":{"type":["string","object"],"description":"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":{"oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/subscription"},{"type":"null"}],"description":"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":{"type":["string","null"],"format":"date-time","description":"For a renewal invoice, the start of the billing period it covers. Left out when the token may not read subscriptions."},"subscription_date_period_end":{"type":["string","null"],"format":"date-time","description":"For a renewal invoice, the end of the billing period it covers. Left out when the token may not read subscriptions."},"promotions":{"type":["string","object"],"description":"A link to the promotions applied to the invoice, or the list when you expand `promotions` on a single invoice."},"options":{"oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/invoice_options"}],"description":"A link to the payment options for the invoice, or the options themselves when you expand `options` on a single invoice."},"meta":{"type":["object","null"],"additionalProperties":true,"description":"Your own data for this invoice, up to 2,048 characters as JSON."},"formatted":{"type":"object","additionalProperties":true,"description":"Only when you send `formatted=true`. The money and date fields above as display text in the customer's language."}},"example":{"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"}}},"refund":{"type":"object","title":"refund","description":"Money given back on one payment, or a chargeback or a record-only refund written down against it. Fields marked \"not for limited tokens\" are left out when a limited token reads the refund. Links to other objects only appear when the token may read that object.","properties":{"object":{"type":"string","enum":["refund"],"description":"The object type. Always `refund`."},"url":{"type":"string","format":"uri","description":"The full URL of the refund."},"refund_id":{"type":"string","description":"The refund id."},"account_id":{"type":"string","description":"The account the refund belongs to."},"success":{"type":"boolean","description":"True when the refund is completed or pending."},"status":{"type":"string","enum":["pending","completed","failed"],"description":"`completed` once the money is back with the customer, `pending` while the payment provider is still working on it, `failed` when it was refused."},"reference":{"type":["string","null"],"description":"Your own reference for the refund, up to 100 characters."},"date_created":{"type":"string","format":"date-time","description":"When the refund was created."},"date_modified":{"type":"string","format":"date-time","description":"When the refund was last changed."},"date_completed":{"type":["string","null"],"format":"date-time","description":"When the refund completed. Null until then."},"test":{"type":"boolean","description":"True for a test refund."},"currency":{"type":"string","description":"The currency of the refund, the payment currency (ISO 4217)."},"subtotal":{"type":"number","description":"The amount refunded without shipping and tax, in `currency`."},"shipping":{"type":"number","description":"The shipping refunded without tax, in `currency`."},"tax":{"type":"number","description":"The tax refunded, in `currency`."},"total":{"type":"number","description":"The whole amount refunded, in `currency`."},"reason":{"type":["string","null"],"description":"Why the refund was made. See `GET /refunds/options` for the reasons your account lists."},"apply_to_balance":{"type":"boolean","description":"True when the payment it refunds was applied to the customer account balance."},"is_chargeback":{"type":"boolean","description":"True when this records a chargeback (the bank took the money back) rather than a refund you made. Not for limited tokens."},"record_only":{"type":"boolean","description":"True when the refund was only written down and no money moved through the payment provider (for example you refunded by bank transfer, or the rest of a partial capture). Not for limited tokens."},"record_only_memo":{"type":["string","null"],"description":"How a record-only refund was really paid back. Not for limited tokens."},"response_code":{"type":["string","null"],"description":"The Comecero result code, for example `OK` or `payment_declined`. Not for limited tokens."},"response_message":{"type":["string","null"],"description":"The Comecero result message. Not for limited tokens."},"gateway_transaction_id":{"type":["string","null"],"description":"The payment provider's id for the refund. Not for limited tokens."},"gateway_error_code":{"type":["string","null"],"description":"The payment provider's own error code when the refund failed. Not for limited tokens."},"gateway_error_message":{"type":["string","null"],"description":"The payment provider's own error message when the refund failed. Not for limited tokens."},"gateway":{"description":"A link to the gateway that processed the refund, or the gateway when you send `expand=gateway`. Only for tokens that may read gateways.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/gateway"}]},"comments":{"type":["string","null"],"description":"Your own notes about the refund. Not for limited tokens."},"payment_method":{"description":"A link to the payment method the money went back to, or the payment method when you send `expand=payment_method`. Null for a record-only refund.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/payment_method"},{"type":"null"}]},"settlement_currency":{"type":"string","description":"The currency the money settles to your account in. Not for limited tokens."},"settlement_subtotal":{"type":"number","description":"`subtotal` in the settlement currency. Not for limited tokens."},"settlement_shipping":{"type":"number","description":"`shipping` in the settlement currency. Not for limited tokens."},"settlement_tax":{"type":"number","description":"`tax` in the settlement currency. Not for limited tokens."},"settlement_total":{"type":"number","description":"`total` in the settlement currency. Not for limited tokens."},"fx_rate":{"type":"number","description":"The exchange rate from `currency` to `settlement_currency`, taken from the payment. Not for limited tokens."},"reporting_currency":{"type":["string","null"],"description":"Your account's main reporting currency."},"reporting_subtotal":{"type":"number","description":"`subtotal` in the reporting currency."},"reporting_shipping":{"type":"number","description":"`shipping` in the reporting currency."},"reporting_tax":{"type":"number","description":"`tax` in the reporting currency."},"reporting_total":{"type":"number","description":"`total` in the reporting currency."},"reporting_fx_rate":{"type":"number","description":"The rate from the settlement currency to the reporting currency."},"reporting_alt_currency":{"type":"string","description":"Your account's second reporting currency. This and the other `reporting_alt_` fields are only present when the account has one."},"reporting_alt_subtotal":{"type":"number","description":"`subtotal` in the second reporting currency."},"reporting_alt_shipping":{"type":"number","description":"`shipping` in the second reporting currency."},"reporting_alt_tax":{"type":"number","description":"`tax` in the second reporting currency."},"reporting_alt_total":{"type":"number","description":"`total` in the second reporting currency."},"reporting_alt_fx_rate":{"type":"number","description":"The rate from the settlement currency to the second reporting currency."},"items":{"description":"For a refund on an order or invoice that names items, a link to the refunded items, or the items when you send `expand=items`. Null when the refund has no items.","oneOf":[{"type":"string","format":"uri"},{"type":"array","items":{"$ref":"#/components/schemas/refund_item"}},{"type":"null"}]},"customer":{"description":"A link to the customer, or the customer when expanded.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/customer"}]},"order":{"description":"A link to the order, or the order when expanded. Null when the payment has no order.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/order"},{"type":"null"}]},"payment":{"description":"A link to the payment refunded, or the payment when expanded.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/payment"}]},"invoice":{"description":"A link to the invoice, or the invoice when expanded. Null when the payment has no invoice.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/invoice"},{"type":"null"}]},"fees":{"description":"A link to the fees on this refund, or the list when you send `expand=fees` on a single refund. Not for limited tokens.","oneOf":[{"type":"string","format":"uri"},{"type":"object"}]},"fee_summary":{"description":"A link to the refund's fee summary, or the summary when expanded. Not for limited tokens.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/order_fee_summary"}]},"commissions":{"description":"A link to the commissions on this refund, or the list when you send `expand=commissions` on a single refund. Not for limited tokens.","oneOf":[{"type":"string","format":"uri"},{"type":"object"}]},"debug":{"type":"string","format":"uri","description":"A link to the payment provider's raw requests and responses. Only present for accounts on the agent model, and for Comecero staff."},"meta":{"description":"Your own data for the refund, a string or an object.","type":["object","string","null"]},"formatted":{"type":"object","description":"The amounts and dates as display text. Only present when you send `formatted=true`."}},"required":["object","url","refund_id","account_id","success","status","reference","date_created","date_modified","date_completed","test","currency","subtotal","shipping","tax","total","reason","apply_to_balance","payment_method","reporting_currency","reporting_subtotal","reporting_shipping","reporting_tax","reporting_total","reporting_fx_rate","items","meta"],"example":{"object":"refund","url":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5","refund_id":"0090374314462Rec3PffZ5","account_id":"AB1234","success":true,"status":"completed","reference":null,"date_created":"2026-11-03T10:12:40Z","date_modified":"2026-11-03T10:12:41Z","date_completed":"2026-11-03T10:12:41Z","test":true,"currency":"USD","subtotal":49.95,"shipping":0,"tax":0,"total":49.95,"reason":"Customer request","apply_to_balance":false,"is_chargeback":false,"record_only":false,"record_only_memo":null,"response_code":"OK","response_message":"OK","gateway_transaction_id":"re_test_3PffZ5","gateway_error_code":null,"gateway_error_message":null,"gateway":"https://api.comecero.com/api/v1/gateways/0089584408915Gtf5AsdJ8","comments":null,"payment_method":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/payment_method","settlement_currency":"USD","settlement_subtotal":49.95,"settlement_shipping":0,"settlement_tax":0,"settlement_total":49.95,"fx_rate":1,"reporting_currency":"USD","reporting_subtotal":49.95,"reporting_shipping":0,"reporting_tax":0,"reporting_total":49.95,"reporting_fx_rate":1,"items":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/items","customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","order":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954","payment":"https://api.comecero.com/api/v1/payments/0093717991362PyRYN1qc6","invoice":null,"fees":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fees","fee_summary":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fee_summary","commissions":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/commissions","meta":null}},"commission":{"type":"object","title":"commission","description":"Money Comecero owes your account for a sale it collected on its own gateway (you sell through Comecero as a reseller or agent). A refund makes a negative commission. No commission is made on sales through your own gateway. Commissions with the same `accounting_id` are paid together.","properties":{"object":{"type":"string","enum":["commission"],"description":"Always `commission`."},"url":{"type":"string","format":"uri","readOnly":true,"description":"The URL of this commission in the API."},"commission_id":{"type":"string","readOnly":true,"description":"The commission id."},"date_created":{"type":"string","format":"date-time","readOnly":true,"description":"When the payment or refund completed."},"date_modified":{"type":"string","format":"date-time","readOnly":true,"description":"When the commission last changed."},"test":{"type":"boolean","readOnly":true,"description":"`true` for a test mode commission. Test commissions are never paid."},"total":{"type":"number","description":"The amount, in `currency`. On a payment it is the settled total minus tax (the full total, tax included, for an agent account). On a refund it is negative."},"currency":{"type":"string","description":"The ISO 4217 settlement currency of `total`."},"type":{"type":"string","enum":["product_sales"],"description":"What the commission is for. Only `product_sales`."},"description":{"type":["string","null"],"description":"What the commission is, in words."},"transaction_type":{"type":["string","null"],"enum":["payment","refund",null],"description":"`payment` or `refund`."},"transaction":{"description":"The payment or refund: its URL, or the full object with `expand=transaction`. Left out when the token may not read it.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/payment"},{"$ref":"#/components/schemas/refund"}]},"accounting_id":{"type":["string","null"],"description":"The payout period the commission is paid in, for example `C-AB1234P261130USD` (account, `P` for payable, period end date as YYMMDD, currency)."},"formatted":{"type":"object","readOnly":true,"description":"Amounts and dates as display text. Only returned with `formatted=true`.","properties":{"total":{"type":"string"},"date_created":{"type":"string"},"date_modified":{"type":"string"}}}},"example":{"object":"commission","url":"https://api.comecero.com/api/v1/commissions/1102611073852CMr8Wd1Nh","commission_id":"1102611073852CMr8Wd1Nh","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:10Z","test":true,"total":99.95,"currency":"USD","type":"product_sales","description":null,"transaction_type":"payment","transaction":"https://api.comecero.com/api/v1/payments/1102611073840PAz3Tq9Xc","accounting_id":"C-AB1234P261130USD"}},"commission_list":{"title":"commission_list","description":"A cursor-based page of commissions.","allOf":[{"$ref":"#/components/schemas/list_cursor"},{"type":"object","properties":{"data":{"type":"array","description":"The commissions on this page.","items":{"$ref":"#/components/schemas/commission"}}}}]},"country":{"type":"object","title":"country","description":"A country, with what an address form for it needs.","readOnly":true,"properties":{"name":{"type":"string","description":"The country's name in English."},"code":{"type":"string","description":"The ISO 3166-1 alpha-2 code."},"currency_code":{"type":["string","null"],"description":"The ISO 4217 code of the country's currency."},"currency_code_alternate":{"type":["string","null"],"description":"A second currency in common use there, if any."},"default_locale":{"type":["string","null"],"description":"The usual locale, such as `en-US`."},"is_eu":{"type":"boolean","description":"True for a country Comecero treats as in the EU for VAT."},"has_postal_code":{"type":"boolean","description":"True when addresses there use a postal code."},"requires_state_prov":{"type":"boolean","description":"True when an address there needs a state or province."},"state_taxes":{"type":"boolean","description":"True when sales tax depends on the state or province."},"states":{"type":"array","description":"The states or provinces, for the countries that list them.","items":{"type":"object","properties":{"name":{"type":"string","description":"The name."},"code":{"type":"string","description":"The code to send as `state_prov`."}}}}},"example":{"name":"Canada","code":"CA","currency_code":"CAD","currency_code_alternate":null,"default_locale":"en-CA","is_eu":false,"has_postal_code":true,"requires_state_prov":true,"state_taxes":true,"states":[{"name":"Alberta","code":"AB"},{"name":"British Columbia","code":"BC"}]}},"country_list":{"type":"object","title":"country_list","description":"Every country, in one page.","readOnly":true,"properties":{"object":{"type":"string","enum":["list"],"description":"Always `list`."},"has_more":{"type":"boolean","description":"Always `false`. Every country comes in one response."},"total_count":{"type":"integer","description":"The number of countries."},"data":{"type":"array","description":"The countries, sorted by name.","items":{"$ref":"#/components/schemas/country"}}}},"customer_list":{"type":"object","title":"customer_list","description":"A cursor-based list of customers.","properties":{"next_page_url":{"type":["string","null"],"description":"The URL of the next page, or `null` on the last page."},"next_page_after_item":{"type":["string","null"],"description":"The `after_item` value for the next page."},"previous_page_url":{"type":["string","null"],"description":"The URL of the previous page, or `null` on the first page."},"previous_page_before_item":{"type":["string","null"],"description":"The `before_item` value for the previous page."},"current_page_url":{"type":"string","description":"The URL of this page."},"data":{"type":"array","description":"The customers on this page.","items":{"$ref":"#/components/schemas/customer"}}},"required":["next_page_url","next_page_after_item","previous_page_url","previous_page_before_item","current_page_url","data"]},"customer_login_request":{"type":"object","title":"customer_login_request","x-limited":true,"x-request":true,"description":"The customer's sign-in details.","properties":{"username":{"type":"string","description":"The customer's username. Not case sensitive."},"password":{"type":"string","writeOnly":true,"description":"The customer's password."}},"required":["username","password"],"example":{"username":"johndoe","password":"s3cret-pass"}},"customer_login":{"title":"customer_login","x-limited":true,"x-response":true,"description":"The customer who signed in. When the request was made without a token or with a secret token, `auth` holds a new limited token for that customer. When the request was made with a limited token, `auth` is left out: that token now acts for the customer.","allOf":[{"$ref":"#/components/schemas/customer"},{"type":"object","properties":{"auth":{"type":"object","title":"customer_login_auth","description":"The new limited token for the customer. Only here when the request had no limited token. Keep `token`: it is shown only this once.","properties":{"object":{"type":"string","enum":["auth"],"description":"The object type. Always `auth`."},"url":{"type":"string","description":"The full URL of the token."},"auth_id":{"type":"string","description":"The id of the token."},"test":{"type":"boolean","description":"True for a test token."},"account_id":{"type":"string","description":"The id of the account."},"account_alias":{"type":["string","null"],"description":"The account's alias."},"type":{"type":"string","enum":["limited"],"description":"The token type. Always `limited`."},"ip_address":{"type":["string","null"],"description":"The shopper's IP address the token was made for."},"token":{"type":"string","description":"The token to send in the `Authorization: Bearer` header."},"expires":{"type":["string","null"],"format":"date-time","description":"When the token expires. A limited token's expiry moves later as it is used."},"expires_in_seconds":{"type":["integer","null"],"description":"Seconds until the token expires."},"date_last_used":{"type":["string","null"],"format":"date-time","description":"The day the token was last used."},"comments":{"type":["string","null"],"description":"Notes on the token."},"date_created":{"type":"string","format":"date-time","description":"When the token was created."},"date_modified":{"type":"string","format":"date-time","description":"When the token was last changed."},"customer":{"type":["string","object"],"description":"The URL of the customer, or the customer when expanded."},"roles":{"type":["array","null"],"items":{"type":"string"},"description":"The roles on the token."},"permissions":{"type":["array","null"],"items":{"type":"object"},"description":"Extra permissions on the token."},"effective_permissions":{"type":["array","null"],"items":{"type":"object"},"description":"Everything the token may do."}}}}}],"example":{"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":null,"billing_address":{"object":"address","name":"John Doe","address_1":"123 Main St.","address_2":null,"city":"New York","state_prov":"NY","postal_code":"10019","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","auth":{"object":"auth","url":"https://api.comecero.com/api/v1/auths/5d1f0c3e9b7a4f2e8c6d1a0b3e5f7a9c","auth_id":"5d1f0c3e9b7a4f2e8c6d1a0b3e5f7a9c","test":true,"account_id":"AB1234","account_alias":"example-shop","type":"limited","ip_address":"203.0.113.10","token":"lt_test_example_token","expires":"2026-11-03T18:20:00Z","expires_in_seconds":86400,"date_last_used":null,"comments":null,"date_created":"2026-11-02T18:20:00Z","date_modified":"2026-11-02T18:20:00Z","customer":"https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3","roles":null,"permissions":null,"effective_permissions":[]}}},"customer_balance_transaction":{"type":"object","title":"customer_balance_transaction","x-limited":true,"x-response":true,"description":"One change to a customer's store credit: money added (a positive amount) or taken (a negative amount). Transactions cannot be changed or deleted.","properties":{"object":{"type":"string","enum":["customer_balance_transaction"],"description":"The object type. Always `customer_balance_transaction`."},"url":{"type":"string","description":"The full URL of the transaction."},"customer_balance_transaction_id":{"type":"string","description":"The id of the transaction."},"customer_id":{"type":"string","description":"The id of the customer."},"account_id":{"type":"string","description":"The id of the account."},"test":{"type":"boolean","description":"True for a test transaction."},"date_created":{"type":"string","format":"date-time","description":"When the transaction was made."},"amount":{"type":"number","description":"The change to the balance, in `currency` (the balance currency). Positive adds credit, negative takes it."},"current_balance":{"type":"number","description":"The balance right after this transaction, in `currency`. Can be negative."},"currency":{"type":"string","description":"The balance currency, which `amount` and `current_balance` are in."},"transaction_amount":{"type":"number","description":"The change in the currency it was made in (`transaction_currency`). Positive adds credit, negative takes it."},"transaction_currency":{"type":"string","description":"The currency the payment or refund behind this transaction was in."},"memo":{"type":["string","null"],"description":"A note on the transaction, for example why a refund was reversed."},"created_by":{"type":["string","null"],"description":"The id of the user who made the transaction by hand, or `null`."},"payment":{"type":["string","object","null"],"description":"The URL of the payment behind this transaction, the payment when expanded, or `null`. Only present when your token may read payments.","x-expandable-url":true},"refund":{"type":["string","object","null"],"description":"The URL of the refund behind this transaction, the refund when expanded, or `null`. Only present when your token may read refunds.","x-expandable-url":true},"formatted":{"type":"object","description":"Only when you send `formatted=true`. Display text.","properties":{"date_created":{"type":"string"},"amount":{"type":"string"},"current_balance":{"type":"string"},"transaction_amount":{"type":"string"}}}},"example":{"object":"customer_balance_transaction","url":"https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/balance/transactions/0093045112207CxAb12Cd3","customer_balance_transaction_id":"0093045112207CxAb12Cd3","customer_id":"0091304300408CuoxY9Pf3","account_id":"AB1234","test":true,"date_created":"2026-11-04T15:02:11Z","amount":25,"current_balance":25,"currency":"USD","transaction_amount":25,"transaction_currency":"USD","memo":null,"created_by":null,"payment":null,"refund":"https://api.comecero.com/api/v1/refunds/0093045112100ReQw34Er5"},"required":["object","url","customer_balance_transaction_id","customer_id","account_id","test","date_created","amount","current_balance","currency","transaction_amount","transaction_currency","memo","created_by"]},"customer_balance_transaction_list":{"type":"object","title":"customer_balance_transaction_list","description":"A cursor-based list of balance transactions.","properties":{"next_page_url":{"type":["string","null"],"description":"The URL of the next page, or `null` on the last page."},"next_page_after_item":{"type":["string","null"],"description":"The `after_item` value for the next page."},"previous_page_url":{"type":["string","null"],"description":"The URL of the previous page, or `null` on the first page."},"previous_page_before_item":{"type":["string","null"],"description":"The `before_item` value for the previous page."},"current_page_url":{"type":"string","description":"The URL of this page."},"data":{"type":"array","description":"The transactions on this page.","items":{"$ref":"#/components/schemas/customer_balance_transaction"}}},"required":["next_page_url","next_page_after_item","previous_page_url","previous_page_before_item","current_page_url","data"]},"invoice_list_offset":{"type":"object","title":"invoice_list_offset","description":"An offset-based list of invoices.","x-response":true,"properties":{"total_items":{"type":"integer","description":"The number of items in the whole list."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The page number of this page, starting at 1."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The items on this page.","items":{"$ref":"#/components/schemas/invoice"}}}},"payment_method_create_request":{"type":"object","title":"payment_method_create_request","x-limited":true,"x-request":true,"description":"A card or US bank account to save to a customer. Only `credit_card` and `ach` can be added this way. Other kinds are saved by a payment with `save: true`.","properties":{"type":{"type":"string","enum":["credit_card","ach"],"description":"The kind of payment method."},"data":{"description":"The card or bank account details.","oneOf":[{"$ref":"#/components/schemas/payment_method_card_request"},{"$ref":"#/components/schemas/payment_method_ach_request"}]},"is_default":{"type":"boolean","default":false,"description":"Make this the customer's default payment method. The customer's first payment method is always the default."},"validate":{"type":"boolean","default":true,"description":"Secret token only (a limited token's value is ignored). Send `false` to save without the $0 check at the gateway. A card sent as a `token` is always checked."}},"required":["type","data"],"example":{"type":"credit_card","data":{"number":"4444555566661111","cvv":"123","exp_month":12,"exp_year":2028,"cardholder_name":"John Doe","billing_address":{"name":"John Doe","address_1":"123 Main St.","city":"New York","state_prov":"NY","postal_code":"10019","country":"US"}},"is_default":true}},"payment_method_update_request":{"type":"object","title":"payment_method_update_request","x-limited":true,"x-request":true,"description":"The changes to a saved payment method. Only the fields you send change. For a card you can change the expiry, name, label and billing address; the number cannot change (save a new card instead). For other types only `is_default` can change.","properties":{"type":{"type":"string","description":"Optional. If sent, it must match the saved type; the type cannot change."},"is_default":{"type":"boolean","description":"Send `true` to make this the default payment method. `false` does nothing: make another method the default instead."},"data":{"type":"object","title":"payment_method_card_update","description":"Card changes. Ignored for types other than `credit_card`.","properties":{"exp_month":{"type":"integer","minimum":1,"maximum":12,"description":"The new expiry month."},"exp_year":{"type":"integer","description":"The new expiry year, as two or four digits. The card must not have expired. A new expiry is also sent to the gateways that hold the card."},"cardholder_name":{"type":"string","maxLength":100,"description":"The name on the card."},"label":{"type":["string","null"],"maxLength":100,"description":"Your name for the card. Sending the brand and last four (for example `Visa 1111`) clears it."},"billing_address":{"$ref":"#/components/schemas/address_request"}}}},"example":{"is_default":true,"data":{"exp_month":3,"exp_year":2030}}},"subscription_item_request":{"type":"object","title":"subscription_item_request","description":"An item to bill for. Send a `product_id` to bill for a product from your catalog. Or leave `product_id` out to add a custom item: then `name`, `type`, `reference_price` (more than 0) and `reference_currency` are required. A reseller account must send `product_id`, and in practice so must a limited token, because it may not send prices.","properties":{"product_id":{"type":"string","description":"The product to bill for. The item takes its name, type and tax code from the product, and its `item_id` is the `product_id`. To add a product to a running subscription at once, the product must use the same subscription plan as the subscription."},"item_id":{"type":"string","description":"Your own id for a custom item. If you send it with `product_id`, it must equal the `product_id`. If you leave it out, a number is assigned."},"name":{"type":"string","description":"The item name. Required for a custom item. Ignored when `product_id` is sent."},"type":{"type":"string","enum":["digital","physical","service"],"description":"The kind of item. Required for a custom item. Ignored when `product_id` is sent."},"tax_code":{"type":"string","description":"The tax code for a custom item. Ignored when `product_id` is sent."},"quantity":{"type":"integer","minimum":1,"default":1,"description":"How many units to bill for."},"reference_price":{"type":"number","exclusiveMinimum":0,"description":"The price of one unit for each billing period, in `reference_currency`. Required for a custom item. For a product item it overrides the product price. A limited token may not send it (`403`)."},"reference_currency":{"type":"string","minLength":3,"maxLength":3,"description":"The three-letter ISO 4217 currency of `reference_price`. Required for a custom item. Your account must have a gateway for it. A limited token may not send it (`403`)."},"reference_discount":{"type":"number","minimum":0,"description":"A discount taken off each unit, in `reference_currency`. Cannot be more than the price. A limited token may not send it (`403`)."},"discount_apply_count":{"type":["integer","null"],"minimum":1,"description":"How many billings the discount applies to. Leave it out or send `null` to apply it to every billing. A limited token may not send it (`403`)."},"apply_immediately":{"type":"boolean","description":"Only for `POST /subscriptions/{subscription_id}/items` and its preview. `true` adds the item now and charges the prorated amount for the rest of the current period. `false` schedules it for the end of the period. The default comes from the immediate upgrade product types in your subscription settings. Sending a value other than the default needs permission to update subscription settings. A limited token may not send it (`403`)."},"date_effective":{"type":"string","format":"date-time","description":"Only with `apply_immediately`. The UTC time the change counts from, used for proration. Use `date_effective` from a preview to get the same amounts. It may be at most one hour in the past and not before the current period start."}},"example":{"name":"Priority support","type":"service","quantity":1,"reference_price":10,"reference_currency":"USD"}},"subscription_request":{"type":"object","title":"subscription_request","description":"A new subscription for an existing customer. The customer must have a saved payment method. Billing interval, trial and number of billings come from the subscription plan.","properties":{"subscription_plan_id":{"type":"string","description":"The subscription plan to follow."},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"The three-letter ISO 4217 currency the customer pays in. Must be a currency your account takes. Defaults to your default payment currency."},"items":{"type":"array","minItems":1,"description":"The items to bill for. Product ids must be unique. On a reseller account every item needs a `product_id`.","items":{"$ref":"#/components/schemas/subscription_item_request"}},"shipping_method_id":{"type":"string","description":"The shipping method for physical items. Only allowed when every item has a `product_id`. If you leave it out and an item is physical, the first shipping method for the customer's country is used."},"affiliate_id":{"type":"string","maxLength":75,"description":"An affiliate to credit for the subscription."},"meta":{"description":"Any data you want to store on the subscription, up to 2,048 characters."}},"required":["subscription_plan_id","items"],"example":{"subscription_plan_id":"0093472113202Spzs4AV8C","currency":"USD","items":[{"product_id":"widget-pro.test","quantity":1}]}},"download_list":{"type":"object","title":"download_list","description":"A page of downloads. A cursor-based list.","properties":{"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_after_item":{"type":["string","null"],"description":"The `after_item` value for the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_before_item":{"type":["string","null"],"description":"The `before_item` value for the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page. Present only when you sent `after_item` or `before_item`."},"data":{"type":"array","description":"The items on this page.","items":{"$ref":"#/components/schemas/download"}}},"required":["next_page_url","next_page_after_item","previous_page_url","previous_page_before_item","data"]},"download_request":{"type":"object","title":"download_request","description":"The limits of a download link. Every field is optional. On create, a field you leave out takes the file's default.","properties":{"expires":{"type":["string","null"],"format":"date-time","description":"When the link stops working, as an ISO 8601 date or date and time read in the `timezone` you send. At most 60 days from now. On create, a date in the past is ignored and the file's `expires_in_days` is used."},"expires_in_clicks":{"type":"integer","minimum":0,"description":"How many clicks the link allows in all. On create, 0 or no value uses the file's `expires_in_clicks`."},"clicks":{"type":"integer","minimum":0,"description":"Update only. Sets how many times the link counts as used."},"order_id":{"type":["string","null"],"description":"Create only. The order to tie the download to. It is not checked."},"product_id":{"type":["string","null"],"description":"Create only. The product to tie the download to. It is not checked."}},"example":{"expires":"2026-11-30T23:59:59Z","expires_in_clicks":5}},"event_type":{"type":"string","title":"event_type","description":"The kind of event. See the Webhooks section of this reference for when each one fires and what its `data` holds.","enum":["account:modified","cart:payment_completed","gateway:created","gateway:modified","event_subscription:created","event_subscription:modified","event_subscription:deleted","license_service:low_licenses","invoice:created","invoice:published","invoice:paid","invoice:payment_completed","order:created","order:payment_completed","order:fulfilled","order:licenses_assigned","payment:completed","payment:created_success","payment:created_failure","payment:captured_success","payment:captured_failure","payment:voided","product:created","product:modified","product:deleted","product:low_inventory","refund:created_success","refund:created_failure","refund:deleted","user:created","user:modified","shipment:created","shipment:modified","shipment:deleted","subscription:created","subscription:modified","subscription:cancelled","subscription:cancellation_scheduled","subscription:cancellation_unscheduled","subscription:completed","subscription:converted","subscription_item:added","subscription_item:cancelled","subscription_item:cancellation_scheduled","subscription_item:cancellation_unscheduled","subscription_item:modified","subscription:renewal_success","subscription:renewal_failure"]},"event_subscription":{"type":"object","title":"event_subscription","description":"An endpoint that receives events of one type, by HTTP POST to a URL or by email. Make one event subscription for each event type you want.","properties":{"object":{"type":"string","enum":["event_subscription"],"description":"Always `event_subscription`."},"url":{"type":"string","format":"uri","readOnly":true,"description":"The URL of this event subscription in the API."},"event_subscription_id":{"type":"string","readOnly":true,"description":"The event subscription id."},"date_created":{"type":"string","format":"date-time","readOnly":true,"description":"When the event subscription was created."},"date_modified":{"type":"string","format":"date-time","readOnly":true,"description":"When the event subscription last changed."},"test":{"type":"boolean","readOnly":true,"description":"`true` for a test mode event subscription. It only receives test mode events. Set by the token you create it with."},"active":{"type":"boolean","description":"Whether events are sent to it. On create the default is `false`, so send `active: true` to start receiving events."},"account_id":{"type":"string","readOnly":true,"description":"The account the event subscription belongs to."},"event_type":{"$ref":"#/components/schemas/event_type"},"destination":{"type":["string","null"],"description":"Where to send events: an `https` URL when `method` is `http`, or one email address or a comma-separated list when `method` is `email`. At most 256 characters. A URL must be a public address (not localhost or a private network)."},"format":{"type":["string","null"],"description":"The body format. `json` and `xml` send the whole event. `html` sends only `data`, as a readable table, and suits email.","enum":["json","xml","html",null]},"method":{"type":["string","null"],"description":"How to deliver. `http` is a POST to `destination`; `email` sends an email.","enum":["http","email",null]},"timezone":{"type":["string","null"],"description":"An IANA time zone name for the dates in the event, such as `America/New_York`. When `null`, the account's time zone is used."},"signature_key":{"type":["string","null"],"description":"The key used to sign deliveries in the `X-Comecero-Signature` header. Letters and digits only, at most 64 characters. When `null`, the account's signature key (Settings, Technical) is used."},"expand":{"type":["string","null"],"description":"Comma-separated child objects of `data` to send in full, as with the `expand` query parameter, for example `customer,payments`."},"show":{"type":["string","null"],"description":"Comma-separated fields of `data` to send; all others are left out. You cannot set both `show` and `hide`."},"hide":{"type":["string","null"],"description":"Comma-separated fields of `data` to leave out. You cannot set both `show` and `hide`."},"http_authorization_username":{"type":["string","null"],"description":"A user name sent with HTTP Basic authorization on each delivery. At most 75 characters. Only returned when `method` is `http`."},"http_authorization_password":{"type":["string","null"],"description":"The password for HTTP Basic authorization. At most 75 characters. It is returned as you set it, so keep secret and trusted tokens safe. Only returned when `method` is `http`."},"custom_header_name":{"type":["string","null"],"description":"The name of an extra header sent with each delivery. At most 75 characters. Sent only when `custom_header_value` is set too."},"custom_header_value":{"type":["string","null"],"description":"The value of the extra header. At most 256 characters."},"environment_variables":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Name and value pairs copied into `environment_variables` of every event sent to this subscription."},"comments":{"type":["string","null"],"description":"Your own notes. At most 256 characters."},"formatted":{"type":"object","readOnly":true,"description":"Dates as display text. Only returned with `formatted=true`.","properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"}}}},"example":{"object":"event_subscription","url":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","event_subscription_id":"1102610913420ES4f9QmLp","date_created":"2026-11-07T14:20:03Z","date_modified":"2026-11-07T14:20:03Z","test":true,"active":true,"account_id":"AB1234","event_type":"order:created","destination":"https://example.com/webhooks/comecero","format":"json","method":"http","timezone":null,"signature_key":null,"expand":"customer","show":null,"hide":null,"http_authorization_username":null,"http_authorization_password":null,"custom_header_name":null,"custom_header_value":null,"environment_variables":{"store":"main"},"comments":"Order sync"}},"event_subscription_list":{"title":"event_subscription_list","description":"An offset-based page of event subscriptions.","allOf":[{"$ref":"#/components/schemas/list_offset"},{"type":"object","properties":{"data":{"type":"array","description":"The event subscriptions on this page.","items":{"$ref":"#/components/schemas/event_subscription"}}}}]},"event_subscription_request":{"type":"object","title":"event_subscription_request","description":"The fields you can set on an event subscription. On create, `event_type`, `method`, `format` and `destination` are required. On update, send only the fields to change.","properties":{"event_type":{"$ref":"#/components/schemas/event_type"},"active":{"type":"boolean","default":false,"description":"Whether events are sent. On create the default is `false`: send `true` to start receiving events."},"method":{"type":"string","enum":["http","email"],"description":"`http` posts to a URL; `email` sends an email."},"format":{"type":"string","enum":["json","xml","html"],"description":"The body format. `html` sends only `data`, as a readable table, and suits email."},"destination":{"type":"string","maxLength":256,"description":"A URL when `method` is `http` (it must be a public address, not localhost or a private network), or an email address or comma-separated list of up to 6 addresses when `method` is `email`."},"timezone":{"type":["string","null"],"description":"An IANA time zone name for the dates in each event."},"signature_key":{"type":["string","null"],"maxLength":64,"pattern":"^[A-Za-z0-9]*$","description":"Your own signing key, letters and digits only. Leave it out to sign with the account's signature key."},"expand":{"type":["string","null"],"description":"Comma-separated child objects of `data` to send in full."},"show":{"type":["string","null"],"description":"Comma-separated fields of `data` to send. Not with `hide`."},"hide":{"type":["string","null"],"description":"Comma-separated fields of `data` to leave out. Not with `show`."},"http_authorization_username":{"type":["string","null"],"maxLength":75,"description":"User name for HTTP Basic authorization on each delivery."},"http_authorization_password":{"type":["string","null"],"maxLength":75,"description":"Password for HTTP Basic authorization on each delivery."},"custom_header_name":{"type":["string","null"],"maxLength":75,"description":"The name of an extra header to send with each delivery."},"custom_header_value":{"type":["string","null"],"maxLength":256,"description":"The value of the extra header."},"environment_variables":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Name and value pairs to pass to your endpoint in each event. On update this replaces the whole set."},"comments":{"type":["string","null"],"maxLength":256,"description":"Your own notes."}},"example":{"event_type":"order:created","active":true,"method":"http","format":"json","destination":"https://example.com/webhooks/comecero","expand":"customer","environment_variables":{"store":"main"},"comments":"Order sync"}},"event_subscription_test_result":{"type":"object","title":"event_subscription_test_result","description":"The result of sending one test event.","properties":{"success":{"type":"boolean","description":"`true` when your server answered 2xx. For an email subscription this is `true` whenever the email was handed to the mail service, even if sending failed later."},"error":{"type":["string","null"],"description":"Why the delivery failed, such as the status code and the start of your server's answer. `null` on success."},"event_id":{"type":"string","description":"The id the test event was sent with. Test events are not saved, so you cannot get it from `/events`."},"event_type":{"$ref":"#/components/schemas/event_type"}},"example":{"success":true,"error":null,"event_id":"1102611204410EVn3Rk8Wd","event_type":"order:created"}},"event":{"type":"object","title":"event","description":"One delivery of one event to one event subscription. When something happens (an order is created, a payment completes), Comecero makes one event for each active event subscription to that event type, each with its own `event_id` and the same `fingerprint`. This is also the body Comecero POSTs to your webhook URL.","properties":{"object":{"type":"string","enum":["event"],"description":"Always `event`."},"url":{"type":"string","format":"uri","readOnly":true,"description":"The URL of this event in the API."},"event_id":{"type":"string","readOnly":true,"description":"The id of this delivery. It is different for each event subscription, and stays the same when the delivery is retried, so use it to ignore a delivery you already handled."},"test":{"type":"boolean","readOnly":true,"description":"`true` for a test mode event."},"account_id":{"type":"string","readOnly":true,"description":"The account the event belongs to."},"type":{"$ref":"#/components/schemas/event_type"},"event_subscription":{"description":"The event subscription this delivery is for: its URL, or the full object when you send `expand=event_subscription`. Left out when the token may not read event subscriptions.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/event_subscription"}]},"fingerprint":{"type":"string","readOnly":true,"description":"The id of the thing that happened. Every event subscription that receives the same occurrence gets the same `fingerprint`."},"status":{"type":"string","readOnly":true,"description":"Where delivery stands. `queued`: made, not sent yet. `delivered`: your server answered 2xx (or the email was sent). `retry`: the last attempt failed and another is planned. `failed`: no more attempts will be made.","enum":["queued","delivered","retry","failed"]},"date_created":{"type":"string","format":"date-time","readOnly":true,"description":"When the event happened. Dates in an event use the event subscription's `timezone`, or the account's time zone when it has none."},"date_modified":{"type":"string","format":"date-time","readOnly":true,"description":"When the event last changed, for example at its last delivery attempt."},"environment_variables":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"The name and value pairs set on the event subscription when the event was made, passed through so your endpoint can read its own settings."},"data":{"type":"object","additionalProperties":true,"description":"The object the event is about, shaped like a GET of that object (an order for `order:created`, a payment for `payment:completed`). The event subscription's `expand`, `show` and `hide` apply to it. It is the object as it was when the event was made, not as it is now."},"retry_count":{"type":"integer","readOnly":true,"description":"How many automatic retries have been made. Only returned with `debug=true`."},"date_last_delivery_attempt":{"type":["string","null"],"format":"date-time","readOnly":true,"description":"When the last delivery attempt was made. Only returned with `debug=true`."},"date_next_delivery_attempt":{"type":["string","null"],"format":"date-time","readOnly":true,"description":"When the next automatic attempt is planned. Only returned with `debug=true`, and only when an attempt is planned."},"debug":{"type":["string","null"],"readOnly":true,"description":"Why the last attempt failed, such as the status code and the first 500 characters your server answered. Only returned with `debug=true`."},"formatted":{"type":"object","readOnly":true,"description":"Dates as display text. Only returned with `formatted=true`.","properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"},"date_delivered":{"type":["string","null"]},"date_last_delivery_attempt":{"type":["string","null"]},"date_next_delivery_attempt":{"type":["string","null"]}}}},"example":{"object":"event","url":"https://api.comecero.com/api/v1/events/1102611073847EVt7Kq2Za","event_id":"1102611073847EVt7Kq2Za","test":true,"account_id":"AB1234","type":"order:created","event_subscription":"https://api.comecero.com/api/v1/event_subscriptions/1102610913420ES4f9QmLp","fingerprint":"k2P9wQ7xR4vT1nY8","status":"delivered","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:11Z","environment_variables":{"store":"main"},"data":{"object":"order","url":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954","order_id":"7393-GMRFY-954","test":true,"currency":"USD","total":99.95,"customer":"https://api.comecero.com/api/v1/customers/1102611073801CUa8Hn2Lq"}}},"event_list":{"title":"event_list","description":"A cursor-based page of events.","allOf":[{"$ref":"#/components/schemas/list_cursor"},{"type":"object","properties":{"data":{"type":"array","description":"The events on this page.","items":{"$ref":"#/components/schemas/event"}}}}]},"fee":{"type":"object","title":"fee","description":"A fee Comecero charges your account, for a transaction (a payment, refund, decline or chargeback) or for the service (a monthly or annual plan). Fees are made by Comecero; you cannot create them. Fees with the same `accounting_id` are billed together.","properties":{"object":{"type":"string","enum":["fee"],"description":"Always `fee`."},"url":{"type":"string","format":"uri","readOnly":true,"description":"The URL of this fee in the API."},"fee_id":{"type":"string","readOnly":true,"description":"The fee id."},"date_created":{"type":"string","format":"date-time","readOnly":true,"description":"When the fee was charged."},"date_modified":{"type":"string","format":"date-time","readOnly":true,"description":"When the fee last changed."},"test":{"type":"boolean","readOnly":true,"description":"`true` for a test mode fee. Test fees are never billed."},"account_id":{"type":"string","readOnly":true,"description":"The account charged."},"fixed_amount":{"type":"number","description":"The fixed part of the fee, in `currency`."},"percentage":{"type":"number","description":"The percentage rate, for example `2.9` for 2.9%."},"percentage_amount":{"type":"number","description":"The percentage part of the fee, in `currency`."},"total":{"type":"number","description":"The whole fee, `fixed_amount` plus `percentage_amount`, in `currency`."},"currency":{"type":"string","description":"The ISO 4217 currency of the amounts."},"type":{"type":"string","description":"What the fee is for. Transaction fees: `payment_completed`, `refund_completed`, `auth`, `zero_auth`, `capture`, `void`, `decline`, `chargeback`, plus contract fees `fx_conversion`, `international_card` and `payout`. Service fees: `platform_monthly`, `platform_annual`, `support_annual`, `miscellaneous`.","enum":["payment_completed","refund_completed","auth","zero_auth","capture","void","decline","chargeback","fx_conversion","international_card","payout","platform_monthly","platform_annual","support_annual","miscellaneous"]},"category":{"type":"string","description":"`transaction` for a fee on a payment or refund, `operation` for a service fee.","enum":["transaction","operation"]},"collected":{"type":"boolean","description":"`true` when the fee was already taken from the money by Comecero Express Payments. It is a record only and is not on any bill."},"description":{"type":["string","null"],"description":"What the fee is, in words."},"transaction_type":{"type":["string","null"],"description":"`payment` or `refund` when the fee is on a transaction, otherwise `null`.","enum":["payment","refund",null]},"created_by":{"type":["string","null"],"description":"Who made the fee by hand. Only returned to Comecero staff tokens."},"transaction":{"description":"The payment or refund the fee is on: its URL, or the full object with `expand=transaction`. Left out when the fee is on no transaction or the token may not read it.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/payment"},{"$ref":"#/components/schemas/refund"}]},"contract":{"type":["string","null"],"description":"The URL of the contract whose prices set this fee, or `null` when no contract was in effect. Left out when the token may not read contracts."},"accounting_id":{"type":["string","null"],"description":"The billing period the fee is billed in, for example `C-AB1234R261130USD` (account, `R` for receivable, period end date as YYMMDD, currency). `null` on a collected fee."},"formatted":{"type":"object","readOnly":true,"description":"Amounts and dates as display text. Only returned with `formatted=true`.","properties":{"fixed_amount":{"type":"string"},"percentage":{"type":"string"},"percentage_amount":{"type":"string"},"total":{"type":"string"},"date_created":{"type":"string"},"date_modified":{"type":"string"}}}},"example":{"object":"fee","url":"https://api.comecero.com/api/v1/fees/1102611073850FEp6Vb2Qs","fee_id":"1102611073850FEp6Vb2Qs","date_created":"2026-11-07T14:32:10Z","date_modified":"2026-11-07T14:32:10Z","test":true,"account_id":"AB1234","fixed_amount":0.3,"percentage":2.9,"percentage_amount":2.9,"total":3.2,"currency":"USD","type":"payment_completed","category":"transaction","collected":false,"description":"Payment completed","transaction_type":"payment","transaction":"https://api.comecero.com/api/v1/payments/1102611073840PAz3Tq9Xc","contract":null,"accounting_id":"C-AB1234R261130USD"}},"fee_list":{"title":"fee_list","description":"A cursor-based page of fees.","allOf":[{"$ref":"#/components/schemas/list_cursor"},{"type":"object","properties":{"data":{"type":"array","description":"The fees on this page.","items":{"$ref":"#/components/schemas/fee"}}}}]},"file_list":{"type":"object","title":"file_list","description":"A page of files. An offset-based list.","properties":{"total_items":{"type":"integer","description":"The number of items that match, across all pages."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The number of this page."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The items on this page.","items":{"$ref":"#/components/schemas/file"}}},"required":["total_items","total_pages","current_page","next_page_url","next_page_offset","previous_page_url","previous_page_offset","current_page_url","data"]},"file_request":{"type":"object","title":"file_request","description":"A `multipart/form-data` body. Send the file itself in a part named `file`, or give `file_url` and Comecero fetches it. Not both, and one file per request. A direct upload may be at most 200 MB (200,000,000 bytes); for a bigger file use `file_url`. A file fetched from `file_url` may be up to 500 MB on a live account and 200 MB on a test account. All your files together may use up to 5 GB live and 500 MB test. Your account may have other limits; going over one returns `422` with the code `account_limit_exceeded`.","properties":{"file":{"type":"string","format":"binary","description":"The file to upload. Its file name must be 50 characters or less. Required on create unless you send `file_url`. On update, a new file replaces the old one."},"file_url":{"type":"string","format":"uri","description":"A public URL Comecero downloads the file from. Not a private or local address. The file name is taken from the URL."},"http_authorization_username":{"type":"string","description":"A user name for HTTP basic authentication on `file_url`, if needed."},"http_authorization_password":{"type":"string","description":"The password for HTTP basic authentication on `file_url`."},"name":{"type":"string","maxLength":75,"description":"Your name for the file. The file name is used when you leave it out."},"description":{"type":"string","maxLength":256,"description":"Your notes about the file."},"version":{"type":"string","maxLength":10,"description":"A version label, for example `2.1`."},"expires_in_days":{"type":"integer","minimum":0,"maximum":720,"description":"How many days a new download link works, up to 720. The default is 7. On create it is read only when you also send `expires_in_clicks`, so send both."},"expires_in_clicks":{"type":"integer","minimum":0,"description":"How many clicks a new download link allows. The default is 10."}}},"fx_amount":{"type":"object","title":"fx_amount","description":"An amount converted to another currency.","readOnly":true,"properties":{"amount":{"type":"number","description":"The converted amount, in `currency`."},"currency":{"type":"string","description":"The ISO 4217 code of the currency the amount was converted to."},"formatted":{"type":"object","description":"Only present when you send `formatted=true`.","properties":{"amount":{"type":"string","description":"The amount as display text, such as `€18.40`."}}}},"example":{"amount":18.4,"currency":"EUR"}},"fx_price":{"type":"object","title":"fx_price","description":"A product's price in one currency.","readOnly":true,"properties":{"price":{"type":"number","description":"The price of one unit, in `currency`, at the quantity asked for (so a volume price applies). It is the price you set in that currency, or your default price converted at today's rate."},"currency":{"type":"string","description":"The ISO 4217 code of the currency."},"formatted":{"type":"object","description":"Only present when you send `formatted=true`.","properties":{"amount":{"type":"string","description":"The price as display text, such as `€45.95`."}}}},"example":{"price":45.95,"currency":"EUR"}},"gateway_list":{"title":"gateway_list","description":"An offset-based list of gateways.","allOf":[{"$ref":"#/components/schemas/list_offset"},{"type":"object","properties":{"data":{"type":"array","description":"The gateways on this page.","items":{"$ref":"#/components/schemas/gateway"}}}}]},"gateway_request":{"type":"object","title":"gateway_request","description":"A new gateway.","required":["provider_id","payment_method_types","currencies"],"properties":{"provider_id":{"type":"string","description":"The payment provider, from `GET /gateways/options`. It cannot be changed later. Some providers are set up only by Comecero and cannot be added here (`400`)."},"payment_method_types":{"type":"array","description":"The kinds of payment the gateway takes. At least one, and the provider must support them. They cannot be changed later.","minItems":1,"items":{"type":"string","enum":["credit_card","paypal","amazon_pay","apple_pay","ach","wallet"]}},"currencies":{"type":"array","description":"The ISO 4217 currency codes the gateway takes. At least one.","items":{"type":"string"}},"card_types":{"type":"array","description":"The card brands the gateway takes. Required, with at least one, when `payment_method_types` has `credit_card`.","items":{"type":"string"}},"fields":{"type":"object","description":"The provider settings, keyed by each field's `name` from `GET /gateways/options`. Required when the provider has fields. Comecero keeps them encrypted and may check them with the provider (`400` if they do not work).","additionalProperties":true},"active":{"type":"boolean","description":"True to take payments on the gateway now. The default is `false`.","default":false},"weight":{"type":"integer","description":"How often this gateway is picked compared to others. The default is 1.","minimum":0,"default":1},"comments":{"type":"string","description":"Your own notes about the gateway.","maxLength":1024}},"example":{"provider_id":"test","payment_method_types":["credit_card"],"currencies":["USD","EUR"],"card_types":["visa","mastercard","american_express"],"active":true}},"gateway_field":{"type":"object","title":"gateway_field","description":"One setting a payment provider needs, such as an API key or a merchant ID.","readOnly":true,"properties":{"name":{"type":"string","description":"The key to use for this setting in the gateway's `fields`."},"type":{"type":"string","description":"The kind of value. `text` is a long string. `array` is a list of strings.","enum":["string","text","integer","decimal","boolean","color","image","array","base64"]},"label":{"type":"string","description":"A short name to show next to the input."},"description":{"type":["string","null"],"description":"Help text for the setting."},"section":{"type":["string","null"],"description":"A heading to group settings under."},"required":{"type":"boolean","description":"True when the gateway cannot be saved without it."},"default_value":{"description":"The value used when you send none."},"min_value":{"type":["number","null"],"description":"The lowest allowed value, for numbers."},"max_value":{"type":["number","null"],"description":"The highest allowed value, for numbers."},"min_length":{"type":["integer","null"],"description":"The shortest allowed value, for strings."},"max_length":{"type":["integer","null"],"description":"The longest allowed value, for strings."},"options":{"type":["array","null"],"description":"When set, the value must be one of these.","items":{"type":"object","properties":{"display":{"type":"string","description":"The text to show."},"value":{"description":"The value to send."}}}},"required_if":{"type":["object","null"],"description":"The setting is required when another setting has one of the listed values. Each key is the other setting's `name`.","additionalProperties":{"type":"array","items":{"type":"string"}}}},"example":{"name":"api_key","type":"string","label":"API key","description":"The secret API key from your provider's dashboard.","section":null,"required":true,"default_value":null,"min_value":null,"max_value":null,"min_length":null,"max_length":200,"options":null,"required_if":null}},"gateway_options":{"type":"object","title":"gateway_options","description":"What you can choose from when you add a gateway.","readOnly":true,"properties":{"account_id":{"type":"string","description":"The account of the token you called with."},"test":{"type":"boolean","description":"True when you called with a test token. The providers listed are for that mode."},"gateway_configs":{"type":"array","description":"The providers you can add, each with the payment types it takes and the settings it needs. In test mode the test provider comes first.","items":{"type":"object","properties":{"provider_id":{"type":"string","description":"The value to send as `provider_id`."},"name":{"type":"string","description":"The provider's name."},"test":{"type":"boolean","description":"True for the test mode version of the provider."},"payment_method_types":{"type":"array","description":"The payment types the provider takes.","items":{"type":"string"}},"fields":{"type":"array","description":"The settings to send in `fields`.","items":{"$ref":"#/components/schemas/gateway_field"}}}}},"currencies":{"type":"array","description":"Every currency a gateway may take.","items":{"type":"object","properties":{"code":{"type":"string","description":"The ISO 4217 currency code."},"name":{"type":"string","description":"The currency's name."}}}},"card_types":{"type":"array","description":"Every card brand you can send in `card_types`.","items":{"type":"string"}}},"example":{"account_id":"AB1234","test":true,"gateway_configs":[{"provider_id":"test","name":"Test Gateway","test":true,"payment_method_types":["credit_card"],"fields":[]}],"currencies":[{"code":"EUR","name":"Euro"},{"code":"USD","name":"US Dollar"}],"card_types":["american_express","discover","mastercard","visa"]}},"gateway_update_request":{"type":"object","title":"gateway_update_request","description":"The fields to change. Fields you leave out keep their value. You cannot change `provider_id` or `payment_method_types`: add a new gateway instead (`400`).","properties":{"currencies":{"type":"array","description":"The ISO 4217 currency codes the gateway takes. Replaces the old list.","items":{"type":"string"}},"card_types":{"type":"array","description":"The card brands the gateway takes. Replaces the old list. A card gateway must keep at least one (`400`).","items":{"type":"string"}},"fields":{"type":"object","description":"New provider settings, keyed by each field's `name`. Replaces the saved settings.","additionalProperties":true},"active":{"type":"boolean","description":"True to take payments on the gateway, false to stop."},"weight":{"type":"integer","description":"How often this gateway is picked compared to others.","minimum":0},"comments":{"type":["string","null"],"description":"Your own notes about the gateway.","maxLength":1024}},"example":{"active":false,"comments":"Paused while we change providers."}},"image_list":{"type":"object","title":"image_list","description":"A page of images. An offset-based list.","properties":{"total_items":{"type":"integer","description":"The number of items that match, across all pages."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The number of this page."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The items on this page.","items":{"$ref":"#/components/schemas/image"}}},"required":["total_items","total_pages","current_page","next_page_url","next_page_offset","previous_page_url","previous_page_offset","current_page_url","data"]},"image_request":{"type":"object","title":"image_request","description":"A `multipart/form-data` body with one image in a part named `file`. The image must be a `.png`, `.jpg`, `.jpeg`, `.gif` or `.ico` file of at most 10 MB (10,000,000 bytes), with a file name of 50 characters or less.","properties":{"file":{"type":"string","format":"binary","description":"The image to upload."}},"required":["file"]},"invoice_list":{"type":"object","title":"invoice_list","description":"A cursor-based list of invoices.","x-response":true,"properties":{"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_after_item":{"type":["string","null"],"description":"The `after_item` value for the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_before_item":{"type":["string","null"],"description":"The `before_item` value for the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page. Only present when you asked for a page with `after_item` or `before_item`."},"data":{"type":"array","description":"The invoices on this page.","items":{"$ref":"#/components/schemas/invoice"}}}},"invoice_item_request":{"type":"object","title":"invoice_item_request","description":"An item to add to an invoice, or the fields to change on one. Send a `product_id` to bill a product from your catalog. Leave it out to add a custom item, which then needs `name`, `type` and `reference_price`. Custom items are not allowed on accounts where Comecero is the seller (reseller model). Limited tokens may not add or change items.","x-request":true,"properties":{"product_id":{"type":"string","description":"The product to bill. The product must be active. The item takes its name, type, tax code and subscription plan from the product, and its `item_id` is the `product_id`. A bundle product adds one item for the bundle and one zero-priced item per product in it."},"item_id":{"type":"string","description":"For a custom item, your own id. Letters, numbers, underscores, dashes and periods only. If you leave it out, Comecero assigns the next number. On update it must match the `item_id` in the URL."},"name":{"type":"string","maxLength":75,"description":"The item name. Required for a custom item. Ignored for a product."},"type":{"type":"string","enum":["digital","physical","service"],"description":"The item type. Required for a custom item. Physical items need a shipping address and may add shipping. Ignored for a product."},"quantity":{"type":"number","minimum":0,"description":"The quantity. Defaults to 1. Decimals are allowed, up to 8 decimal places."},"reference_price":{"type":"number","minimum":0,"description":"The unit price. Required for a custom item (0 is allowed). For a product, it replaces the product's price. Comecero converts it from `reference_currency` to the invoice currency."},"reference_currency":{"type":"string","description":"The currency of `reference_price`, a three-letter ISO 4217 code. Defaults to the invoice currency."},"tax_code":{"type":"string","description":"The tax code to work out tax with. Custom items only."},"subscription_plan_id":{"type":"string","description":"Makes a custom item a subscription. Paying the invoice starts the subscription on this plan."},"meta":{"type":"object","additionalProperties":true,"description":"Your own data for this item, up to 2,048 characters as JSON."}},"example":{"name":"Website setup, 10 hours","type":"service","quantity":10,"reference_price":95,"reference_currency":"USD"}},"invoice_request":{"type":"object","title":"invoice_request","description":"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.","x-request":true,"properties":{"invoice_id":{"type":"string","maxLength":30,"description":"Your 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."},"currency":{"type":"string","description":"The 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":{"type":["string","null"],"description":"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":{"type":"boolean","default":true,"description":"Send `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."},"suppress_customer_notification":{"type":"boolean","default":false,"description":"Send `true` with `draft: false` to publish without emailing the customer. Use it when you send the link yourself (see Create a payment link)."},"autopay":{"type":"boolean","description":"Send `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":{"type":["string","null"],"description":"The id of an existing customer. Send either this or `customer`, not both. After an invoice is published you cannot change its customer."},"customer":{"$ref":"#/components/schemas/customer_request","description":"A new customer, or changes to an existing one (include its `customer_id`). Send either this or `customer_id`, not both."},"items":{"type":"array","description":"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.","items":{"$ref":"#/components/schemas/invoice_item_request"}},"promotion_code":{"type":["string","null"],"description":"A coupon code to apply. It must be valid for the customer."},"shipping_method_id":{"type":["string","null"],"description":"The shipping method for physical items. It must exist and ship to the customer's country."},"referrer":{"type":["string","null"],"description":"Where the sale came from, for your reports."},"affiliate_id":{"type":["string","null"],"description":"The affiliate to credit with the sale."},"meta":{"type":["object","null"],"additionalProperties":true,"description":"Your own data, up to 2,048 characters as JSON."}},"example":{"currency":"USD","date_due":"2026-11-30","draft":false,"customer":{"name":"John Doe","email":"john@example.com","billing_address":{"name":"John Doe","address_1":"100 Main Street","city":"Springfield","state_prov":"IL","postal_code":"62701","country":"US"}},"items":[{"name":"Website setup, 10 hours","type":"service","quantity":10,"reference_price":95}],"meta":{"project":"Q4-site"}}},"invoice_item_list":{"type":"object","title":"invoice_item_list","description":"An offset-based list of the items on an invoice.","x-response":true,"properties":{"total_items":{"type":"integer","description":"The number of items in the whole list."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The page number of this page, starting at 1."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The items on this page.","items":{"$ref":"#/components/schemas/invoice_item"}}},"required":["total_items","total_pages","current_page","next_page_url","next_page_offset","previous_page_url","previous_page_offset","current_page_url","data"]},"invoice_link":{"type":"object","title":"invoice_link","description":"A payment link for an invoice.","x-limited":true,"x-response":true,"properties":{"link_url":{"type":"string","format":"uri","description":"The link the customer opens to see and pay the invoice. It is built on the host of the app installed for invoice payments, or else the first app host in your technical settings. It expires after 30 days."}},"required":["link_url"],"example":{"link_url":"https://shop.example.com/link?id=in-7f3c2a91b04e4d6c9a1e"}},"notification_type":{"type":"string","title":"notification_type","description":"The kind of customer email. `order:confirmation` (receipt for a new order), `payment:confirmation`, `refund:confirmation`, `shipment:confirmation`, `cart:link` and `invoice:link` (a link to pay), `customer:link` (a link to the customer's account), `subscription:prebill_notification` (a renewal is coming), `subscription:cancel_confirmation` and `subscription:payment_failure` (a renewal payment failed).","enum":["order:confirmation","shipment:confirmation","payment:confirmation","refund:confirmation","cart:link","invoice:link","customer:link","subscription:prebill_notification","subscription:cancel_confirmation","subscription:payment_failure"]},"template":{"type":"object","title":"template","description":"A Handlebars template that builds the body of an email (or a PDF). Use one on a notification subscription, wrap it in another with `wrapper_template`, or render it yourself with the build endpoint.","properties":{"object":{"type":"string","enum":["template"],"description":"Always `template`."},"url":{"type":"string","format":"uri","readOnly":true,"description":"The URL of this template in the API."},"template_id":{"type":"string","readOnly":true,"description":"The template id."},"date_created":{"type":"string","format":"date-time","readOnly":true,"description":"When the template was created."},"date_modified":{"type":"string","format":"date-time","readOnly":true,"description":"When the template last changed."},"test":{"type":"boolean","readOnly":true,"description":"`true` for a test mode template."},"account_id":{"type":"string","readOnly":true,"description":"The account it belongs to."},"expand":{"type":["string","null"],"description":"Comma-separated child objects of the data to expand before the template is filled."},"show":{"type":["string","null"],"description":"Comma-separated fields of the data to keep."},"hide":{"type":["string","null"],"description":"Comma-separated fields of the data to leave out."},"wrapper_template":{"description":"The template this one is placed inside (a shared header and footer, for example): its URL, the full object with `expand=wrapper_template`, or `null`.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/template"},{"type":"null"}]},"comments":{"type":["string","null"],"description":"Your own notes, at most 256 characters."},"template_type":{"type":["string","null"],"description":"`email` (or `null`, the same) or `pdf`. A PDF template cannot be changed back.","enum":["email","pdf",null]},"pdf_type":{"type":["string","null"],"description":"For a PDF template, what it renders, such as `invoice` or `order`."},"page_format":{"type":["string","null"],"description":"For a PDF template, the page size, such as `A4` or `Letter`."},"orientation":{"type":["string","null"],"description":"For a PDF template, `portrait` or `landscape`."},"margin_top":{"type":["integer","null"],"description":"For a PDF template, the top margin."},"margin_bottom":{"type":["integer","null"],"description":"For a PDF template, the bottom margin."},"margin_left":{"type":["integer","null"],"description":"For a PDF template, the left margin."},"margin_right":{"type":["integer","null"],"description":"For a PDF template, the right margin."},"body":{"type":["string","null"],"description":"The Handlebars source, at most 128 kB. In a list this holds a short note instead; get the template by id to read the body."},"formatted":{"type":"object","readOnly":true,"description":"Dates as display text. Only returned with `formatted=true`.","properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"}}}},"example":{"object":"template","url":"https://api.comecero.com/api/v1/templates/1102500900112TEm5Jc3Rw","template_id":"1102500900112TEm5Jc3Rw","date_created":"2026-10-01T09:05:00Z","date_modified":"2026-10-01T09:05:00Z","test":true,"account_id":"AB1234","expand":null,"show":null,"hide":null,"wrapper_template":null,"comments":"Download email","template_type":null,"pdf_type":null,"page_format":null,"orientation":null,"margin_top":null,"margin_bottom":null,"margin_left":null,"margin_right":null,"body":"<p>Hi {{customer.first_name}}, your download is ready: {{download_url}}</p>"}},"notification_subscription":{"type":"object","title":"notification_subscription","description":"Turns on one kind of customer email and sets who it comes from, its subject and its template. Only one subscription per type may be active.","properties":{"object":{"type":"string","enum":["notification_subscription"],"description":"Always `notification_subscription`."},"url":{"type":"string","format":"uri","readOnly":true,"description":"The URL of this notification subscription in the API."},"notification_subscription_id":{"type":"string","readOnly":true,"description":"The notification subscription id."},"date_created":{"type":"string","format":"date-time","readOnly":true,"description":"When it was created."},"date_modified":{"type":"string","format":"date-time","readOnly":true,"description":"When it last changed."},"test":{"type":"boolean","readOnly":true,"description":"`true` for a test mode subscription. It only sends test mode emails."},"type":{"$ref":"#/components/schemas/notification_type"},"active":{"type":"boolean","description":"Whether the email is sent. On create the default is `false`."},"account_id":{"type":"string","readOnly":true,"description":"The account it belongs to."},"method":{"type":"string","enum":["email"],"description":"How to send. Only `email`."},"from":{"type":["string","null"],"description":"The sender address, one of your verified notification addresses. When `null`, emails go from `notification@comecero.com`."},"from_name":{"type":["string","null"],"description":"The sender name, at most 25 characters. When `null`, your public company name."},"reply_to":{"type":["string","null"],"description":"The reply-to address. When `null` and emails go from Comecero's address, your support email is used."},"bcc":{"type":["string","null"],"description":"Up to 4 addresses, comma-separated, that get a blind copy of every email."},"subject":{"type":["string","null"],"description":"The subject line, at most 75 characters. It may hold placeholders such as `{{order.order_id}}`. When `null`, the template's default subject is used, then a built-in one."},"template":{"description":"Your template for the body: its URL, the full object with `expand=template`, or `null` to use Comecero's built-in template (in the customer's language where one exists). Left out when the token may not read templates.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/template"},{"type":"null"}]},"comments":{"type":["string","null"],"description":"Your own notes, at most 256 characters."},"formatted":{"type":"object","readOnly":true,"description":"Dates as display text. Only returned with `formatted=true`.","properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"}}}},"example":{"object":"notification_subscription","url":"https://api.comecero.com/api/v1/notification_subscriptions/1102500112233NSd4Kw9Tz","notification_subscription_id":"1102500112233NSd4Kw9Tz","date_created":"2026-10-01T09:00:00Z","date_modified":"2026-10-01T09:00:00Z","test":true,"type":"shipment:confirmation","active":true,"account_id":"AB1234","method":"email","from":null,"from_name":"Example Shop","reply_to":"support@example.com","bcc":null,"subject":"Your order {{order.order_id}} has shipped","template":null,"comments":null}},"notification":{"type":"object","title":"notification","description":"One email Comecero sent, or will send, to a customer because a notification subscription matched. Notifications are kept for 120 days (15 days in test mode).","properties":{"object":{"type":"string","enum":["notification"],"description":"Always `notification`."},"url":{"type":["string","null"],"format":"uri","readOnly":true,"description":"The URL of this notification in the API. `null` on one sent with `POST /notifications`."},"notification_id":{"type":["string","null"],"readOnly":true,"description":"The notification id. `null` on one sent with `POST /notifications`, which is not saved."},"test":{"type":"boolean","readOnly":true,"description":"`true` for a test mode notification."},"account_id":{"type":"string","readOnly":true,"description":"The account that sent it."},"type":{"description":"The kind of email. `null` on one sent with `POST /notifications`.","oneOf":[{"$ref":"#/components/schemas/notification_type"},{"type":"null"}]},"method":{"type":"string","enum":["email"],"description":"How it was sent. Only `email` today."},"from":{"type":["string","null"],"description":"The sender address. `notification@comecero.com` unless the subscription names one of your verified addresses."},"from_name":{"type":["string","null"],"description":"The sender name. Defaults to your public company name."},"reply_to":{"type":["string","null"],"description":"The reply-to address. When the subscription sets none and the email goes from Comecero's address, your support email is used."},"bcc":{"type":["string","null"],"description":"Addresses that got a blind copy, comma-separated."},"destination":{"type":["string","null"],"description":"Who it went to: the customer's email, plus the billing address email when that is different (separated by `;`)."},"subject":{"type":["string","null"],"description":"The subject line, after placeholders were filled in."},"notification_subscription":{"description":"The notification subscription that sent it: its URL, or the full object with `expand=notification_subscription`. Left out when the token may not read notification subscriptions.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/notification_subscription"},{"type":"null"}]},"customer":{"description":"The customer it was sent to: a URL, or the full object with `expand=customer`. Left out when the token may not read customers.","oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/customer"},{"type":"null"}]},"status":{"type":"string","readOnly":true,"description":"`queued`: not sent yet (an order confirmation waits here until every license key in the order is assigned). `delivered`: sent. `retry`: the last attempt failed and another is planned. `failed`: no more attempts.","enum":["queued","delivered","retry","failed"]},"date_created":{"type":"string","format":"date-time","readOnly":true,"description":"When the notification was made."},"date_modified":{"type":"string","format":"date-time","readOnly":true,"description":"When it last changed, for example at its last send attempt."},"data":{"type":["object","null"],"additionalProperties":true,"description":"The data the template was filled with: the order, payment, customer and account the email is about."},"body":{"type":["string","null"],"description":"The HTML that was sent. In a list this holds a short note instead; get the notification by id to read the body."},"retry_count":{"type":"integer","readOnly":true,"description":"How many automatic retries were made. Only with `debug=true` on a single notification."},"date_last_delivery_attempt":{"type":["string","null"],"format":"date-time","readOnly":true,"description":"When it was last tried. Only with `debug=true` on a single notification."},"date_next_delivery_attempt":{"type":["string","null"],"format":"date-time","readOnly":true,"description":"When the next attempt is planned. Only with `debug=true` on a single notification, and only when one is planned."},"last_failure_meta":{"type":["string","null"],"readOnly":true,"description":"Why the last attempt failed. Only with `debug=true` on a single notification."},"formatted":{"type":"object","readOnly":true,"description":"Dates as display text. Only returned with `formatted=true`.","properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"},"date_delivered":{"type":["string","null"]},"date_last_delivery_attempt":{"type":["string","null"]},"date_next_delivery_attempt":{"type":["string","null"]}}}},"example":{"object":"notification","url":"https://api.comecero.com/api/v1/notifications/1102611073905NOq2Lx7Pv","notification_id":"1102611073905NOq2Lx7Pv","test":true,"account_id":"AB1234","type":"order:confirmation","method":"email","from":"notification@comecero.com","from_name":"Example Shop","reply_to":"support@example.com","bcc":null,"destination":"john@example.com","subject":"Your Order Confirmation","notification_subscription":"https://api.comecero.com/api/v1/notification_subscriptions/1102500112233NSd4Kw9Tz","customer":"https://api.comecero.com/api/v1/customers/1102611073801CUa8Hn2Lq","status":"delivered","date_created":"2026-11-07T14:32:12Z","date_modified":"2026-11-07T14:32:14Z","data":{"order":{"order_id":"7393-GMRFY-954","total":99.95,"currency":"USD"}},"body":"<html><body><h1>Thanks for your order</h1></body></html>"}},"invoice_notification_list":{"type":"object","title":"invoice_notification_list","description":"An offset-based list of the notifications (emails) sent about an invoice.","x-response":true,"properties":{"total_items":{"type":"integer","description":"The number of items in the whole list."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The page number of this page, starting at 1."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The items on this page.","items":{"$ref":"#/components/schemas/notification"}}}},"invoice_payment_list":{"type":"object","title":"invoice_payment_list","description":"An offset-based list of the payments made against an invoice.","x-response":true,"properties":{"total_items":{"type":"integer","description":"The number of items in the whole list."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The page number of this page, starting at 1."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The items on this page.","items":{"$ref":"#/components/schemas/payment"}}}},"invoice_promotion_list":{"type":"object","title":"invoice_promotion_list","description":"An offset-based list of the promotions applied to an invoice.","x-response":true,"properties":{"total_items":{"type":"integer","description":"The number of items in the whole list."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The page number of this page, starting at 1."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The items on this page.","items":{"$ref":"#/components/schemas/promotion"}}}},"invoice_refund_list":{"type":"object","title":"invoice_refund_list","description":"An offset-based list of the refunds of an invoice's payments.","x-response":true,"properties":{"total_items":{"type":"integer","description":"The number of items in the whole list."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The page number of this page, starting at 1."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The items on this page.","items":{"$ref":"#/components/schemas/refund"}}}},"license_request":{"type":"object","title":"license_request","description":"One attempt by Comecero to get a license key from a license service for an order item. For a `remote_url` service this is also the body Comecero posts to your license server. Failed requests are retried on their own for several days.","properties":{"object":{"type":"string","enum":["license_request"],"description":"The object type. Always `license_request`."},"url":{"type":"string","format":"uri","description":"The URL of this license request in the API."},"license_request_id":{"type":"string","description":"The id of the license request."},"date_created":{"type":"string","format":"date-time","description":"When the request was first made."},"date_modified":{"type":"string","format":"date-time","description":"When the request last changed."},"test":{"type":"boolean","description":"True for a test-mode request."},"account_id":{"type":"string","description":"The account the request belongs to."},"status":{"type":"string","enum":["queued","completed","retry","failed"],"description":"`queued` before the first attempt, `completed` once a key was issued, `retry` while it waits for another automatic attempt, and `failed` when the attempts ran out."},"product_id":{"type":"string","description":"The product the key is for."},"license":{"description":"The license issued, as a link, or the full object when you send `expand=license`. Null until a key is issued. Left out for tokens that may not read licenses.","anyOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/license"},{"type":"null"}]},"license_service":{"description":"The license service asked, as a link, or the full object when you send `expand=license_service`. Left out for tokens that may not read license services.","anyOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/license_service"}]},"order":{"type":["object","null"],"description":"The order as it was sent to the license service, with the customer expanded and the service's `expand`, `show` and `hide` applied."},"retry_count":{"type":"integer","description":"How many attempts have been made. Returned only with `debug=true`."},"date_last_request_attempt":{"type":["string","null"],"format":"date-time","description":"When the last attempt was made. Returned only with `debug=true`."},"date_next_request_attempt":{"type":["string","null"],"format":"date-time","description":"When the next automatic attempt is due. Returned only with `debug=true`."},"last_failure_meta":{"type":["string","null"],"description":"Why the last attempt failed, with the first 500 characters of your server's response. Returned only with `debug=true`."},"formatted":{"type":"object","description":"Present only when you send `formatted=true`.","additionalProperties":{"type":["string","null"]}}},"required":["object","url","license_request_id","date_created","date_modified","test","account_id","status","product_id","order"],"example":{"object":"license_request","url":"https://api.comecero.com/api/v1/license_requests/0142130710483Lruow24Z6","license_request_id":"0142130710483Lruow24Z6","date_created":"2026-11-02T00:45:10Z","date_modified":"2026-11-02T01:15:10Z","test":true,"account_id":"AB1234","status":"retry","product_id":"widget-pro.test","license":null,"license_service":"https://api.comecero.com/api/v1/license_services/0095012789659LsuOeAWLC","order":{"object":"order","url":"https://api.comecero.com/api/v1/orders/6622-NXKHE-858","order_id":"6622-NXKHE-858","test":true},"retry_count":2,"date_last_request_attempt":"2026-11-02T01:15:10Z","date_next_request_attempt":"2026-11-02T02:15:10Z","last_failure_meta":"HTTP 500, Response Content (preview of first 500 characters): Internal Server Error"}},"license_request_list":{"type":"object","title":"license_request_list","description":"A page of license requests. A cursor-based list.","properties":{"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_after_item":{"type":["string","null"],"description":"The `after_item` value for the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_before_item":{"type":["string","null"],"description":"The `before_item` value for the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page. Present only when you sent `after_item` or `before_item`."},"data":{"type":"array","description":"The items on this page.","items":{"$ref":"#/components/schemas/license_request"}}},"required":["next_page_url","next_page_after_item","previous_page_url","previous_page_before_item","data"]},"license_service_list":{"type":"object","title":"license_service_list","description":"A page of license services. An offset-based list.","properties":{"total_items":{"type":"integer","description":"The number of items that match, across all pages."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The number of this page."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The items on this page.","items":{"$ref":"#/components/schemas/license_service"}}},"required":["total_items","total_pages","current_page","next_page_url","next_page_offset","previous_page_url","previous_page_offset","current_page_url","data"]},"license_service_request":{"type":"object","title":"license_service_request","description":"The fields you can set on a license service. On create, `name`, `label`, `type` and `configuration` are required (for a `list`, with at least one key). On update, send only the fields you want to change; inside `configuration`, only the fields you send change.","properties":{"name":{"type":"string","maxLength":75,"description":"Your name for the service."},"label":{"type":"string","maxLength":75,"description":"What the key is called when shown to the customer, for example `License Code` or `Registration Code`."},"description":{"type":["string","null"],"maxLength":256,"description":"Your notes about the service."},"instructions":{"type":["string","null"],"maxLength":1024,"description":"How to use the key, shown to the customer with it. Basic HTML is kept; anything else is stripped."},"type":{"type":"string","enum":["remote_url","list"],"description":"Where keys come from: `remote_url` asks your license server, `list` hands out keys you uploaded."},"expand":{"type":["string","null"],"description":"For `remote_url`: the child objects to expand in the order sent to your server, as in the `expand` query parameter. `customer` is always expanded."},"show":{"type":["string","null"],"description":"For `remote_url`: the only order fields to send to your server. Cannot be used with `hide`."},"hide":{"type":["string","null"],"description":"For `remote_url`: order fields to leave out of what is sent to your server. Cannot be used with `show`."},"configuration":{"description":"The settings for the service's `type`.","anyOf":[{"$ref":"#/components/schemas/license_service_remote_url_config"},{"$ref":"#/components/schemas/license_service_list_config"}]}},"example":{"name":"Widget Pro keys","label":"License Code","type":"list","instructions":"Open Widget Pro, choose Help, then Enter License, and paste the code.","configuration":{"licenses":["AAAA-BBBB-CCCC-0001","AAAA-BBBB-CCCC-0002"],"per_quantity":false,"notify_at_count":10}}},"license_list":{"type":"object","title":"license_list","description":"A page of licenses. A cursor-based list.","properties":{"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_after_item":{"type":["string","null"],"description":"The `after_item` value for the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_before_item":{"type":["string","null"],"description":"The `before_item` value for the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page. Present only when you sent `after_item` or `before_item`."},"data":{"type":"array","description":"The items on this page.","items":{"$ref":"#/components/schemas/license"}}},"required":["next_page_url","next_page_after_item","previous_page_url","previous_page_before_item","data"]},"license_create_request":{"type":"object","title":"license_create_request","description":"Asks a license service for a key for one item of an order, for example to issue a key by hand or to replace one.","properties":{"license_service_id":{"type":"string","description":"The license service to get the key from. Must be one of yours."},"order_id":{"type":"string","description":"The order the key is for. Must be one of your orders."},"product_id":{"type":"string","description":"The product of the order item the key is for. It must be an item of the order."},"item_id":{"type":"string","description":"The order item the key is for. When left out, `product_id` is used."},"account_id":{"type":"string","description":"Your account id. Send it: the order is looked up with the account id in the body, and without it the request fails."},"save":{"type":"boolean","description":"When false, the key is fetched and returned but not saved or added to the order. The license request is still recorded. The default is true."}},"required":["license_service_id","order_id","product_id"],"example":{"license_service_id":"0095012789659LsuOeAWLC","order_id":"6622-NXKHE-858","product_id":"widget-pro.test","account_id":"AB1234"}},"notification_subscription_list":{"title":"notification_subscription_list","description":"An offset-based page of notification subscriptions.","allOf":[{"$ref":"#/components/schemas/list_offset"},{"type":"object","properties":{"data":{"type":"array","description":"The notification subscriptions on this page.","items":{"$ref":"#/components/schemas/notification_subscription"}}}}]},"notification_subscription_request":{"type":"object","title":"notification_subscription_request","description":"The fields you can set on a notification subscription. On create, `type` and `method` are required. On update, send only the fields to change.","properties":{"type":{"$ref":"#/components/schemas/notification_type"},"method":{"type":"string","enum":["email"],"description":"How to send. Only `email`."},"active":{"type":"boolean","default":false,"description":"Whether the email is sent. On create the default is `false`. Only one subscription per type may be active (`409`)."},"from":{"type":["string","null"],"format":"email","description":"A sender address. It must be on your list of verified notification addresses (Settings, General), or the request fails with `422`."},"from_name":{"type":["string","null"],"maxLength":25,"description":"The sender name."},"reply_to":{"type":["string","null"],"format":"email","description":"The reply-to address."},"bcc":{"type":["string","null"],"description":"Up to 4 addresses, comma-separated, for a blind copy."},"subject":{"type":["string","null"],"maxLength":75,"description":"The subject line. It may hold placeholders such as `{{order.order_id}}`."},"template_id":{"type":["string","null"],"description":"The id of your template for the body. Leave it out or send `null` to use the built-in template."},"comments":{"type":["string","null"],"maxLength":256,"description":"Your own notes."}},"example":{"type":"shipment:confirmation","method":"email","active":true,"from_name":"Example Shop","reply_to":"support@example.com","subject":"Your order {{order.order_id}} has shipped"}},"notification_list":{"title":"notification_list","description":"A cursor-based page of notifications.","allOf":[{"$ref":"#/components/schemas/list_cursor"},{"type":"object","properties":{"data":{"type":"array","description":"The notifications on this page.","items":{"$ref":"#/components/schemas/notification"}}}}]},"notification_request":{"type":"object","title":"notification_request","description":"An email to send now, built from one of your templates.","required":["method","destination","from","reply_to","template_id","data"],"properties":{"method":{"type":"string","enum":["email"],"description":"How to send. Only `email`."},"destination":{"type":"string","format":"email","description":"The one address to send to."},"from":{"type":"string","format":"email","description":"The sender address. It must be one of your verified notification addresses (Settings, General), or the request fails with `400`."},"from_name":{"type":["string","null"],"description":"The sender name."},"reply_to":{"type":"string","format":"email","description":"The reply-to address. Required."},"subject":{"type":["string","null"],"description":"The subject line, sent as is."},"template_id":{"type":"string","description":"The id of a template in your account that builds the body."},"data":{"type":"object","additionalProperties":true,"description":"The values the template reads, at most 50,000 characters as JSON. Your account's details are added as `account` unless you send your own."}},"example":{"method":"email","destination":"john@example.com","from":"orders@example.com","from_name":"Example Shop","reply_to":"support@example.com","subject":"Your download is ready","template_id":"1102500900112TEm5Jc3Rw","data":{"customer":{"first_name":"John"},"download_url":"https://example.com/downloads/abc123"}}},"order_capture_request":{"type":"object","title":"order_capture_request","description":"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.","properties":{"total":{"type":"number","exclusiveMinimum":0,"description":"The amount to capture, in the order currency. Cannot be more than the order total. Cannot be sent with `items` or `shipping`."},"items":{"type":"array","minItems":1,"description":"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.","items":{"type":"object","required":["item_id"],"properties":{"item_id":{"type":"string","description":"An `item_id` on the order."},"quantity":{"type":"number","description":"The quantity to capture. Can be a decimal. Do not send `price`, `subtotal`, `tax` or `total` on an item."}}}},"shipping":{"type":"number","description":"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."}},"example":{"items":[{"item_id":"1","quantity":1}],"shipping":5}},"order_payment_list":{"type":"object","title":"payment_list","description":"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.","properties":{"object":{"type":"string","enum":["payment_list"],"description":"The object type. Always `payment_list`."},"url":{"type":"string","format":"uri","description":"The URL of this result."},"payment_list_id":{"type":"string","description":"The id of this result."},"test":{"type":"boolean","description":"True for test payments."},"account_id":{"type":["string","null"],"description":"The account the payments belong to."},"currency":{"type":["string","null"],"description":"The currency of the payments."},"subtotal":{"type":"number","description":"The subtotal of the payments that are now completed or pending, in `currency`."},"shipping":{"type":"number","description":"The shipping of the payments that are now completed or pending, in `currency`."},"tax":{"type":"number","description":"The tax of the payments that are now completed or pending, in `currency`."},"total":{"type":"number","description":"The total of the payments that are now completed or pending, in `currency`."},"success_count":{"type":"integer","description":"How many payments succeeded."},"failure_count":{"type":"integer","description":"How many payments failed."},"payments":{"type":"array","description":"The payments, each with its new status.","items":{"$ref":"#/components/schemas/payment"}}},"required":["object","url","payment_list_id","test","account_id","currency","subtotal","shipping","tax","total","success_count","failure_count","payments"]},"order_item_request":{"type":"object","title":"order_item_request","description":"The fields you may change on an order item. Every other field is read-only and is ignored.","properties":{"fulfilled":{"type":"boolean","description":"Set to `true` to mark the item fulfilled. When this makes every item on the order fulfilled, the order is marked fulfilled, any pending (authorized) payment is captured and the `order:fulfilled` event fires. Set to `false` to mark the item, and so the order, not fulfilled."},"meta":{"description":"Your own data for this item, a string or an object. At most 2048 characters once serialized.","type":["object","string","null"]}},"example":{"fulfilled":true}},"shipment_list":{"title":"shipment_list","description":"An offset-based page of shipments.","allOf":[{"$ref":"#/components/schemas/list_offset"},{"type":"object","properties":{"data":{"type":"array","description":"The shipments on this page.","items":{"$ref":"#/components/schemas/shipment"}}}}]},"refund_item_request":{"type":"object","title":"refund_item_request","description":"One item to refund on an order or invoice.","properties":{"item_id":{"type":"string","description":"An `item_id` on the order or invoice. Each may appear once."},"quantity":{"type":"number","exclusiveMinimum":0,"description":"The quantity to refund. Can be a decimal. Leave it out to refund all of the quantity not refunded yet. This plus what was refunded before cannot be more than the quantity ordered. Do not send `price`, `subtotal`, `tax` or `total` on an item: the amounts are worked out from the quantity."},"meta":{"description":"Your own data for this refund item, a string or an object. At most 2048 characters once serialized.","type":["object","string","null"]}},"required":["item_id"],"example":{"item_id":"1","quantity":1}},"refund_request":{"type":"object","title":"refund_request","description":"What to refund. **Send no body, or `{}`, to refund everything that has not been refunded yet (a full refund).** For a partial refund send exactly one of `total`, `tax`, `items` or `shipping`; `items` and `shipping` may be sent together. The other amounts are worked out for you. `subtotal` is never accepted. `items` works when you refund an order or an invoice, or a payment that belongs to one. A payment with no order or invoice ignores `items`, so a body with only `items` refunds that payment in full.","properties":{"total":{"type":"number","exclusiveMinimum":0,"description":"The amount to give back, with tax, in the payment currency. The tax part is worked out for you. This plus earlier refunds cannot be more than what was paid. Required when `is_chargeback` is `true`."},"tax":{"type":"number","exclusiveMinimum":0,"description":"Refund only tax, for example when tax was charged by mistake. Cannot be sent with `total`, `items` or `shipping`."},"shipping":{"type":"number","exclusiveMinimum":0,"description":"The shipping amount to give back, with tax, in the payment currency. Up to the shipping not refunded yet. May be sent with `items`."},"items":{"type":"array","minItems":1,"description":"The items to refund, by `item_id` and quantity. Only for an order, an invoice, or a payment that belongs to one.","items":{"$ref":"#/components/schemas/refund_item_request"}},"reason":{"type":"string","description":"Why you are refunding. Use one of the reasons from `GET /refunds/options` to keep reports tidy."},"comments":{"type":"string","maxLength":1024,"description":"Your own notes about the refund."},"reference":{"type":"string","maxLength":100,"description":"Your own reference for the refund. You can filter lists by it."},"meta":{"description":"Your own data for the refund, a string or an object. At most 2048 characters once serialized.","type":["object","string"]},"payment_method":{"type":"object","description":"Send `{\"type\": \"customer_account_balance\"}` to give the money to the customer's store credit instead of back to the card or wallet they paid with. Leave it out to refund the original payment method.","properties":{"type":{"type":"string","enum":["customer_account_balance"]}}},"is_chargeback":{"type":"boolean","description":"Set to `true` to record a chargeback the bank already took. No money moves. Needs `total`. Only used on accounts on the agent model (or when Comecero staff send it); otherwise it is ignored without an error and the refund is real: money goes back. On a gateway that Comecero owns, only Comecero staff may send it (400). An order with more than one successful payment must take it on the payment instead. Not allowed when the payment was made from store credit."},"record_only":{"type":"boolean","description":"Set to `true` to write down a refund you paid back some other way. No money moves. Needs `record_only_memo`. Same limits as `is_chargeback`."},"record_only_memo":{"type":"string","minLength":5,"description":"How a record-only refund was paid back, at least 5 characters. Required when `record_only` is `true`."}},"example":{"items":[{"item_id":"1","quantity":1}],"reason":"Customer request"}},"refund_list":{"type":"object","title":"refund_list","description":"The result of refunding an order. An order can have more than one payment, and the refund is spread over them, largest first (store credit payments last), so this holds one refund per payment used, each with its own result.","properties":{"object":{"type":"string","enum":["refund_list"],"description":"The object type. Always `refund_list`."},"url":{"type":"string","format":"uri","description":"The URL of this result, which you can read again later."},"refund_list_id":{"type":"string","description":"The id of this result."},"test":{"type":"boolean","description":"True for test refunds."},"account_id":{"type":["string","null"],"description":"The account the refunds belong to."},"currency":{"type":["string","null"],"description":"The currency of the refunds."},"subtotal":{"type":"number","description":"The subtotal of the refunds that completed or are pending, in `currency`."},"shipping":{"type":"number","description":"The shipping of the refunds that completed or are pending, in `currency`."},"tax":{"type":"number","description":"The tax of the refunds that completed or are pending, in `currency`."},"total":{"type":"number","description":"The total of the refunds that completed or are pending, in `currency`."},"success_count":{"type":"integer","description":"How many refunds succeeded (completed or pending)."},"failure_count":{"type":"integer","description":"How many refunds failed."},"refunds":{"type":"array","description":"The refunds made.","items":{"$ref":"#/components/schemas/refund"}}},"required":["object","url","refund_list_id","test","account_id","currency","subtotal","shipping","tax","total","success_count","failure_count","refunds"],"example":{"object":"refund_list","url":"https://api.comecero.com/api/v1/refund_list/0090374314470RlA8kWm3T","refund_list_id":"0090374314470RlA8kWm3T","test":true,"account_id":"AB1234","currency":"USD","subtotal":49.95,"shipping":0,"tax":0,"total":49.95,"success_count":1,"failure_count":0,"refunds":[{"object":"refund","url":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5","refund_id":"0090374314462Rec3PffZ5","account_id":"AB1234","success":true,"status":"completed","reference":null,"date_created":"2026-11-03T10:12:40Z","date_modified":"2026-11-03T10:12:41Z","date_completed":"2026-11-03T10:12:41Z","test":true,"currency":"USD","subtotal":49.95,"shipping":0,"tax":0,"total":49.95,"reason":"Customer request","apply_to_balance":false,"is_chargeback":false,"record_only":false,"record_only_memo":null,"response_code":"OK","response_message":"OK","gateway_transaction_id":"re_test_3PffZ5","gateway_error_code":null,"gateway_error_message":null,"gateway":"https://api.comecero.com/api/v1/gateways/0089584408915Gtf5AsdJ8","comments":null,"payment_method":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/payment_method","settlement_currency":"USD","settlement_subtotal":49.95,"settlement_shipping":0,"settlement_tax":0,"settlement_total":49.95,"fx_rate":1,"reporting_currency":"USD","reporting_subtotal":49.95,"reporting_shipping":0,"reporting_tax":0,"reporting_total":49.95,"reporting_fx_rate":1,"items":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/items","customer":"https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4","order":"https://api.comecero.com/api/v1/orders/7393-GMRFY-954","payment":"https://api.comecero.com/api/v1/payments/0093717991362PyRYN1qc6","invoice":null,"fees":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fees","fee_summary":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fee_summary","commissions":"https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/commissions","meta":null}]}},"shipment_request":{"type":"object","title":"shipment_request","description":"A new shipment for an order. Saving it marks order items fulfilled once every unit has shipped. When that makes the whole order fulfilled, any pending (authorized) payment is captured and `order:fulfilled` fires. The `shipment:created` event fires and the customer gets the shipment email.","properties":{"items":{"type":"array","minItems":1,"description":"The order items in the parcel. At least one.","items":{"type":"object","required":["item_id","quantity"],"properties":{"item_id":{"type":"string","description":"An `item_id` on the order."},"quantity":{"type":"integer","minimum":1,"description":"How many units. This plus the units in earlier shipments cannot be more than the quantity ordered."}}}},"date_shipped":{"type":"string","format":"date-time","description":"When the parcel left or will leave. Can be in the past or the future. Defaults to now."},"courier":{"type":"string","maxLength":50,"description":"The carrier, for example `UPS`. See the shipment object for the carriers that get a tracking link made for them."},"tracking_number":{"type":"string","description":"The tracking number."},"tracking_url":{"type":"string","maxLength":256,"description":"The tracking page. Leave it out for known carriers."}},"example":{"items":[{"item_id":"1","quantity":2}],"courier":"UPS","tracking_number":"1Z999AA10123456784"}},"payment_list":{"type":"object","title":"payment_list","description":"A group of payments acted on together, such as the captures or voids made when you capture or void an order with more than one payment. Not a page of a list: it has no paging.","x-response":true,"properties":{"object":{"type":"string","enum":["payment_list"],"description":"The object type. Always `payment_list`."},"url":{"type":"string","format":"uri","description":"The full URL of the payment list."},"payment_list_id":{"type":"string","description":"The id of the payment list."},"test":{"type":"boolean","description":"True for test payments. False when the list is empty."},"account_id":{"type":["string","null"],"description":"The account of the payments. Null when the list is empty."},"currency":{"type":["string","null"],"description":"The currency of the first payment. Null when the list is empty."},"subtotal":{"type":"number","description":"The sum of `subtotal` of the `pending` and `completed` payments."},"shipping":{"type":"number","description":"The sum of `shipping` of the `pending` and `completed` payments."},"tax":{"type":"number","description":"The sum of `tax` of the `pending` and `completed` payments."},"total":{"type":"number","description":"The sum of `total` of the `pending` and `completed` payments."},"success_count":{"type":"integer","description":"How many payments have `success` true."},"failure_count":{"type":"integer","description":"How many payments have `success` false."},"payments":{"type":"array","description":"The payments.","items":{"$ref":"#/components/schemas/payment"}}},"required":["object","url","payment_list_id","test","account_id","currency","subtotal","shipping","tax","total","success_count","failure_count","payments"],"example":{"object":"payment_list","url":"https://api.comecero.com/api/v1/payment_list/0091310055812aB3kQ9","payment_list_id":"0091310055812aB3kQ9","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":[]}},"payment_cursor_list":{"type":"object","title":"payment_cursor_list","description":"A cursor-based list of payments.","x-response":true,"properties":{"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_after_item":{"type":["string","null"],"description":"The `after_item` value for the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_before_item":{"type":["string","null"],"description":"The `before_item` value for the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page. Only present when you asked for a page with `after_item` or `before_item`."},"data":{"type":"array","description":"The payments on this page.","items":{"$ref":"#/components/schemas/payment"}}},"required":["next_page_url","next_page_after_item","previous_page_url","previous_page_before_item","data"]},"payment_options":{"type":"object","title":"payment_options","description":"What a shopper can pay with on your account, for a payment with no cart or invoice: currencies, payment methods, card types and the customer fields to collect.","x-limited":true,"x-response":true,"properties":{"account_id":{"type":"string","description":"Your account."},"test":{"type":"boolean","description":"True for test mode."},"currencies":{"type":"array","description":"The currencies your account takes.","items":{"type":"object","properties":{"code":{"type":"string","description":"ISO 4217 code."},"name":{"type":"string"}}}},"customer_default_currency":{"type":["string","null"],"description":"The best currency for the caller's location among those you take."},"customer_default_country":{"type":["string","null"],"description":"The country of the caller's IP address."},"payment_methods":{"type":"array","description":"The payment methods available in the requested currency, or your default one.","items":{"$ref":"#/components/schemas/payment_option"}},"card_types":{"type":"array","description":"The card brands taken in that currency.","items":{"type":"string"}},"customer_required_fields":{"type":"array","description":"The customer fields that must be sent with a payment, in dot notation.","items":{"type":"string"}},"customer_optional_fields":{"type":"array","description":"The customer fields you may also collect.","items":{"type":"string"}},"allowed_customer_countries":{"type":"array","description":"The countries a customer may be in.","items":{"type":"string"}}},"required":["account_id","test","currencies","customer_default_currency","customer_default_country","payment_methods","card_types","customer_required_fields","customer_optional_fields","allowed_customer_countries"],"example":{"account_id":"AB1234","test":true,"currencies":[{"code":"USD","name":"US Dollar"},{"code":"EUR","name":"Euro"}],"customer_default_currency":"USD","customer_default_country":"US","payment_methods":[{"payment_method_type":"credit_card","surcharge":0,"currency":"USD","paypal_fraudnet_source_id":null,"stripe_publishable_key":null,"stripe_account_id":null,"finix_card_form":null}],"card_types":["Visa","MasterCard"],"customer_required_fields":["name","email","billing_address.country"],"customer_optional_fields":["phone"],"allowed_customer_countries":["US","CA"]}},"payment_update_request":{"type":"object","title":"payment_update_request","description":"The fields of a payment you can change. Only the fields you send change; any other field is ignored.","x-limited":true,"x-request":true,"properties":{"payment_id":{"type":"string","description":"Optional. Must match the id in the URL."},"description":{"type":["string","null"],"maxLength":256,"description":"Your description of the payment."},"reference":{"type":["string","null"],"maxLength":100,"description":"Your own reference for the payment."},"meta":{"description":"Your own data for the payment, a string or an object, up to 2048 characters.","type":["object","string","null"]}},"example":{"reference":"PO-20261107-01"}},"payment_capture_request":{"type":"object","title":"payment_capture_request","description":"Optional. Send no body to capture the full amount. Only `total` is allowed; `subtotal`, `tax`, `shipping` or `items` are refused (error `Sye7VYp`).","x-request":true,"properties":{"total":{"type":"number","minimum":0,"description":"The amount to capture, in the payment currency, no more than the authorized total. What is not captured is recorded as a refund. If you send a body without `total`, 0 is captured, so leave the body out to capture everything."}},"example":{"total":150}},"payment_commission_list":{"type":"object","title":"payment_commission_list","description":"An offset-based list of the commissions on a payment.","x-response":true,"properties":{"total_items":{"type":"integer","description":"The number of items in the whole list."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The page number of this page, starting at 1."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The commissions on this page.","items":{"$ref":"#/components/schemas/commission"}}},"required":["total_items","total_pages","current_page","next_page_url","next_page_offset","previous_page_url","previous_page_offset","current_page_url","data"]},"payment_commit_request":{"type":"object","title":"payment_commit_request","description":"Optional. What a commit may carry. Everything else in the body is ignored: the amounts are worked out again from the cart or invoice.","x-limited":true,"x-request":true,"properties":{"capture":{"type":"boolean","description":"True to capture at once, false to only authorize. Left out, your fulfillment settings decide. Ignored for a limited token.","x-exclude-limited":true},"payment_method":{"type":"object","description":"Results the browser got from the shopper's step, merged into the payment method. Only the fields below are read.","properties":{"data":{"type":"object","description":"For `credit_card`, the 3-D Secure results from a 3-D Secure page you run yourself. For `apple_pay`, `details` from the Apple Pay sheet.","properties":{"cryptogram":{"type":"string","description":"The authentication value (CAVV)."},"eci_indicator":{"type":"string","description":"The ECI value."},"three_ds_server_trans_id":{"type":"string"},"three_ds_ds_trans_id":{"type":"string"},"three_ds_message_version":{"type":"string"},"three_ds_trans_status":{"type":"string"},"details":{"type":"object","description":"For `apple_pay`, the payment details from the sheet.","additionalProperties":true}}}}}},"example":{}},"payment_fee_list":{"type":"object","title":"payment_fee_list","description":"An offset-based list of the fees on a payment.","x-response":true,"properties":{"total_items":{"type":"integer","description":"The number of items in the whole list."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The page number of this page, starting at 1."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The fees on this page.","items":{"$ref":"#/components/schemas/fee"}}},"required":["total_items","total_pages","current_page","next_page_url","next_page_offset","previous_page_url","previous_page_offset","current_page_url","data"]},"payment_notification_list":{"type":"object","title":"payment_notification_list","description":"An offset-based list of the notifications sent for a payment.","x-response":true,"properties":{"total_items":{"type":"integer","description":"The number of items in the whole list."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The page number of this page, starting at 1."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The notifications on this page.","items":{"$ref":"#/components/schemas/notification"}}},"required":["total_items","total_pages","current_page","next_page_url","next_page_offset","previous_page_url","previous_page_offset","current_page_url","data"]},"payment_refund_list":{"type":"object","title":"payment_refund_list","description":"An offset-based list of the refunds of a payment.","x-response":true,"properties":{"total_items":{"type":"integer","description":"The number of items in the whole list."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The page number of this page, starting at 1."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The refunds on this page.","items":{"$ref":"#/components/schemas/refund"}}},"required":["total_items","total_pages","current_page","next_page_url","next_page_offset","previous_page_url","previous_page_offset","current_page_url","data"]},"product_inventory_request":{"type":["object","null"],"title":"product_inventory_request","description":"Turns on stock tracking for the product. Send null to stop tracking. Send `current` to set the stock level, or `adjust_quantity_by` to change it.","properties":{"current":{"type":"number","writeOnly":true,"description":"Sets the units in stock to this number."},"adjust_quantity_by":{"type":"number","writeOnly":true,"description":"Adds this many units to the stock (use a negative number to take units away). Ignored when `current` is sent."},"allow_oversells":{"type":"boolean","description":"When true, shoppers may buy more than is in stock. The default is false."},"low_quantity_notification":{"type":["number","null"],"description":"The stock level at which the `product.low_inventory` event fires."}},"example":{"current":120,"allow_oversells":false,"low_quantity_notification":10}},"product_request":{"type":"object","title":"product_request","description":"The fields you can set on a product. On create, `name`, `type` and at least one price are required. On update, send only the fields you want to change; the rest keep their values.","properties":{"product_id":{"type":"string","maxLength":30,"description":"The id you want for the product. Letters, numbers, underscores, dashes and periods only. It is stored in lower case, and `.test` is added to a test product's id. If you leave it out, the next free number is used. Must not be in use already. Can only be set on create; on update it must match the id in the URL."},"name":{"type":"string","maxLength":75,"description":"The name of the product. Required on create."},"type":{"type":"string","enum":["physical","digital","service","bundle"],"description":"The kind of product. Required on create."},"description":{"type":["string","null"],"maxLength":2048,"description":"A description of the product."},"headline":{"type":["string","null"],"maxLength":100,"description":"A short line about the product."},"tax_code":{"type":["string","null"],"description":"The tax code that decides how the product is taxed."},"prices":{"type":"array","minItems":1,"description":"The price in each currency you want to set, at least one. Each price must be 0 or more and each currency may appear only once. On update, the list replaces the old one and may not be empty or null.","items":{"$ref":"#/components/schemas/price"}},"compare_at_prices":{"type":"array","description":"Higher \"was\" prices to show next to the price. Each must be greater than 0. Replaces the old list.","items":{"$ref":"#/components/schemas/price"}},"volume_prices":{"type":"array","description":"Quantity tiers with their own unit price. Replaces the old list.","items":{"$ref":"#/components/schemas/product_volume_price"}},"weight":{"description":"The weight of one unit. Send null to remove it.","anyOf":[{"$ref":"#/components/schemas/weight"},{"type":"null"}]},"active":{"type":"boolean","description":"True to put the product on sale. The default on create is false, so send `true` for a product shoppers can buy. Setting it to true also clears `deleted`. Cannot be true when `deleted` is true."},"deleted":{"type":"boolean","description":"Update only. True marks the product deleted and inactive; false restores it. A product cannot be created deleted."},"hidden":{"type":"boolean","description":"True to leave the product out of the product list for shoppers while keeping it for sale by its id. The default is false."},"file_id":{"type":["string","null"],"description":"The file a buyer may download. It must be one of your files. Not allowed on a bundle."},"license_service_id":{"type":["string","null"],"description":"The license service that issues a license key when the product is bought. It must be one of your license services. Not allowed on a bundle."},"subscription_plan_id":{"type":["string","null"],"description":"The subscription plan to start each time the product is bought. It must be one of your plans and not deleted. Not allowed on a bundle."},"image_ids":{"type":"array","description":"The ids of the product's images, in display order. Each must be one of your images. Repeats are removed. Replaces the old list.","items":{"type":"string"}},"video_url":{"type":["string","null"],"format":"uri","maxLength":256,"description":"A link to a video about the product. Must be a valid URL."},"related_product_ids":{"type":["array","null"],"maxItems":3,"description":"Up to 3 products to suggest with this one. Each must exist, be active and not be deleted. No repeats, and not the product itself. Send null or an empty list to remove them all. Read them at `GET /products/{product_id}/related_products`.","items":{"type":"string"}},"subscription_change_product_ids":{"type":["array","null"],"maxItems":10,"description":"Up to 10 products a subscriber to this product may switch to. Each must exist, be active, not be deleted and have the same subscription plan as this product. No repeats; the product itself is dropped. Send null to remove them all.","items":{"type":"string"}},"subscription_term_change_product_ids":{"type":["array","null"],"maxItems":10,"description":"Up to 10 products on a different subscription plan (for example yearly instead of monthly) that a subscriber may switch to. Each must exist, be active, not be deleted and have a subscription plan other than this product's. No repeats; the product itself is dropped. Send null to remove them all.","items":{"type":"string"}},"inventory":{"$ref":"#/components/schemas/product_inventory_request"},"bundle_items":{"type":"array","description":"Required for a bundle, with at least one item. The products the bundle holds, each once, not the bundle itself.","items":{"$ref":"#/components/schemas/product_bundle_item"}},"meta":{"description":"Your own data for the product, a string or an object, up to 2048 characters.","type":["object","string","null"]},"translations":{"type":["object","null"],"description":"The product's text in other languages, keyed by a 2 to 5 character language code such as `de` or `ja-JP`. Replaces the old translations. Send null to remove them.","additionalProperties":{"$ref":"#/components/schemas/product_translation"}}},"example":{"product_id":"widget","name":"Widget","type":"physical","description":"A simple widget for everyday use.","headline":"The widget you will use every day","prices":[{"price":49.95,"currency":"USD"},{"price":45.95,"currency":"EUR"}],"compare_at_prices":[{"price":59.95,"currency":"USD"}],"volume_prices":[{"low":10,"prices":[{"price":39.95,"currency":"USD"}]}],"weight":{"amount":3,"unit":"lb"},"active":true,"hidden":false,"image_ids":["0099844605810ImLAMbo73"],"inventory":{"current":120,"allow_oversells":false,"low_quantity_notification":10},"translations":{"de":{"name":"Widget","headline":"Das Widget fur jeden Tag","description":"Ein einfaches Widget fur jeden Tag."}}}},"promotion_request":{"type":"object","title":"promotion_request","description":"The fields you can set on a promotion. On create, `type` and `config` are required. On update, send only the fields you want to change.","properties":{"type":{"type":"string","enum":["coupon","cross_sell","up_sell"],"description":"The kind of promotion. Required on create. Cannot be changed later."},"name":{"type":["string","null"],"maxLength":50,"description":"Your name for the promotion."},"active":{"type":"boolean","description":"True to make the promotion usable. The default on create is false."},"apply_to_recurring":{"type":"boolean","description":"True to also discount a subscription's later billings. Not allowed for `order` and `shipping` coupons. The default is false."},"apply_to_recurring_count":{"type":["integer","null"],"minimum":1,"maximum":100,"description":"How many later billings get the discount, 1 to 100. Send null to discount all of them. Only allowed when `apply_to_recurring` is true."},"expires":{"type":["string","null"],"format":"date-time","description":"When the promotion stops working, as an ISO 8601 date or date and time, read in the `timezone` you send. Must be in the future. Send null for never."},"comments":{"type":["string","null"],"maxLength":250,"description":"Your notes."},"config":{"description":"The rules for the promotion's `type`. Required on create. On update it replaces the old rules, except that a coupon's `code` and `generator_prefix` cannot change.","oneOf":[{"$ref":"#/components/schemas/promotion_coupon_config"},{"$ref":"#/components/schemas/promotion_cross_sell_config"},{"$ref":"#/components/schemas/promotion_up_sell_config"}]}},"example":{"type":"coupon","name":"Ten percent off","active":true,"expires":"2026-12-31T23:59:59Z","config":{"type":"order","code":"SAVE10","discount_percent":0.1,"max_uses_per_customer":1}}},"refund_options":{"type":"object","title":"refund_options","description":"The refund and chargeback reasons your account offers.","properties":{"account_id":{"type":"string","description":"The account."},"test":{"type":"boolean","description":"True when read with a test token."},"refund_reasons":{"type":"array","items":{"type":"string"},"description":"The reasons to pick from when you refund."},"chargeback_reasons":{"type":"array","items":{"type":"string"},"description":"The reasons to pick from when you record a chargeback."}},"required":["account_id","test","refund_reasons","chargeback_reasons"]},"refund_update_request":{"type":"object","title":"refund_update_request","description":"The fields you may change on a refund after it is made. Every other field is read-only and is ignored. The body cannot be empty.","properties":{"comments":{"type":["string","null"],"maxLength":1024,"description":"Your own notes about the refund."},"meta":{"description":"Your own data for the refund, a string or an object. At most 2048 characters once serialized.","type":["object","string","null"]}},"example":{"comments":"Customer was refunded after a support call."}},"report_formatted_dates":{"type":"object","title":"report_formatted_dates","description":"The report dates as display text in the shopper's language. Only present when `formatted=true`.","properties":{"date_created":{"type":"string","example":"Nov 7, 2026"},"date_start":{"type":["string","null"],"example":"Nov 6, 2026"},"date_end":{"type":["string","null"],"example":"Nov 6, 2026"}}},"report_commissions":{"type":"object","title":"report_commissions","description":"The commissions Comecero owes the account in a date range or on one payout, totalled per currency and broken down by commission type.","properties":{"object":{"type":"string","enum":["report.commissions"],"description":"The object type. Always `report.commissions`."},"url":{"type":"string","format":"uri","description":"The URL that returns this report again, with the dates, filters and time zone it used."},"account_id":{"type":["string","null"],"description":"The account the report is for."},"date_created":{"type":"string","format":"date-time","description":"When the report was run, in the report time zone."},"date_start":{"type":["string","null"],"format":"date-time","description":"The start of the range the report covers, in the report time zone."},"date_end":{"type":["string","null"],"format":"date-time","description":"The end of the range the report covers, in the report time zone."},"timezone":{"type":"string","description":"The time zone used to read the dates."},"test":{"type":"boolean","description":"True when the report covers test mode data."},"type":{"type":["string","null"],"description":"Not used. Always null."},"data":{"type":"array","description":"One group per currency. When you ask for a reporting `currency`, all commissions are converted into it and there is one group.","items":{"type":"object","properties":{"currency":{"type":["string","null"],"description":"The currency of this group."},"total":{"type":"number","description":"The sum of the commissions, in this group's currency. Refunds count as negative commissions."},"transaction_count":{"type":"number","description":"How many commissions."},"breakdowns":{"type":"array","description":"One row per commission type, largest total first.","items":{"type":"object","properties":{"type":{"type":"string","enum":["product_sales"],"description":"The commission type."},"total":{"type":"number","description":"The sum of these commissions, in the group's currency."},"transaction_count":{"type":"number","description":"How many commissions."},"formatted":{"type":"object","description":"Only present when `formatted=true`.","properties":{"total":{"type":"string"}}}}}},"formatted":{"type":"object","description":"Only present when `formatted=true`.","properties":{"total":{"type":"string"}}}}}},"formatted":{"$ref":"#/components/schemas/report_formatted_dates"}}},"report_fees":{"type":"object","title":"report_fees","description":"The fees Comecero charged the account in a date range or on one bill, totalled per currency and broken down by fee type.","properties":{"object":{"type":"string","enum":["report.fees"],"description":"The object type. Always `report.fees`."},"url":{"type":"string","format":"uri","description":"The URL that returns this report again, with the dates, filters and time zone it used."},"account_id":{"type":["string","null"],"description":"The account the report is for."},"date_created":{"type":"string","format":"date-time","description":"When the report was run, in the report time zone."},"date_start":{"type":["string","null"],"format":"date-time","description":"The start of the range the report covers, in the report time zone."},"date_end":{"type":["string","null"],"format":"date-time","description":"The end of the range the report covers, in the report time zone."},"timezone":{"type":"string","description":"The time zone used to read the dates."},"test":{"type":"boolean","description":"True when the report covers test mode data."},"type":{"type":["string","null"],"description":"The fee type you filtered on, or null.","enum":["payment_completed","refund_completed","auth","zero_auth","capture","void","decline","chargeback","fx_conversion","international_card","payout","platform_monthly","platform_annual","support_annual","miscellaneous",null]},"data":{"type":"array","description":"One group per currency. When you ask for a reporting `currency`, all fees are converted into it and there is one group.","items":{"type":"object","properties":{"currency":{"type":["string","null"],"description":"The currency of this group."},"total":{"type":"number","description":"The fees Comecero bills you, in this group's currency. Fees the provider already took from the money (`collected`) are not in it."},"transaction_count":{"type":"number","description":"How many billed fees."},"collected_total":{"type":"number","description":"Fees the provider already took from the money (Comecero Express Payments), in this group's currency. These are never billed."},"collected_transaction_count":{"type":"number","description":"How many collected fees."},"breakdowns":{"type":"array","description":"One row per fee type, category and collected flag, largest total first.","items":{"type":"object","properties":{"type":{"type":"string","description":"The fee type.","enum":["payment_completed","refund_completed","auth","zero_auth","capture","void","decline","chargeback","fx_conversion","international_card","payout","platform_monthly","platform_annual","support_annual","miscellaneous"]},"category":{"type":"string","enum":["transaction","operation"],"description":"`transaction` for fees on payments and refunds, `operation` for account fees such as the monthly platform fee."},"collected":{"type":"boolean","description":"True when the provider already took these fees from the money."},"total":{"type":"number","description":"The sum of these fees, in the group's currency."},"transaction_count":{"type":"number","description":"How many fees."},"formatted":{"type":"object","description":"Only present when `formatted=true`.","properties":{"total":{"type":"string"}}}}}},"formatted":{"type":"object","description":"Only present when `formatted=true`.","properties":{"total":{"type":"string"},"collected_total":{"type":"string"}}}}}},"formatted":{"$ref":"#/components/schemas/report_formatted_dates"}}},"report_items":{"type":"object","title":"report_items","description":"Sales totals per product for a date range, one row per item_id.","properties":{"object":{"type":"string","enum":["report.items"],"description":"The object type. Always `report.items`."},"url":{"type":"string","format":"uri","description":"The URL that returns this report again, with the dates, filters and time zone it used."},"account_id":{"type":"string","description":"The account the report is for."},"date_created":{"type":"string","format":"date-time","description":"When the report was run, in the report time zone."},"date_start":{"type":["string","null"],"format":"date-time","description":"The start of the range the report covers, in the report time zone."},"date_end":{"type":["string","null"],"format":"date-time","description":"The end of the range the report covers, in the report time zone."},"timezone":{"type":"string","description":"The time zone used to read the dates."},"test":{"type":"boolean","description":"True when the report covers test mode data."},"type":{"type":"string","enum":["payments","refunds","combined"],"description":"Which transactions are counted. `payments` (the default) reads completed orders, `refunds` reads completed refunds (negative amounts), `combined` nets refunds against the items on this page."},"currency":{"type":"string","description":"The currency every amount is in: the account's primary reporting currency, or its secondary one when you asked for it with `currency`."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null when this page has fewer rows than the page size."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or null."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or null."},"data":{"type":"array","description":"One row per product.","items":{"type":"object","properties":{"item_id":{"type":"string","description":"The product id."},"name":{"type":["string","null"],"description":"The product name as it was on the order."},"subtotal":{"type":"number","description":"The subtotal, in `currency`."},"tax":{"type":"number","description":"The tax, in `currency`."},"total":{"type":"number","description":"The subtotal plus tax, in `currency`."},"transaction_count":{"type":"integer","description":"How many orders or refunds held this item."},"item_count":{"type":"number","description":"How many units (sum of quantities)."},"formatted":{"type":"object","description":"The amounts as display text. Only present when `formatted=true`.","properties":{"subtotal":{"type":"string"},"tax":{"type":"string"},"total":{"type":"string"}}}}}},"formatted":{"$ref":"#/components/schemas/report_formatted_dates"}}},"report_stats":{"type":"object","title":"report_stats","description":"Statistics over the rows in a report's `data`: one value per row (per hour, day, month or year, or one row when there is no grouping).","properties":{"sum":{"type":"number","description":"The sum of all rows."},"average":{"type":"number","description":"The average of all rows."},"max":{"type":"number","description":"The largest row."},"min":{"type":"number","description":"The smallest row."},"median":{"type":"number","description":"The median of the rows. Core does not sort the rows first, so with more than two rows this is the middle row in date order, not the true median."},"formatted":{"type":"object","description":"The same values as display text in the report currency. Only present when `formatted=true`, and never on `transaction_count` or `item_count`.","properties":{"sum":{"type":"string"},"average":{"type":"string"},"max":{"type":"string"},"min":{"type":"string"},"median":{"type":"string"}}}}},"report_sales":{"type":"object","title":"report_sales","description":"Sales totals for a date range: subtotal, shipping, tax and total, with counts, optionally split by hour, day, month or year.","properties":{"object":{"type":"string","enum":["report.sales"],"description":"The object type. Always `report.sales`."},"url":{"type":"string","format":"uri","description":"The URL that returns this report again, with the dates, filters and time zone it used."},"account_id":{"type":"string","description":"The account the report is for."},"date_created":{"type":"string","format":"date-time","description":"When the report was run, in the report time zone."},"date_start":{"type":["string","null"],"format":"date-time","description":"The start of the range the report covers, in the report time zone."},"date_end":{"type":["string","null"],"format":"date-time","description":"The end of the range the report covers, in the report time zone. A `date_end` later than today is cut back to the end of today."},"timezone":{"type":"string","description":"The time zone used to read the dates and to group the rows."},"test":{"type":"boolean","description":"True when the report covers test mode data."},"type":{"type":"string","enum":["payments","refunds","combined"],"description":"Which transactions are counted. `payments` (the default), `refunds` (as negative amounts), or `combined` (payments net of refunds)."},"segment":{"type":"string","enum":["all","non_subscriptions","subscriptions","new_subscriptions","renewal_subscriptions"],"description":"Which sales are counted. `all` is the default."},"currency":{"type":"string","description":"The currency every amount is in: the account's primary reporting currency, or its secondary one when you asked for it with `currency`.","example":"USD"},"subtotal":{"allOf":[{"$ref":"#/components/schemas/report_stats"}],"description":"Statistics over the subtotal of each row, in `currency`."},"tax":{"allOf":[{"$ref":"#/components/schemas/report_stats"}],"description":"Statistics over the tax of each row, in `currency`."},"shipping":{"allOf":[{"$ref":"#/components/schemas/report_stats"}],"description":"Statistics over the shipping of each row, in `currency`."},"total":{"allOf":[{"$ref":"#/components/schemas/report_stats"}],"description":"Statistics over the total of each row, in `currency`."},"transaction_count":{"allOf":[{"$ref":"#/components/schemas/report_stats"}],"description":"Statistics over the number of transactions in each row."},"item_count":{"allOf":[{"$ref":"#/components/schemas/report_stats"}],"description":"Statistics over the number of items (quantity) in each row."},"data":{"type":"array","description":"One row per period when `group_by` is set, otherwise one row for the whole range.","items":{"type":"object","properties":{"date":{"type":["string","null"],"description":"The period, in the report time zone, cut to the grouping: `2026` for year, `2026-11` for month, `2026-11-06` for day, `2026-11-06T14:00` for hour. Null when there is no `group_by`."},"subtotal":{"type":"number","description":"The subtotal, in `currency`."},"shipping":{"type":"number","description":"The shipping, in `currency`."},"tax":{"type":"number","description":"The tax, in `currency`."},"total":{"type":"number","description":"The total, in `currency`."},"transaction_count":{"type":"integer","description":"How many transactions."},"item_count":{"type":"number","description":"How many items (sum of quantities)."},"formatted":{"type":"object","description":"The amounts as display text. Only present when `formatted=true`.","properties":{"subtotal":{"type":"string"},"shipping":{"type":"string"},"tax":{"type":"string"},"total":{"type":"string"}}}}}},"formatted":{"$ref":"#/components/schemas/report_formatted_dates"}}},"report_sales_summary":{"type":"object","title":"report_sales_summary","description":"Sales in a date range totalled per currency, or as one total converted into the `currency` you ask for.","properties":{"object":{"type":"string","enum":["report.sales_summary"],"description":"The object type. Always `report.sales_summary`."},"url":{"type":"string","format":"uri","description":"The URL that returns this report again, with the dates, filters and time zone it used."},"account_id":{"type":["string","null"],"description":"The account the report is for."},"date_created":{"type":"string","format":"date-time","description":"When the report was run, in the report time zone."},"date_start":{"type":["string","null"],"format":"date-time","description":"The start of the range the report covers, in the report time zone."},"date_end":{"type":["string","null"],"format":"date-time","description":"The end of the range the report covers, in the report time zone."},"timezone":{"type":"string","description":"The time zone used to read the dates."},"test":{"type":"boolean","description":"True when the report covers test mode data."},"type":{"type":["string","null"],"description":"Not filled in by core. Always null, even when you send `type`."},"data":{"type":"array","description":"One row per currency. When you send `currency`, one row with every currency converted into it.","items":{"type":"object","properties":{"currency":{"type":["string","null"],"description":"The currency of the amounts in this row: the settlement currency (the default) or the payment currency with `currency_type=payment`. Null on the converted row you get with `currency`."},"subtotal":{"type":"number","description":"The subtotal, in this row's currency."},"shipping":{"type":"number","description":"The shipping, in this row's currency."},"tax":{"type":"number","description":"The tax, in this row's currency."},"total":{"type":"number","description":"The total, in this row's currency."},"formatted":{"type":"object","description":"The amounts as display text. Only present when `formatted=true`.","properties":{"subtotal":{"type":"string"},"shipping":{"type":"string"},"tax":{"type":"string"},"total":{"type":"string"}}}}}},"formatted":{"$ref":"#/components/schemas/report_formatted_dates"}}},"report_tax":{"type":"object","title":"report_tax","description":"Taxed sales in a date range, totalled per currency, country and state or province. Only transactions with tax above zero are counted.","properties":{"object":{"type":"string","enum":["report.tax"],"description":"The object type. Always `report.tax`."},"url":{"type":"string","format":"uri","description":"The URL that returns this report again, with the dates, filters and time zone it used."},"account_id":{"type":["string","null"],"description":"The account the report is for."},"date_created":{"type":"string","format":"date-time","description":"When the report was run, in the report time zone."},"date_start":{"type":["string","null"],"format":"date-time","description":"The start of the range the report covers, in the report time zone."},"date_end":{"type":["string","null"],"format":"date-time","description":"The end of the range the report covers, in the report time zone."},"timezone":{"type":"string","description":"The time zone used to read the dates."},"test":{"type":"boolean","description":"True when the report covers test mode data."},"type":{"type":"string","enum":["payments","refunds","combined"],"description":"Which transactions are counted: `payments`, `refunds` (as negative amounts) or `combined` (payments net of refunds, the default)."},"data":{"type":"array","description":"One row per currency, tax country and tax state or province.","items":{"type":"object","properties":{"currency":{"type":"string","description":"The currency of the amounts in this row: the payment currency, or the settlement currency when `currency_type=settlement`."},"country":{"type":["string","null"],"description":"The two-letter country the tax was charged for."},"state_prov":{"type":["string","null"],"description":"The state or province the tax was charged for, if any."},"subtotal":{"type":"number","description":"The subtotal, in `currency`."},"shipping":{"type":"number","description":"The shipping, in `currency`."},"tax":{"type":"number","description":"The tax, in `currency`."},"total":{"type":"number","description":"The total, in `currency`."},"total_minus_tax":{"type":"number","description":"The total less the tax, in `currency`."},"formatted":{"type":"object","description":"The amounts as display text. Only present when `formatted=true`.","properties":{"subtotal":{"type":"string"},"shipping":{"type":"string"},"tax":{"type":"string"},"total":{"type":"string"},"total_minus_tax":{"type":"string"}}}}}},"formatted":{"$ref":"#/components/schemas/report_formatted_dates"}}},"role":{"type":"object","title":"role","description":"A named set of permissions that you give to users and secret tokens. Roles are kept per mode: a test token sees only test roles.","properties":{"object":{"type":"string","enum":["role"],"description":"The object type. Always `role`.","readOnly":true},"url":{"type":"string","format":"uri","description":"The URL of this role.","readOnly":true},"role_id":{"type":"string","description":"The role's ID. You may choose it when you create the role. Otherwise it is made from the name, in lower case with dashes for spaces.","readOnly":true},"date_created":{"type":"string","format":"date-time","description":"When the role was created.","readOnly":true},"date_modified":{"type":"string","format":"date-time","description":"When the role was last changed.","readOnly":true},"test":{"type":"boolean","description":"True for a test role.","readOnly":true},"account_id":{"type":"string","description":"The account the role belongs to.","readOnly":true},"name":{"type":"string","description":"The role's name.","maxLength":25},"comments":{"type":["string","null"],"description":"Your own notes about the role.","maxLength":150},"permission_type":{"type":["string","null"],"description":"An older label kept for roles that have one. Comecero does not use it."},"permissions":{"type":"array","description":"The permissions the role gives.","items":{"$ref":"#/components/schemas/role_permission"}},"formatted":{"type":"object","description":"Display text for the dates. Only present when you send `formatted=true`.","readOnly":true,"properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"}}}},"example":{"object":"role","url":"https://api.comecero.com/api/v1/roles/support","role_id":"support","date_created":"2026-10-01T14:36:52Z","date_modified":"2026-10-01T14:36:52Z","test":true,"account_id":"AB1234","name":"Support","comments":"Can look up and update orders and customers.","permission_type":null,"permissions":[{"resource":"orders","methods":["read","update"],"allow":true},{"resource":"customers","methods":["read"],"allow":true}]}},"role_list":{"title":"role_list","description":"An offset-based list of roles.","allOf":[{"$ref":"#/components/schemas/list_offset"},{"type":"object","properties":{"data":{"type":"array","description":"The roles on this page.","items":{"$ref":"#/components/schemas/role"}}}}]},"role_request":{"type":"object","title":"role_request","description":"A role and its permissions.","required":["name","permissions"],"properties":{"role_id":{"type":"string","description":"The ID for a new role, up to 25 characters of letters, numbers, underscores, dashes and periods. Leave it out to make one from the name. `400` if it is taken. When you replace a role, it is required and must match the URL.","maxLength":25},"name":{"type":"string","description":"The role's name. Required when you create a role.","maxLength":25},"comments":{"type":["string","null"],"description":"Your own notes about the role.","maxLength":150},"permissions":{"type":"array","description":"The permissions the role gives. At least one is required.","minItems":1,"items":{"$ref":"#/components/schemas/role_permission"}}},"example":{"name":"Support","comments":"Can look up and update orders and customers.","permissions":[{"resource":"orders","methods":["read","update"],"allow":true},{"resource":"customers","methods":["read"],"allow":true}]}},"settings_analytics":{"type":"object","title":"settings_analytics","description":"The analytics settings of the account in the current mode (test or live). They set the tracking code the hosted storefront adds to its pages and to the order receipt.","properties":{"object":{"type":"string","enum":["settings_analytics"],"description":"The object type. Always `settings_analytics`.","readOnly":true},"url":{"type":"string","format":"uri","description":"The URL of this object.","readOnly":true},"account_id":{"type":"string","description":"The ID of the account the settings belong to.","readOnly":true},"test":{"type":"boolean","description":"True for the test mode settings, false for live.","readOnly":true},"date_modified":{"type":"string","format":"date-time","description":"When the settings were last changed.","readOnly":true},"pageview_tracking":{"type":["string","null"],"description":"Your own JavaScript, run on every storefront page view.","maxLength":5000},"conversion_tracking":{"type":["string","null"],"description":"Your own JavaScript, run once when an order is completed.","maxLength":5000},"google_tracking_id":{"type":["string","null"],"description":"Deprecated. A Universal Analytics property ID in the form `UA-XXXXXX-XX`. Google has retired Universal Analytics: use `ga4_measurement_id`.","deprecated":true},"ga4_measurement_id":{"type":["string","null"],"description":"Your Google Analytics 4 measurement ID, in the form `G-XXXXXXXXXX` (in GA4 under Admin, Data Streams). When set, page views and purchases are sent to GA4.","pattern":"^[Gg]-[A-Za-z0-9]{6,}$"},"google_ads_id":{"type":["string","null"],"description":"Your Google Ads conversion ID, in the form `AW-123456789` (in Google Ads under Tools, Conversions). Used with `google_ads_label` to report purchases as conversions.","pattern":"^AW-[0-9]+$"},"google_ads_label":{"type":["string","null"],"description":"The Google Ads conversion label for purchases. Letters, numbers, underscores and hyphens only.","pattern":"^[A-Za-z0-9_-]+$"},"matomo_url":{"type":["string","null"],"format":"uri","description":"The HTTPS address of your own Matomo installation, for example `https://analytics.example.com` or `https://yoursite.matomo.cloud`."},"matomo_site_id":{"type":["integer","null"],"minimum":1,"description":"Your Matomo site ID."},"has_matomo_token_auth":{"type":"boolean","description":"True when a Matomo API token is saved. The token itself is never returned.","readOnly":true},"send_transactions":{"type":"boolean","description":"Send completed orders to your Matomo site as ecommerce transactions."},"send_events":{"type":"boolean","description":"Send shopper events (such as add to cart) to your Matomo site."},"formatted":{"type":"object","description":"Display text for the dates. Returned only when `formatted=true`.","readOnly":true,"properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"}}}},"example":{"object":"settings_analytics","url":"https://api.comecero.com/api/v1/settings/analytics","account_id":"AB1234","test":true,"date_modified":"2026-10-02T14:21:07Z","pageview_tracking":null,"conversion_tracking":null,"google_tracking_id":null,"ga4_measurement_id":"G-4X7KQ2M9PL","google_ads_id":"AW-123456789","google_ads_label":"AbC_dEfGh-12","matomo_url":null,"matomo_site_id":null,"has_matomo_token_auth":false,"send_transactions":false,"send_events":false}},"settings_analytics_request":{"type":"object","title":"settings_analytics_request","description":"The analytics fields to change. Send only the fields you want to change. Send a field as `null` or an empty string to clear it.","minProperties":1,"properties":{"pageview_tracking":{"type":["string","null"],"maxLength":5000,"description":"Your own JavaScript, run on every storefront page view."},"conversion_tracking":{"type":["string","null"],"maxLength":5000,"description":"Your own JavaScript, run once when an order is completed."},"google_tracking_id":{"type":["string","null"],"deprecated":true,"description":"Deprecated. A Universal Analytics ID in the form `UA-XXXXXX-XX`."},"ga4_measurement_id":{"type":["string","null"],"pattern":"^[Gg]-[A-Za-z0-9]{6,}$","description":"Your GA4 measurement ID, in the form `G-XXXXXXXXXX`."},"google_ads_id":{"type":["string","null"],"pattern":"^AW-[0-9]+$","description":"Your Google Ads conversion ID, in the form `AW-123456789`."},"google_ads_label":{"type":["string","null"],"pattern":"^[A-Za-z0-9_-]+$","description":"The Google Ads conversion label for purchases."},"matomo_url":{"type":["string","null"],"format":"uri","description":"The HTTPS address of your Matomo installation."},"matomo_site_id":{"type":["integer","null"],"minimum":1,"description":"Your Matomo site ID. Send `null` to clear it."},"matomo_token_auth":{"type":["string","null"],"writeOnly":true,"description":"A Matomo API token, used to read your Matomo reports into the dashboard. Write only: it is never returned. Send an empty string to remove it."},"send_transactions":{"type":"boolean","description":"Send completed orders to your Matomo site."},"send_events":{"type":"boolean","description":"Send shopper events to your Matomo site."}},"example":{"ga4_measurement_id":"G-4X7KQ2M9PL","google_ads_id":"AW-123456789","google_ads_label":"AbC_dEfGh-12"}},"settings_fraud":{"type":"object","title":"settings_fraud","description":"The fraud screening rules of the account in the current mode. A field that is `null` uses the platform default.","properties":{"object":{"type":"string","enum":["settings_fraud"],"description":"The object type. Always `settings_fraud`.","readOnly":true},"url":{"type":"string","format":"uri","description":"The URL of this object.","readOnly":true},"account_id":{"type":"string","description":"The ID of the account the settings belong to.","readOnly":true},"test":{"type":"boolean","description":"True for the test mode settings, false for live.","readOnly":true},"date_created":{"type":"string","format":"date-time","description":"When the settings were created.","readOnly":true},"date_modified":{"type":"string","format":"date-time","description":"When the settings were last changed.","readOnly":true},"enable_fraud_screening":{"type":["boolean","null"],"description":"Whether payments are scored for fraud before they are sent to the gateway."},"max_score":{"type":["number","null"],"minimum":0,"exclusiveMaximum":1,"description":"Payments that score at or above this value are blocked. From 0 up to (not including) 1. `0` turns score checks off. `null` uses the platform default."},"max_successful_payments":{"type":["integer","null"],"description":"The most successful payments one shopper may make in 24 hours. Further payments are refused. `null` uses the platform default."},"max_failed_payments":{"type":["integer","null"],"description":"The most failed payments one shopper may have in 24 hours. After that, no more payments are accepted. `null` uses the platform default."},"block_ip_country_mismatch":{"type":["boolean","null"],"description":"Block a payment when the shopper's IP country differs from the billing country."},"blocked_countries":{"type":["array","null"],"items":{"type":"string"},"description":"Two-letter ISO country codes to refuse payments from. `null` uses the platform list. An empty list blocks no countries."},"step_up_enabled":{"type":["boolean","null"],"description":"When on, a payment that scores between `max_score` and `step_up_max_score` is sent with a 3-D Secure challenge instead of being blocked. Set by Comecero only.","readOnly":true},"step_up_max_score":{"type":["number","null"],"description":"With `step_up_enabled`, the score from which a payment is blocked instead of challenged. Set by Comecero only.","readOnly":true},"formatted":{"type":"object","description":"Display text for the dates. Returned only when `formatted=true`.","readOnly":true,"properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"}}}},"example":{"object":"settings_fraud","url":"https://api.comecero.com/api/v1/settings/fraud","account_id":"AB1234","test":true,"date_created":"2026-01-12T09:30:00Z","date_modified":"2026-10-02T14:21:07Z","enable_fraud_screening":true,"max_score":0.6,"max_successful_payments":5,"max_failed_payments":3,"block_ip_country_mismatch":false,"blocked_countries":null,"step_up_enabled":null,"step_up_max_score":null}},"settings_fraud_request":{"type":"object","title":"settings_fraud_request","description":"The fraud fields to change. Send only the fields you want to change.","minProperties":1,"properties":{"enable_fraud_screening":{"type":["boolean","null"],"description":"Whether payments are scored for fraud."},"max_score":{"type":["number","null"],"minimum":0,"exclusiveMaximum":1,"description":"The block threshold, from 0 up to (not including) 1. `null` uses the default."},"max_successful_payments":{"type":["integer","null"],"description":"The most successful payments per shopper in 24 hours."},"max_failed_payments":{"type":["integer","null"],"description":"The most failed payments per shopper in 24 hours."},"block_ip_country_mismatch":{"type":["boolean","null"],"description":"Block when the IP country differs from the billing country."},"blocked_countries":{"type":["array","null"],"items":{"type":"string"},"description":"Two-letter ISO country codes to refuse. `null` uses the platform list."}},"example":{"max_score":0.6,"blocked_countries":["XX"]}},"settings_fulfillment":{"type":"object","title":"settings_fulfillment","description":"How the account captures payments and marks items as fulfilled, in the current mode.","properties":{"object":{"type":"string","enum":["settings_fulfillment"],"description":"The object type. Always `settings_fulfillment`.","readOnly":true},"url":{"type":"string","format":"uri","description":"The URL of this object.","readOnly":true},"account_id":{"type":"string","description":"The ID of the account the settings belong to.","readOnly":true},"test":{"type":"boolean","description":"True for the test mode settings, false for live.","readOnly":true},"date_modified":{"type":"string","format":"date-time","description":"When the settings were last changed.","readOnly":true},"auto_fulfill_items":{"type":"boolean","description":"Mark order items as fulfilled automatically. When false, you mark them yourself (for example with a shipment). Default false."},"auto_fulfill_delay":{"type":"integer","minimum":0,"maximum":168,"description":"With `auto_fulfill_items`, how many hours to wait before items are marked as fulfilled. From 0 to 168. Default 0."},"auto_capture":{"type":"boolean","description":"Capture payments automatically. When false, payments are only authorized and you capture them yourself. Default true."},"auto_capture_delay":{"type":"integer","minimum":0,"maximum":168,"description":"With `auto_capture`, how many hours to wait before a payment is captured. From 0 to 168. Default 0."},"low_inventory_notification":{"type":"number","description":"Send a low inventory notice when a product's stock falls to this number. Default 10. Saved as a whole number."},"formatted":{"type":"object","description":"Display text for the dates. Returned only when `formatted=true`.","readOnly":true,"properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"}}}},"example":{"object":"settings_fulfillment","url":"https://api.comecero.com/api/v1/settings/fulfillment","account_id":"AB1234","test":true,"date_modified":"2026-10-02T14:21:07Z","auto_fulfill_items":false,"auto_fulfill_delay":0,"auto_capture":true,"auto_capture_delay":0,"low_inventory_notification":10}},"settings_fulfillment_request":{"type":"object","title":"settings_fulfillment_request","description":"The fulfillment fields to change. Send only the fields you want to change.","minProperties":1,"properties":{"auto_fulfill_items":{"type":"boolean","description":"Mark order items as fulfilled automatically."},"auto_fulfill_delay":{"type":"integer","minimum":0,"maximum":168,"description":"Hours to wait before items are marked as fulfilled."},"auto_capture":{"type":"boolean","description":"Capture payments automatically."},"auto_capture_delay":{"type":"integer","minimum":0,"maximum":168,"description":"Hours to wait before a payment is captured."},"low_inventory_notification":{"type":"integer","description":"The stock level that triggers a low inventory notice."}},"example":{"auto_capture":true,"auto_capture_delay":24}},"settings_invoice_custom_field":{"type":"object","title":"settings_invoice_custom_field","description":"One extra field shown on every invoice.","required":["label"],"properties":{"key":{"type":"string","description":"The key the value is saved under in the invoice's `meta`. Lower case. If you leave it out, it is made from the label (`PO Number` becomes `po_number`). Keys must be unique: a repeat is dropped."},"label":{"type":"string","description":"The name shown on the invoice form, PDF and email. A field with no label is dropped."},"required":{"type":"boolean","description":"Whether the field must be filled in on the invoice."}}},"settings_general":{"type":"object","title":"settings_general","description":"General settings of the account in the current mode: reporting currencies, the addresses emails are sent from, document templates and custom invoice fields.","properties":{"object":{"type":"string","enum":["settings_general"],"description":"The object type. Always `settings_general`.","readOnly":true},"url":{"type":"string","format":"uri","description":"The URL of this object.","readOnly":true},"account_id":{"type":"string","description":"The ID of the account the settings belong to.","readOnly":true},"test":{"type":"boolean","description":"True for the test mode settings, false for live.","readOnly":true},"date_modified":{"type":"string","format":"date-time","description":"When the settings were last changed.","readOnly":true},"reporting_currency_primary":{"type":"string","description":"The main currency reports are shown in (ISO 4217 code). It is stored on every payment, so it cannot be changed after the first payment in this mode. Contact support if you need to change it."},"reporting_currency_secondary":{"type":"string","description":"A second reporting currency (ISO 4217 code). Like the primary, it is fixed after the first payment in this mode."},"notification_from_addresses":{"type":"array","items":{"type":"string","format":"email"},"description":"The email addresses your notifications may be sent from. Each new address gets a verification email. Accounts may have 1 address unless support raises the limit."},"cart_app_id":{"type":["string","null"],"description":"The ID of the installed app that serves the cart."},"invoice_app_id":{"type":["string","null"],"description":"The ID of the installed app that serves the invoice payment page."},"customer_admin_app_id":{"type":["string","null"],"description":"The ID of the installed app that serves the customer account pages."},"order_pdf_template_id":{"type":["string","null"],"description":"The ID of your template used for order PDFs. `null` uses the default."},"invoice_pdf_template_id":{"type":["string","null"],"description":"The ID of your template used for invoice PDFs. `null` uses the default."},"invoice_custom_fields":{"type":"array","maxItems":20,"description":"Extra fields shown on every invoice form, PDF and email, such as a PO number. The values for an invoice are kept in its `meta`, under each field's `key`.","items":{"$ref":"#/components/schemas/settings_invoice_custom_field"}},"formatted":{"type":"object","description":"Display text for the dates. Returned only when `formatted=true`.","readOnly":true,"properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"}}}},"example":{"object":"settings_general","url":"https://api.comecero.com/api/v1/settings/general","account_id":"AB1234","test":true,"date_modified":"2026-10-02T14:21:07Z","reporting_currency_primary":"USD","reporting_currency_secondary":"EUR","notification_from_addresses":["sales@example.com"],"cart_app_id":"comecero-shopping-cart","invoice_app_id":"comecero-shopping-cart","customer_admin_app_id":"comecero-customer-admin","order_pdf_template_id":null,"invoice_pdf_template_id":null,"invoice_custom_fields":[{"key":"po_number","label":"PO Number","required":false}]}},"settings_general_request":{"type":"object","title":"settings_general_request","description":"The general fields to change. Send only the fields you want to change.","minProperties":1,"properties":{"reporting_currency_primary":{"type":"string","description":"ISO 4217 currency code. Refused with `400` once the account has a payment in this mode."},"reporting_currency_secondary":{"type":"string","description":"ISO 4217 currency code. Refused with `400` once the account has a payment in this mode."},"notification_from_addresses":{"type":"array","items":{"type":"string","format":"email"},"description":"The full list of from addresses (it replaces the saved list). Each new address is sent a verification email. More addresses than your limit (1 by default), or removing an address a notification subscription still uses, returns `422`."},"cart_app_id":{"type":["string","null"],"description":"An installed app that accepts carts. Refused with `400` if the app is not installed or cannot take carts."},"invoice_app_id":{"type":["string","null"],"description":"An installed app that accepts invoice payments. Refused with `400` if the app is not installed or cannot take invoices."},"customer_admin_app_id":{"type":["string","null"],"description":"An installed app for the customer account pages."},"order_pdf_template_id":{"type":["string","null"],"description":"A template of yours in the same mode. A template from the other mode or another account returns `400`. Send `null` to use the default."},"invoice_pdf_template_id":{"type":["string","null"],"description":"Like `order_pdf_template_id`, for invoice PDFs."},"invoice_custom_fields":{"type":"array","description":"The full list of custom invoice fields (it replaces the saved list). Labels and keys are trimmed, blanks and repeated keys are dropped. More than 20 returns `422`.","items":{"$ref":"#/components/schemas/settings_invoice_custom_field"}}},"example":{"notification_from_addresses":["sales@example.com"],"invoice_custom_fields":[{"label":"PO Number","required":false}]}},"settings_currency_settlement_rule":{"type":"object","title":"settings_currency_settlement_rule","description":"Settle payments made in one currency in another.","required":["payment_currency","settlement_currency"],"properties":{"payment_currency":{"type":"string","description":"The currency the shopper pays in (ISO 4217)."},"settlement_currency":{"type":"string","enum":["USD"],"description":"The currency the payment settles in. Only `USD` is supported."}}},"settings_payment":{"type":"object","title":"settings_payment","description":"How the account takes payments in the current mode: card statement text, saved cards, currencies, duplicate and country checks, and the reasons offered for refunds and chargebacks.","properties":{"object":{"type":"string","enum":["settings_payment"],"description":"The object type. Always `settings_payment`.","readOnly":true},"url":{"type":"string","format":"uri","description":"The URL of this object.","readOnly":true},"account_id":{"type":"string","description":"The ID of the account the settings belong to.","readOnly":true},"test":{"type":"boolean","description":"True for the test mode settings, false for live.","readOnly":true},"date_created":{"type":"string","format":"date-time","description":"When the settings were created.","readOnly":true},"date_modified":{"type":"string","format":"date-time","description":"When the settings were last changed.","readOnly":true},"merchant_descriptor_name":{"type":["string","null"],"maxLength":18,"description":"The name on the customer's card statement. Card networks show up to 18 characters. `null` uses your company name."},"product_as_merchant_descriptor_name":{"type":"boolean","description":"For a cart payment, use the name of the first product as the statement name instead of `merchant_descriptor_name`."},"merchant_descriptor_contact":{"type":["string","null"],"maxLength":11,"description":"A phone number, web address or city on the card statement. Up to 11 characters."},"allow_save_cards":{"type":"boolean","description":"Whether this account may save cards on customers for later one-time payments. Set by Comecero: a value you send is ignored.","readOnly":true},"save_cards_by_default":{"type":"boolean","description":"Save the card on the customer when a payment does not say. Only changes when `allow_save_cards` is true."},"ignore_bad_cvv":{"type":"boolean","description":"Let a card payment succeed even when the CVV does not match."},"ignore_bad_avs":{"type":"boolean","description":"Let a card payment succeed even when the address check (AVS) does not match. Address checks are not enforced on the platform at present, so this has no effect today."},"duplicate_payment_timeout":{"type":"integer","minimum":0,"maximum":600,"description":"Seconds during which an exact repeat of a payment request is refused. From 0 to 600. `0` turns the check off (not recommended)."},"default_payment_currency":{"type":"string","description":"The currency (ISO 4217) used when a payment does not name one."},"default_settlement_currency":{"type":"string","description":"The currency (ISO 4217) payments settle in when no settlement rule matches."},"currency_settlement_rules":{"type":"array","description":"Which currency each payment currency settles in.","items":{"$ref":"#/components/schemas/settings_currency_settlement_rule"}},"customer_required_fields":{"type":"array","description":"Customer fields a shopper must fill in at checkout.","items":{"type":"string","enum":["name","company_name","email","phone","full_address","postal_code","country"]}},"customer_optional_fields":{"type":"array","description":"Customer fields offered at checkout but not required. A field cannot be in both lists.","items":{"type":"string","enum":["name","company_name","email","phone","credentials","full_address","postal_code","country"]}},"refund_reasons":{"type":"array","items":{"type":"string"},"description":"The reasons offered when someone issues a refund."},"chargeback_reasons":{"type":"array","items":{"type":"string"},"description":"The reasons offered when someone records a chargeback."},"blocked_countries":{"type":"array","maxItems":50,"items":{"type":"string"},"description":"Two-letter ISO country codes payments are refused from. Up to 50."},"max_gateway_attempts":{"type":["integer","null"],"minimum":1,"description":"When a card is declined and more than one gateway can take it, how many gateways to try in total. `null` means no limit: every gateway that can take the payment is tried. New accounts start at 2."},"formatted":{"type":"object","description":"Display text for the dates. Returned only when `formatted=true`.","readOnly":true,"properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"}}}},"example":{"object":"settings_payment","url":"https://api.comecero.com/api/v1/settings/payment","account_id":"AB1234","test":true,"date_created":"2026-01-12T09:30:00Z","date_modified":"2026-10-02T14:21:07Z","merchant_descriptor_name":"EXAMPLE STORE","product_as_merchant_descriptor_name":true,"merchant_descriptor_contact":"8005551234","allow_save_cards":true,"save_cards_by_default":false,"ignore_bad_cvv":true,"ignore_bad_avs":true,"duplicate_payment_timeout":120,"default_payment_currency":"USD","default_settlement_currency":"USD","currency_settlement_rules":[],"customer_required_fields":["name","email","country"],"customer_optional_fields":["phone"],"refund_reasons":["Customer request","Duplicate order"],"chargeback_reasons":["Fraudulent Charge","Merchandise Not Received","Other"],"blocked_countries":[],"max_gateway_attempts":2}},"settings_payment_request":{"type":"object","title":"settings_payment_request","description":"The payment fields to change. Send only the fields you want to change. Lists you send replace the saved list.","minProperties":1,"properties":{"merchant_descriptor_name":{"type":["string","null"],"maxLength":18,"description":"The name on the card statement. Up to 18 characters."},"product_as_merchant_descriptor_name":{"type":"boolean","description":"Use the first product name on the card statement."},"merchant_descriptor_contact":{"type":["string","null"],"maxLength":11,"description":"A phone number, web address or city on the statement. Up to 11 characters."},"save_cards_by_default":{"type":"boolean","description":"Save the card when a payment does not say. Ignored unless `allow_save_cards` is true on the account."},"ignore_bad_cvv":{"type":"boolean","description":"Let a payment succeed when the CVV does not match."},"ignore_bad_avs":{"type":"boolean","description":"Let a payment succeed when the address check does not match."},"duplicate_payment_timeout":{"type":"integer","minimum":0,"maximum":600,"description":"Seconds during which an exact repeat payment is refused. `0` turns it off."},"default_payment_currency":{"type":"string","description":"ISO 4217 currency code."},"default_settlement_currency":{"type":"string","description":"ISO 4217 currency code."},"currency_settlement_rules":{"type":["array","null"],"items":{"$ref":"#/components/schemas/settings_currency_settlement_rule"},"description":"The full list of settlement rules. `null` clears them."},"customer_required_fields":{"type":"array","items":{"type":"string","enum":["name","company_name","email","phone","full_address","postal_code","country"]},"description":"Customer fields a shopper must fill in. Repeats are removed."},"customer_optional_fields":{"type":"array","items":{"type":"string","enum":["name","company_name","email","phone","credentials","full_address","postal_code","country"]},"description":"Customer fields offered but not required. Must not overlap the required list."},"refund_reasons":{"type":"array","items":{"type":"string"},"description":"The reasons offered for a refund."},"chargeback_reasons":{"type":"array","items":{"type":"string"},"description":"The reasons offered for a chargeback."},"blocked_countries":{"type":"array","maxItems":50,"items":{"type":"string"},"description":"Two-letter ISO country codes to refuse. Up to 50."},"max_gateway_attempts":{"type":["integer","null"],"description":"When a card is declined and more than one gateway can take it, how many gateways to try in total. A value below 1, or `null`, means no limit: every gateway that can take the payment is tried. New accounts start at 2."}},"example":{"merchant_descriptor_name":"EXAMPLE STORE","duplicate_payment_timeout":120,"customer_required_fields":["name","email","country"]}},"settings_currency_rounding_rule":{"type":"object","title":"settings_currency_rounding_rule","description":"How a converted price is rounded in one currency, for example to end in .95 or .99.","required":["method","positions"],"properties":{"currency":{"type":["string","null"],"description":"The currency the rule is for (ISO 4217). `null` makes it the rule for every currency without its own rule."},"method":{"type":"string","enum":["highest","closest","lowest"],"description":"Round up to the next position, to the closest one, or down."},"minimum":{"type":"number","description":"Amounts below this are not rounded."},"positions":{"type":"array","minItems":1,"items":{"type":"number","minimum":0,"exclusiveMaximum":1},"description":"The endings to round to, as the part after the decimal point, for example `0`, `0.5`, `0.95`, `0.99`. Each from 0 up to (not including) 1. Saved sorted from low to high."},"date_created":{"type":"string","format":"date-time","description":"When the rule was saved. Set by Comecero.","readOnly":true}}},"settings_currency_markup_rule":{"type":"object","title":"settings_currency_markup_rule","description":"A markup added to the exchange rate when a price is converted into a currency.","required":["markup_percentage"],"properties":{"currency":{"type":["string","null"],"description":"The currency the rule is for (ISO 4217). `null` makes it the rule for every currency without its own rule."},"markup_percentage":{"type":"number","description":"The markup as a fraction. `0.03` is 3%."},"date_created":{"type":"string","format":"date-time","description":"When the rule was saved. Set by Comecero.","readOnly":true}}},"settings_pricing":{"type":"object","title":"settings_pricing","description":"How prices are converted into other currencies in the current mode: the markup on the exchange rate and how the result is rounded.","properties":{"object":{"type":"string","enum":["settings_pricing"],"description":"The object type. Always `settings_pricing`.","readOnly":true},"url":{"type":"string","format":"uri","description":"The URL of this object.","readOnly":true},"account_id":{"type":"string","description":"The ID of the account the settings belong to.","readOnly":true},"test":{"type":"boolean","description":"True for the test mode settings, false for live.","readOnly":true},"date_modified":{"type":"string","format":"date-time","description":"When the settings were last changed.","readOnly":true},"currency_rounding_rules":{"type":"array","description":"Rounding rules, one per currency, plus an optional default rule (`currency` null).","items":{"$ref":"#/components/schemas/settings_currency_rounding_rule"}},"currency_markup_rules":{"type":"array","description":"Exchange rate markups, one per currency, plus an optional default rule (`currency` null). With no rule, the markup is 3%.","items":{"$ref":"#/components/schemas/settings_currency_markup_rule"}},"formatted":{"type":"object","description":"Display text for the dates. Returned only when `formatted=true`.","readOnly":true,"properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"}}}},"example":{"object":"settings_pricing","url":"https://api.comecero.com/api/v1/settings/pricing","account_id":"AB1234","test":true,"date_modified":"2026-10-02T14:21:07Z","currency_rounding_rules":[{"currency":null,"method":"highest","minimum":3,"positions":[0,0.25,0.5,0.75,0.95,0.99],"date_created":"2026-10-02T14:21:07Z"}],"currency_markup_rules":[{"currency":null,"markup_percentage":0.03,"date_created":"2026-10-02T14:21:07Z"}]}},"settings_pricing_request":{"type":"object","title":"settings_pricing_request","description":"The pricing rules to change. Each list you send replaces the saved list.","minProperties":1,"properties":{"currency_rounding_rules":{"type":["array","null"],"items":{"$ref":"#/components/schemas/settings_currency_rounding_rule"},"description":"The full list of rounding rules."},"currency_markup_rules":{"type":"array","items":{"$ref":"#/components/schemas/settings_currency_markup_rule"},"description":"The full list of markup rules."}},"example":{"currency_markup_rules":[{"currency":null,"markup_percentage":0.03},{"currency":"JPY","markup_percentage":0.04}]}},"settings_shipping_price":{"type":"object","title":"settings_shipping_price","description":"A price in one currency.","required":["price","currency"],"properties":{"price":{"type":"number","minimum":0,"description":"The amount, in `currency`."},"currency":{"type":"string","description":"The currency (ISO 4217). Each currency may appear once in a list."},"formatted":{"type":"object","description":"Display text. Returned only when `formatted=true`.","readOnly":true,"properties":{"price":{"type":"string"}}}}},"settings_shipping_quantity_rule":{"type":"object","title":"settings_shipping_quantity_rule","description":"The price for orders with a number of items in a range. Ranges must not overlap. Gaps between ranges are closed when saved, and the lowest range starts at 1.","required":["minimum","maximum","prices"],"properties":{"minimum":{"type":"integer","minimum":0,"description":"The lowest item count in the range."},"maximum":{"type":"integer","minimum":0,"description":"The highest item count in the range."},"prices":{"type":"array","minItems":1,"description":"The price, in one or more currencies. A currency not listed is converted from the first.","items":{"$ref":"#/components/schemas/settings_shipping_price"}}}},"settings_shipping_subtotal_rule":{"type":"object","title":"settings_shipping_subtotal_rule","description":"Prices by order subtotal in one currency.","required":["currency","ranges"],"properties":{"currency":{"type":"string","description":"The currency (ISO 4217) of the subtotal ranges and prices. Each currency may appear once."},"ranges":{"type":"array","minItems":1,"description":"Subtotal ranges and their prices. Ranges must not overlap.","items":{"type":"object","required":["minimum","maximum","price"],"properties":{"minimum":{"type":"number","minimum":0,"description":"The lowest subtotal in the range, in `currency`."},"maximum":{"type":"number","minimum":0,"description":"The highest subtotal in the range, in `currency`."},"price":{"type":"number","minimum":0,"description":"The shipping price for this range, in `currency`."},"formatted":{"type":"object","description":"Display text. Returned only when `formatted=true`.","readOnly":true}}}}}},"settings_shipping_weight_rule":{"type":"object","title":"settings_shipping_weight_rule","description":"The price for orders with a total weight in a range. Ranges must not overlap.","required":["minimum","maximum","unit","prices"],"properties":{"minimum":{"type":"number","minimum":0,"description":"The lowest weight in the range."},"maximum":{"type":"number","minimum":0,"description":"The highest weight in the range."},"unit":{"type":"string","enum":["oz","lb","g","kg"],"description":"The unit of `minimum` and `maximum`."},"prices":{"type":"array","minItems":1,"description":"The price, in one or more currencies.","items":{"$ref":"#/components/schemas/settings_shipping_price"}}}},"settings_shipping_adjustment":{"type":"object","title":"settings_shipping_adjustment","description":"An extra charge on a method for some states or provinces. Give a percentage or fixed amounts, not both.","required":["country"],"properties":{"country":{"type":"string","enum":["US","CA"],"description":"The country. Must be one of the method's countries."},"regions":{"type":"array","items":{"type":"string"},"description":"State or province codes, such as `AK` or `HI`. A region may appear in only one adjustment of a method."},"percentage":{"type":["number","null"],"minimum":-1,"maximum":5,"description":"Change the price by this fraction. `0.2` adds 20%. From -1 (-100%) to 5 (500%)."},"amounts":{"type":["array","null"],"description":"A fixed amount added to the price, in one or more currencies. A currency not listed is converted from the first.","items":{"$ref":"#/components/schemas/settings_shipping_price"}}}},"settings_shipping_method":{"type":"object","title":"settings_shipping_method","description":"One shipping method in the shipping settings: the countries it serves and how its price is worked out. A method has exactly one set of rules: by quantity, by order subtotal or by weight.","properties":{"object":{"type":"string","enum":["settings_shipping.method"],"description":"The object type. Always `settings_shipping.method`.","readOnly":true},"url":{"type":"string","format":"uri","description":"The URL of this method.","readOnly":true},"method_id":{"type":"string","description":"The method ID. Comecero makes it from the description and countries when the method is created. It does not change after that.","readOnly":true},"description":{"type":"string","maxLength":75,"description":"The name the shopper sees, such as `Standard Shipping`. Up to 75 characters."},"details":{"type":["string","null"],"maxLength":125,"description":"More text for the shopper, such as delivery times. Up to 125 characters."},"countries":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"},"description":"Two-letter ISO country codes the method ships to, up to 50. Or `*` on its own for every country."},"quantity_rules":{"type":["array","null"],"description":"Prices by the number of items in the order.","items":{"$ref":"#/components/schemas/settings_shipping_quantity_rule"}},"subtotal_rules":{"type":["array","null"],"description":"Prices by the order subtotal, one entry per currency.","items":{"$ref":"#/components/schemas/settings_shipping_subtotal_rule"}},"weight_rules":{"type":["array","null"],"description":"Prices by the total weight of the order.","items":{"$ref":"#/components/schemas/settings_shipping_weight_rule"}},"adjustments":{"type":["array","null"],"description":"Extra charges for some states or provinces, such as Alaska and Hawaii. Only for the United States and Canada.","items":{"$ref":"#/components/schemas/settings_shipping_adjustment"}},"formatted":{"type":"object","description":"Display text. Returned only when `formatted=true`.","readOnly":true,"properties":{"countries":{"type":"array","items":{"type":"string"},"description":"The country names."}}}},"example":{"object":"settings_shipping.method","url":"https://api.comecero.com/api/v1/settings/shipping/methods/standard-shipping-us","method_id":"standard-shipping-us","description":"Standard Shipping","details":"Arrives in 3 to 5 business days.","countries":["US"],"quantity_rules":null,"subtotal_rules":[{"currency":"USD","ranges":[{"minimum":0,"maximum":49.99,"price":5},{"minimum":50,"maximum":999999,"price":0}]}],"weight_rules":null,"adjustments":[{"country":"US","regions":["AK","HI"],"percentage":null,"amounts":[{"price":10,"currency":"USD"}]}]}},"settings_shipping":{"type":"object","title":"settings_shipping","description":"The shipping settings of the account in the current mode, with every shipping method.","properties":{"object":{"type":"string","enum":["settings_shipping"],"description":"The object type. Always `settings_shipping`.","readOnly":true},"url":{"type":"string","format":"uri","description":"The URL of this object.","readOnly":true},"account_id":{"type":"string","description":"The ID of the account the settings belong to.","readOnly":true},"test":{"type":"boolean","description":"True for the test mode settings, false for live.","readOnly":true},"date_created":{"type":"string","format":"date-time","description":"When the settings were created.","readOnly":true},"date_modified":{"type":"string","format":"date-time","description":"When the settings were last changed.","readOnly":true},"methods":{"type":"array","description":"The shipping methods, sorted by `method_id`.","items":{"$ref":"#/components/schemas/settings_shipping_method"}},"formatted":{"type":"object","description":"Display text for the dates. Returned only when `formatted=true`.","readOnly":true,"properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"}}}},"example":{"object":"settings_shipping","url":"https://api.comecero.com/api/v1/settings/shipping","account_id":"AB1234","test":true,"date_created":"2026-01-12T09:30:00Z","date_modified":"2026-10-02T14:21:07Z","methods":[{"object":"settings_shipping.method","url":"https://api.comecero.com/api/v1/settings/shipping/methods/standard-shipping-us","method_id":"standard-shipping-us","description":"Standard Shipping","details":null,"countries":["US"],"quantity_rules":null,"subtotal_rules":[{"currency":"USD","ranges":[{"minimum":0,"maximum":49.99,"price":5},{"minimum":50,"maximum":99.99,"price":10},{"minimum":100,"maximum":999999,"price":15}]}],"weight_rules":null,"adjustments":null}]}},"settings_shipping_method_request":{"type":"object","title":"settings_shipping_method_request","description":"A shipping method. Send `description`, `countries` and exactly one of `quantity_rules`, `subtotal_rules` or `weight_rules`. This is checked on update too, so an update must send them again.","required":["description","countries"],"properties":{"description":{"type":"string","maxLength":75,"description":"The name the shopper sees. Up to 75 characters."},"details":{"type":["string","null"],"maxLength":125,"description":"More text for the shopper. Up to 125 characters."},"countries":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"},"description":"Two-letter ISO country codes, up to 50, or `*` on its own for every country."},"quantity_rules":{"type":"array","items":{"$ref":"#/components/schemas/settings_shipping_quantity_rule"},"description":"Prices by item count."},"subtotal_rules":{"type":"array","items":{"$ref":"#/components/schemas/settings_shipping_subtotal_rule"},"description":"Prices by order subtotal."},"weight_rules":{"type":"array","items":{"$ref":"#/components/schemas/settings_shipping_weight_rule"},"description":"Prices by order weight."},"adjustments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/settings_shipping_adjustment"},"description":"Extra charges for some US states or Canadian provinces."}},"example":{"description":"Standard Shipping","details":"Arrives in 3 to 5 business days.","countries":["US"],"subtotal_rules":[{"currency":"USD","ranges":[{"minimum":0,"maximum":49.99,"price":5},{"minimum":50,"maximum":999999,"price":0}]}]}},"settings_shipping_request":{"type":"object","title":"settings_shipping_request","description":"Replace every shipping method at once. To change one method, use the shipping method endpoints instead.","properties":{"methods":{"type":"array","description":"The full list of methods. It replaces every saved method, and each gets a new `method_id`. An empty list removes all methods.","items":{"$ref":"#/components/schemas/settings_shipping_method_request"}}},"example":{"methods":[{"description":"Standard Shipping","countries":["*"],"quantity_rules":[{"minimum":1,"maximum":999,"prices":[{"price":7.5,"currency":"USD"}]}]}]}},"settings_shipping_method_list":{"title":"settings_shipping_method_list","description":"An offset-based list of shipping methods.","allOf":[{"$ref":"#/components/schemas/list_offset"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/settings_shipping_method"}}}}],"example":{"total_items":1,"total_pages":1,"current_page":1,"next_page_url":null,"next_page_offset":null,"previous_page_url":null,"previous_page_offset":null,"current_page_url":"https://api.comecero.com/api/v1/settings/shipping/methods","data":[{"object":"settings_shipping.method","url":"https://api.comecero.com/api/v1/settings/shipping/methods/standard-shipping-us","method_id":"standard-shipping-us","description":"Standard Shipping","details":"Arrives in 3 to 5 business days.","countries":["US"],"quantity_rules":null,"subtotal_rules":[{"currency":"USD","ranges":[{"minimum":0,"maximum":49.99,"price":5},{"minimum":50,"maximum":999999,"price":0}]}],"weight_rules":null,"adjustments":null}]}},"settings_storefront_document":{"type":"object","title":"settings_storefront_document","description":"The storefront settings document, in groups. The storefront owns the fields in each group and may add new ones. Every value is checked for length, list size and depth. Addresses must be `http`, `https` or a path on the shop.","properties":{"version":{"type":"integer","description":"The document version. Set by Comecero.","readOnly":true},"brand":{"type":"object","description":"Shop name, logos and favicon.","additionalProperties":true},"theme":{"type":"object","description":"Colors, fonts, corner radius and header and footer layout. `mode` is `standard` or `custom`. Colors are CSS color values.","additionalProperties":true},"content":{"type":"object","description":"The home page sections (`hero`, `featured`, `grid`, `text`, `banner`) and other page text.","additionalProperties":true},"seo":{"type":"object","description":"Page titles, descriptions and the social sharing image.","additionalProperties":true},"shop":{"type":"object","description":"Catalog and product page options.","additionalProperties":true},"checkout":{"type":"object","description":"Cart and checkout options, such as label position, how errors are shown, and when up-sells and cross-sells appear.","additionalProperties":true},"pay":{"type":"object","description":"Invoice payment page options.","additionalProperties":true},"embed":{"type":"object","description":"Options for the checkout embedded in your own site.","additionalProperties":true},"account":{"type":"object","description":"Customer account page options.","additionalProperties":true},"languages":{"type":"object","description":"The languages the shop offers.","additionalProperties":true},"custom":{"type":"object","description":"Custom CSS and JavaScript run on the shop's pages. Only the account owner may change it.","additionalProperties":true},"flags":{"type":"object","description":"Feature flags. Set by Comecero only.","readOnly":true,"additionalProperties":true},"source":{"type":"object","description":"Where the values came from. `kind` is `storefront`, `legacy` or `default`. Set by Comecero.","readOnly":true,"additionalProperties":true}},"additionalProperties":true},"settings_storefront":{"type":"object","title":"settings_storefront","description":"The hosted storefront's settings in the current mode: one document used by the shop, cart, checkout, payment page and customer account, and the switch that says whether the shop's own addresses show the storefront.","properties":{"object":{"type":"string","enum":["settings_storefront"],"description":"The object type. Always `settings_storefront`.","readOnly":true},"url":{"type":"string","format":"uri","description":"The URL of this object.","readOnly":true},"account_id":{"type":"string","description":"The ID of the account the settings belong to.","readOnly":true},"test":{"type":"boolean","description":"True for the test mode settings, false for live.","readOnly":true},"date_created":{"type":"string","format":"date-time","description":"When the settings were first saved.","readOnly":true},"date_modified":{"type":"string","format":"date-time","description":"When the document or the switch last changed.","readOnly":true},"modified_by":{"type":["string","null"],"description":"The ID of the user who last changed the document or the switch.","readOnly":true},"enabled":{"type":"boolean","description":"The shop's switch. True when its own addresses show the storefront."},"live":{"type":"boolean","description":"True when the shop's addresses show the storefront: its own switch is on, or Comecero shows the storefront for every shop.","readOnly":true},"managed":{"type":"boolean","description":"True when Comecero shows the storefront for every shop. The shop's own switch then decides nothing.","readOnly":true},"date_enabled":{"type":["string","null"],"format":"date-time","description":"When the switch was turned on. `null` while it is off.","readOnly":true},"can_switch":{"type":"boolean","description":"Whether the caller may turn the switch on or off.","readOnly":true},"can_edit_code":{"type":"boolean","description":"Whether the caller may change the custom CSS and JavaScript.","readOnly":true},"has_settings":{"type":"boolean","description":"Whether a settings document has been saved.","readOnly":true},"settings":{"oneOf":[{"$ref":"#/components/schemas/settings_storefront_document"},{"type":"null"}],"description":"The settings document. `null` until it is first saved."},"storefront_url":{"type":["string","null"],"format":"uri","description":"Where the shop's storefront answers now. `null` when the shop has no host.","readOnly":true},"preview_url":{"type":["string","null"],"format":"uri","description":"The storefront's own address for the shop, where the document can be seen before the switch is on.","readOnly":true},"hosts":{"type":"array","items":{"type":"string"},"description":"The shop's host names, from the technical settings (`app_hosts`).","readOnly":true},"platform_apps":{"type":"array","description":"The Comecero apps the account has installed that the storefront replaces.","readOnly":true,"items":{"type":"object","properties":{"app_id":{"type":"string"},"alias":{"type":"string"},"name":{"type":["string","null"]},"version":{"type":["string","null"]},"key":{"type":"string","enum":["cart","pop","hpp","account"],"description":"Which storefront part replaces the app."}}}},"own_apps":{"type":"array","description":"Apps of your own that are installed. They are served as before.","readOnly":true,"items":{"type":"object","properties":{"app_id":{"type":"string"},"alias":{"type":"string"},"name":{"type":["string","null"]},"version":{"type":["string","null"]},"type":{"type":["string","null"]}}}},"alias_conflicts":{"type":"array","items":{"type":"string"},"description":"Aliases of your own apps that would hide a storefront page. Give each a different alias before you turn the switch on.","readOnly":true},"formatted":{"type":"object","description":"Display text for the dates. Returned only when `formatted=true`.","readOnly":true,"properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"}}}},"example":{"object":"settings_storefront","url":"https://api.comecero.com/api/v1/settings/storefront","account_id":"AB1234","test":true,"date_created":"2026-09-28T10:02:44Z","date_modified":"2026-10-02T14:21:07Z","modified_by":"1000","enabled":true,"live":true,"managed":false,"date_enabled":"2026-10-02T14:21:07Z","can_switch":true,"can_edit_code":true,"has_settings":true,"settings":{"version":1,"brand":{"name":"Example Store","logo":"https://cdn.example.com/logo.png"},"theme":{"mode":"standard","primary":"#1F6FEB"},"source":{"kind":"storefront"}},"storefront_url":"https://example.apps.comecero.com","preview_url":"https://example.shop.comecero.com","hosts":["example.apps.comecero.com"],"platform_apps":[{"app_id":"comecero-shopping-cart","alias":"cart","name":"Shopping Cart","version":"3.1.60","key":"cart"}],"own_apps":[],"alias_conflicts":[]}},"settings_storefront_request":{"type":"object","title":"settings_storefront_request","description":"Change the storefront document, the switch, or both. Send only what you want to change.","minProperties":1,"properties":{"settings":{"oneOf":[{"$ref":"#/components/schemas/settings_storefront_document"},{"type":"null"}],"description":"The groups to change. A group you send is merged field by field (a list replaces the list). A group sent as `null` goes back to the defaults. A group you leave out is kept. Send `settings: null` to discard the whole document; you must switch the shop off first. Changing `custom` needs the account owner (`403` otherwise), and `flags` cannot be changed."},"enabled":{"type":"boolean","description":"Turn the switch on or off. Only the account owner may do this (`403` otherwise). Turning it on needs a saved document (`422`), and none of your own apps on an address the storefront uses (`409`)."}},"example":{"settings":{"brand":{"name":"Example Store"},"theme":{"primary":"#1F6FEB"}}}},"settings_subscription":{"type":"object","title":"settings_subscription","description":"How subscriptions renew in the current mode: reminders, retries after a failed payment, what customers may change themselves, and renewal emails.","properties":{"object":{"type":"string","enum":["settings_subscription"],"description":"The object type. Always `settings_subscription`.","readOnly":true},"url":{"type":"string","format":"uri","description":"The URL of this object.","readOnly":true},"account_id":{"type":"string","description":"The ID of the account the settings belong to.","readOnly":true},"test":{"type":"boolean","description":"True for the test mode settings, false for live.","readOnly":true},"date_modified":{"type":"string","format":"date-time","description":"When the settings were last changed.","readOnly":true},"copy_affiliate_id_on_subscription_renewal":{"type":"boolean","description":"Copy the affiliate ID of the first order onto renewal orders."},"subscription_renewal_notification_days":{"type":"integer","minimum":0,"maximum":30,"description":"Days before a renewal to send the customer a reminder. `0` sends none. Default 3."},"subscription_invoice_payment_delay":{"type":"integer","minimum":0,"maximum":168,"description":"Hours between creating the renewal invoice and charging it, so you can change the invoice first. From 0 to 168. Default 0."},"payment_retry_delay":{"type":"integer","minimum":1,"description":"Days between tries after a renewal payment fails. Default 3."},"allow_deep_payment_retries":{"type":"boolean","description":"When a retried payment succeeds, also queue up to three more open past due invoices of the same subscription for payment."},"max_payment_attempts":{"type":"integer","minimum":1,"description":"The most tries for a failed renewal payment. Default 4."},"payment_retry_friday_bias":{"type":"boolean","description":"Move a retry that falls one day either side of a Friday to the Friday."},"cancel_on_chargeback":{"type":"boolean","description":"Cancel the subscription when a chargeback is recorded on its payment."},"allow_customer_subscription_cancel":{"type":"boolean","description":"Let customers cancel their own subscriptions. On accounts where Comecero is the seller, only Comecero can turn this off; a value you send is ignored."},"allow_customer_subscription_downgrade":{"type":"boolean","description":"Let customers move to a cheaper product or a lower quantity."},"allow_customer_subscription_upgrade":{"type":"boolean","description":"Let customers move to a more expensive product or a higher quantity."},"use_customer_payment_currency":{"type":"boolean","description":"When the customer pays in a currency the product has no price for, keep the subscription in the customer's currency. When false, use the product's default price currency."},"receipt_on_renewal":{"type":"boolean","description":"Email a receipt for each renewal payment."},"digital_delivery_on_renewal":{"type":"boolean","description":"Send the downloads and license keys again on each renewal."},"cancellation_reasons":{"type":"array","maxItems":25,"items":{"type":"string","maxLength":50},"description":"The reasons offered when a subscription is cancelled. Up to 25, each up to 50 characters."},"immediate_upgrade_product_types":{"type":"array","items":{"type":"string","enum":["digital","physical","service","bundle"]},"description":"Product types whose upgrades apply at once. Other upgrades apply at the end of the billing period."},"immediate_downgrade_product_types":{"type":"array","items":{"type":"string","enum":["digital","physical","service","bundle"]},"description":"Product types whose downgrades apply at once."},"formatted":{"type":"object","description":"Display text for the dates. Returned only when `formatted=true`.","readOnly":true,"properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"}}}},"example":{"object":"settings_subscription","url":"https://api.comecero.com/api/v1/settings/subscription","account_id":"AB1234","test":true,"date_modified":"2026-10-02T14:21:07Z","copy_affiliate_id_on_subscription_renewal":false,"subscription_renewal_notification_days":3,"subscription_invoice_payment_delay":0,"payment_retry_delay":3,"allow_deep_payment_retries":true,"max_payment_attempts":4,"payment_retry_friday_bias":true,"allow_customer_subscription_cancel":true,"allow_customer_subscription_downgrade":true,"allow_customer_subscription_upgrade":true,"use_customer_payment_currency":false,"cancel_on_chargeback":true,"receipt_on_renewal":true,"digital_delivery_on_renewal":true,"cancellation_reasons":["Too expensive","No longer needed"],"immediate_upgrade_product_types":["digital","service"],"immediate_downgrade_product_types":[]}},"settings_subscription_request":{"type":"object","title":"settings_subscription_request","description":"The subscription fields to change. Send only the fields you want to change.","minProperties":1,"properties":{"copy_affiliate_id_on_subscription_renewal":{"type":"boolean","description":"Copy the affiliate ID onto renewal orders."},"subscription_renewal_notification_days":{"type":"integer","minimum":0,"maximum":30,"description":"Days before a renewal to send a reminder. `0` sends none."},"subscription_invoice_payment_delay":{"type":"integer","minimum":0,"maximum":168,"description":"Hours between creating and charging a renewal invoice."},"payment_retry_delay":{"type":"integer","minimum":1,"description":"Days between payment retries."},"allow_deep_payment_retries":{"type":"boolean","description":"Also pay older past due invoices after a successful retry."},"max_payment_attempts":{"type":"integer","minimum":1,"description":"The most tries for a failed renewal payment."},"payment_retry_friday_bias":{"type":"boolean","description":"Move retries near a Friday to the Friday."},"cancel_on_chargeback":{"type":"boolean","description":"Cancel the subscription on a chargeback."},"allow_customer_subscription_cancel":{"type":"boolean","description":"Let customers cancel. Ignored on accounts where Comecero is the seller."},"allow_customer_subscription_downgrade":{"type":"boolean","description":"Let customers downgrade."},"allow_customer_subscription_upgrade":{"type":"boolean","description":"Let customers upgrade."},"use_customer_payment_currency":{"type":"boolean","description":"Keep the subscription in the customer's payment currency."},"receipt_on_renewal":{"type":"boolean","description":"Email a receipt for each renewal."},"digital_delivery_on_renewal":{"type":"boolean","description":"Send downloads and license keys again on each renewal."},"cancellation_reasons":{"type":"array","maxItems":25,"items":{"type":"string","maxLength":50},"description":"The full list of cancellation reasons."},"immediate_upgrade_product_types":{"type":"array","items":{"type":"string","enum":["digital","physical","service","bundle"]},"description":"Product types whose upgrades apply at once."},"immediate_downgrade_product_types":{"type":"array","items":{"type":"string","enum":["digital","physical","service","bundle"]},"description":"Product types whose downgrades apply at once."}},"example":{"payment_retry_delay":2,"max_payment_attempts":5}},"settings_tax_rule":{"type":"object","title":"settings_tax_rule","description":"A tax rule for a country, state or tax code.","required":["country"],"properties":{"country":{"type":"string","description":"Two-letter ISO country code, or `EU` for every EU country."},"state_prov":{"type":["string","null"],"description":"State or province code. Required for the United States. Only for countries that tax at state level."},"location_postal_code":{"type":["string","null"],"description":"A US zip code inside the state, used to find the local rate."},"rate":{"type":["number","null"],"minimum":0,"exclusiveMaximum":1,"description":"The rate as a fraction: `0.1` is 10%. `null` looks the rate up automatically, which works for the United States, Canada and the EU only."},"tax_code":{"type":["string","null"],"description":"Apply the rule only to products with this tax code. No spaces. Each country, state and tax code mix may appear once."}}},"settings_tax":{"type":"object","title":"settings_tax","description":"Tax settings of the account in the current mode: where prices include tax, where discounts apply before tax, and your own tax rules.","properties":{"object":{"type":"string","enum":["settings_tax"],"description":"The object type. Always `settings_tax`.","readOnly":true},"url":{"type":"string","format":"uri","description":"The URL of this object.","readOnly":true},"account_id":{"type":"string","description":"The ID of the account the settings belong to.","readOnly":true},"test":{"type":"boolean","description":"True for the test mode settings, false for live.","readOnly":true},"date_modified":{"type":"string","format":"date-time","description":"When the settings were last changed.","readOnly":true},"tax_inclusive_countries":{"type":"array","items":{"type":"string"},"description":"Countries where your prices already include tax. Two-letter ISO codes, `EU` for every EU country, or `*` for every country."},"gross_discount_countries":{"type":"array","items":{"type":"string"},"description":"Countries where discounts are taken off the price including tax. Two-letter ISO codes, `EU` or `*`."},"rules":{"type":"array","description":"Your own tax rules. Only accounts that sell as themselves (not through Comecero as the seller) use them.","items":{"$ref":"#/components/schemas/settings_tax_rule"}},"formatted":{"type":"object","description":"Display text for the dates. Returned only when `formatted=true`.","readOnly":true,"properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"}}}},"example":{"object":"settings_tax","url":"https://api.comecero.com/api/v1/settings/tax","account_id":"AB1234","test":true,"date_modified":"2026-10-02T14:21:07Z","tax_inclusive_countries":["EU"],"gross_discount_countries":[],"rules":[{"country":"US","state_prov":"WA","location_postal_code":null,"rate":null,"tax_code":null},{"country":"AU","state_prov":null,"location_postal_code":null,"rate":0.1,"tax_code":null}]}},"settings_tax_request":{"type":"object","title":"settings_tax_request","description":"The tax fields to change. Send only the fields you want to change. Each list you send replaces the saved list; an empty list or `null` clears it.","minProperties":1,"properties":{"tax_inclusive_countries":{"type":["array","null"],"items":{"type":"string"},"description":"Two-letter ISO codes, `EU` or `*`."},"gross_discount_countries":{"type":["array","null"],"items":{"type":"string"},"description":"Two-letter ISO codes, `EU` or `*`."},"rules":{"type":["array","null"],"items":{"$ref":"#/components/schemas/settings_tax_rule"},"description":"The full list of tax rules. Ignored on accounts where Comecero is the seller, since Comecero handles the tax."}},"example":{"tax_inclusive_countries":["EU","GB"]}},"settings_technical":{"type":"object","title":"settings_technical","description":"Technical settings of the account in the current mode: time zone, shop addresses, the webhook signing key, OAuth redirect addresses and CORS.","properties":{"object":{"type":"string","enum":["settings_technical"],"description":"The object type. Always `settings_technical`.","readOnly":true},"url":{"type":"string","format":"uri","description":"The URL of this object.","readOnly":true},"account_id":{"type":"string","description":"The ID of the account the settings belong to.","readOnly":true},"test":{"type":"boolean","description":"True for the test mode settings, false for live.","readOnly":true},"date_modified":{"type":"string","format":"date-time","description":"When the settings were last changed.","readOnly":true},"timezone":{"type":["string","null"],"description":"The time zone for reports and dates, as an IANA name such as `America/New_York`. `null` uses UTC."},"app_hosts":{"type":"array","minItems":1,"maxItems":3,"items":{"type":"string"},"description":"The host names your shop answers on, up to 3. The first is the default. After 10 changes, contact support to change them again."},"app_alias_redirects":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Send requests for one app alias to another, as an object of old alias to new alias, such as `{\"old-cart\": \"cart\"}`."},"signature_key":{"type":["string","null"],"maxLength":64,"description":"The key Comecero signs outbound requests with (webhook events and license service calls), so you can check they came from Comecero. Letters and digits only, up to 64. Keep it secret."},"oauth_redirect_uris":{"type":"array","maxItems":20,"items":{"type":"string","format":"uri"},"description":"The redirect addresses allowed for OAuth sign-in to your apps. Up to 20."},"cors_allowed_origins":{"type":"array","maxItems":15,"items":{"type":"string"},"description":"Web origins allowed to call the API from a browser, up to 15. Scheme and host only, such as `https://www.example.com`, with no trailing slash. Live mode needs `https`; test mode allows `http` too."},"allow_public_limited_test_tokens":{"type":"boolean","description":"Let anyone get a limited test mode token for this account without first holding one of your tokens."},"formatted":{"type":"object","description":"Display text for the dates. Returned only when `formatted=true`.","readOnly":true,"properties":{"date_created":{"type":"string"},"date_modified":{"type":"string"}}}},"example":{"object":"settings_technical","url":"https://api.comecero.com/api/v1/settings/technical","account_id":"AB1234","test":true,"date_modified":"2026-10-02T14:21:07Z","timezone":"America/New_York","app_hosts":["example.apps.comecero.com"],"app_alias_redirects":null,"signature_key":"7f3K9pQx2LmN8vB4","oauth_redirect_uris":["https://www.example.com/oauth/callback"],"cors_allowed_origins":["https://www.example.com"],"allow_public_limited_test_tokens":false}},"settings_technical_request":{"type":"object","title":"settings_technical_request","description":"The technical fields to change. Send only the fields you want to change. Lists you send replace the saved list.","minProperties":1,"properties":{"timezone":{"type":["string","null"],"description":"An IANA time zone name."},"app_hosts":{"type":"array","minItems":1,"maxItems":3,"items":{"type":"string"},"description":"Between 1 and 3 host names; the first is the default. A host another account uses returns `409`. After 10 changes, further changes return `400`."},"app_alias_redirects":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Alias redirects. An alias may not point to itself."},"signature_key":{"type":["string","null"],"maxLength":64,"pattern":"^[A-Za-z0-9]*$","description":"Letters and digits only, up to 64."},"oauth_redirect_uris":{"type":["array","null"],"maxItems":20,"items":{"type":"string","format":"uri"},"description":"Fully qualified addresses, including `http://` or `https://`."},"cors_allowed_origins":{"type":["array","null"],"maxItems":15,"items":{"type":"string"},"description":"Scheme and host only. `https` in live mode."},"allow_public_limited_test_tokens":{"type":"boolean","description":"Let anyone get a limited test token for the account."}},"example":{"cors_allowed_origins":["https://www.example.com","https://shop.example.com"]}},"shipment_update_request":{"type":"object","title":"shipment_update_request","description":"The fields you may change on a shipment. The items cannot be changed: delete the shipment and create a new one instead. The body cannot be empty. The `shipment:modified` event fires.","properties":{"date_shipped":{"type":"string","format":"date-time","description":"When the parcel left or will leave."},"courier":{"type":["string","null"],"maxLength":50,"description":"The carrier."},"tracking_number":{"type":["string","null"],"description":"The tracking number."},"tracking_url":{"type":["string","null"],"maxLength":256,"description":"The tracking page."},"meta":{"description":"Your own data for the shipment, a string or an object. At most 2048 characters once serialized.","type":["object","string","null"]}},"example":{"tracking_number":"1Z999AA10123456799"}},"shipping_method_quantity_config":{"title":"shipping_method_quantity_config","type":"object","description":"Prices shipping by the number of units in the cart.","properties":{"prices_per_quantity":{"type":"array","minItems":1,"description":"The price for each unit, one per currency. At least one is required.","items":{"$ref":"#/components/schemas/price"}},"rules":{"type":"array","description":"Flat prices for ranges of quantity. Ranges must not overlap, and `minimum` must not be more than `maximum`.","items":{"type":"object","properties":{"minimum":{"type":"integer","minimum":0},"maximum":{"type":"integer","minimum":0},"prices":{"type":"array","items":{"$ref":"#/components/schemas/price"}}}}}}},"shipping_method_subtotal_config":{"title":"shipping_method_subtotal_config","type":"object","description":"Prices shipping by the cart subtotal.","properties":{"percent_of_subtotal":{"type":["number","null"],"minimum":0,"maximum":3,"description":"Shipping as a fraction of the subtotal, from 0 to 3 (300%). A range in `rules` that matches the subtotal wins. This fraction is used only when no range matches, or when there are no `rules`. When it is not set and no range matches, the price of a nearby range is used."},"rules":{"type":"array","description":"Price ranges by subtotal, one entry per currency. Each currency may appear once.","items":{"type":"object","properties":{"currency":{"type":"string","description":"The currency of the subtotal and prices in `ranges`."},"ranges":{"type":"array","minItems":1,"items":{"type":"object","properties":{"minimum":{"type":"number","minimum":0,"description":"The lowest subtotal for this range."},"maximum":{"type":"number","minimum":0,"description":"The highest subtotal for this range."},"price":{"type":"number","minimum":0,"description":"The shipping price for a subtotal in this range."}}}}}}}}},"shipping_method_weight_config":{"title":"shipping_method_weight_config","type":"object","description":"Prices shipping by the total weight of the cart.","properties":{"unit":{"type":"string","enum":["oz","lb","g","kg"],"description":"The weight unit of `prices_per_unit`."},"prices_per_unit":{"type":"array","minItems":1,"description":"The price for each unit of weight, one per currency. At least one is required.","items":{"$ref":"#/components/schemas/price"}},"rules":{"type":"array","description":"Flat prices for ranges of weight. Ranges must not overlap. Rules are stored in grams, so they come back with `unit: g`.","items":{"type":"object","properties":{"minimum":{"type":"number","minimum":0},"maximum":{"type":"number","minimum":0},"unit":{"type":"string","enum":["oz","lb","g","kg"]},"prices":{"type":"array","items":{"$ref":"#/components/schemas/price"}}}}}}},"shipping_method":{"type":"object","title":"shipping_method","description":"A way to ship an order, with its price rules. Shoppers pick one at checkout from the methods that ship to their country.","properties":{"object":{"type":"string","enum":["shipping_method"],"description":"The object type. Always `shipping_method`."},"url":{"type":"string","format":"uri","description":"The URL of this shipping method in the API."},"shipping_method_id":{"type":"string","description":"The id of the shipping method, made from its description when it was created."},"test":{"type":"boolean","description":"True for a test-mode shipping method."},"account_id":{"type":"string","description":"The account the shipping method belongs to."},"date_created":{"type":"string","format":"date-time","description":"When the shipping method was created."},"date_modified":{"type":"string","format":"date-time","description":"When the shipping method was last changed."},"description":{"type":"string","maxLength":75,"description":"The name shoppers see, for example `Standard Shipping`."},"details":{"type":["string","null"],"maxLength":125,"description":"More text shown with the method, such as delivery times."},"countries":{"type":"array","minItems":1,"maxItems":50,"description":"The two-letter ISO codes of the countries the method ships to, up to 50, or `[\"*\"]` for every country. `*` cannot be mixed with codes.","items":{"type":"string"}},"quantity_config":{"description":"Prices by quantity, or null. Exactly one of the three configs must be set.","anyOf":[{"$ref":"#/components/schemas/shipping_method_quantity_config"},{"type":"null"}]},"subtotal_config":{"description":"Prices by subtotal, or null. Exactly one of the three configs must be set.","anyOf":[{"$ref":"#/components/schemas/shipping_method_subtotal_config"},{"type":"null"}]},"weight_config":{"description":"Prices by weight, or null. Exactly one of the three configs must be set.","anyOf":[{"$ref":"#/components/schemas/shipping_method_weight_config"},{"type":"null"}]},"adjustments":{"type":["array","null"],"description":"Extra charges for some regions, for example Alaska and Hawaii. Only for the United States and Canada, and only for countries in `countries`.","items":{"type":"object","properties":{"country":{"type":"string","enum":["US","CA"],"description":"The country of the regions."},"regions":{"type":"array","description":"The state or province codes the adjustment applies to.","items":{"type":"string"}},"percentage":{"type":["number","null"],"minimum":-1,"maximum":5,"description":"A change to the price as a fraction, from -1 (-100%) to 5 (500%). Give this or `amounts`, not both."},"amounts":{"type":["array","null"],"description":"An amount added to the price, one per currency.","items":{"$ref":"#/components/schemas/price"}}}}},"formatted":{"type":"object","description":"Present only when you send `formatted=true`.","additionalProperties":true}},"required":["object","url","shipping_method_id","test","account_id","date_created","date_modified","description","details","countries","quantity_config","subtotal_config","weight_config","adjustments"],"example":{"object":"shipping_method","url":"https://api.comecero.com/api/v1/shipping_methods/Standard-Shipping","shipping_method_id":"Standard-Shipping","test":true,"account_id":"AB1234","date_created":"2026-11-02T20:13:16Z","date_modified":"2026-11-02T20:13:16Z","description":"Standard Shipping","details":"Arrives in 3 to 5 business days.","countries":["US"],"quantity_config":null,"subtotal_config":{"percent_of_subtotal":null,"rules":[{"currency":"USD","ranges":[{"minimum":0,"maximum":49.99,"price":5},{"minimum":50,"maximum":999999,"price":0}]}]},"weight_config":null,"adjustments":null}},"shipping_method_list":{"type":"object","title":"shipping_method_list","description":"A page of shipping methods. An offset-based list.","properties":{"total_items":{"type":"integer","description":"The number of items that match, across all pages."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The number of this page."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The items on this page.","items":{"$ref":"#/components/schemas/shipping_method"}}},"required":["total_items","total_pages","current_page","next_page_url","next_page_offset","previous_page_url","previous_page_offset","current_page_url","data"]},"shipping_method_request":{"type":"object","title":"shipping_method_request","description":"The fields of a shipping method. `description`, `countries` and exactly one of `quantity_config`, `subtotal_config` and `weight_config` are required, on update as well as on create.","properties":{"description":{"type":"string","maxLength":75,"description":"The name shoppers see, for example `Standard Shipping`."},"details":{"type":["string","null"],"maxLength":125,"description":"More text shown with the method, such as delivery times."},"countries":{"type":"array","minItems":1,"maxItems":50,"description":"The two-letter ISO codes of the countries the method ships to, up to 50, or `[\"*\"]` for every country. `*` cannot be mixed with codes.","items":{"type":"string"}},"quantity_config":{"description":"Prices by quantity, or null. Exactly one of the three configs must be set.","anyOf":[{"$ref":"#/components/schemas/shipping_method_quantity_config"},{"type":"null"}]},"subtotal_config":{"description":"Prices by subtotal, or null. Exactly one of the three configs must be set.","anyOf":[{"$ref":"#/components/schemas/shipping_method_subtotal_config"},{"type":"null"}]},"weight_config":{"description":"Prices by weight, or null. Exactly one of the three configs must be set.","anyOf":[{"$ref":"#/components/schemas/shipping_method_weight_config"},{"type":"null"}]},"adjustments":{"type":["array","null"],"description":"Extra charges for some regions, for example Alaska and Hawaii. Only for the United States and Canada, and only for countries in `countries`.","items":{"type":"object","properties":{"country":{"type":"string","enum":["US","CA"],"description":"The country of the regions."},"regions":{"type":"array","description":"The state or province codes the adjustment applies to.","items":{"type":"string"}},"percentage":{"type":["number","null"],"minimum":-1,"maximum":5,"description":"A change to the price as a fraction, from -1 (-100%) to 5 (500%). Give this or `amounts`, not both."},"amounts":{"type":["array","null"],"description":"An amount added to the price, one per currency.","items":{"$ref":"#/components/schemas/price"}}}}}},"required":["description","countries"],"example":{"description":"Standard Shipping","details":"Arrives in 3 to 5 business days.","countries":["US"],"subtotal_config":{"rules":[{"currency":"USD","ranges":[{"minimum":0,"maximum":49.99,"price":5},{"minimum":50,"maximum":999999,"price":0}]}]}}},"subscription_plan_list":{"type":"object","title":"subscription_plan_list","description":"An offset-based page of subscription plans.","properties":{"total_items":{"type":"integer","description":"The number of items in the whole list."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The page number of this page, starting at 1."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The plans on this page.","items":{"$ref":"#/components/schemas/subscription_plan"}}},"required":["total_items","total_pages","current_page","next_page_url","next_page_offset","previous_page_url","previous_page_offset","current_page_url","data"]},"subscription_plan_request":{"type":"object","title":"subscription_plan_request","description":"A new subscription plan.","properties":{"name":{"type":"string","minLength":1,"maxLength":75,"description":"The plan name, for your own reference."},"description":{"type":"string","maxLength":256,"description":"A description, for your own reference."},"billing_interval":{"type":"integer","minimum":1,"description":"How many `billing_interval_unit` make one billing period. Maximum: 365 days, 24 months, 2 years, 24 hours, 60 minutes (minute plans need at least 5)."},"billing_interval_unit":{"type":"string","enum":["day","month","year","hour","minute"],"description":"The unit of the billing period. `hour` and `minute` are only allowed with a test token, and `minute` only outside production."},"end_at_billing_count":{"type":["integer","null"],"minimum":1,"description":"Stop billing after this many billings. Leave it out or send `null` to bill until cancelled."},"trial_interval":{"type":["integer","null"],"minimum":1,"description":"The trial length in `trial_interval_unit`. Maximum: 365 days, 12 months, 1 year, 24 hours, 60 minutes. Leave it out or send `null` for no trial."},"trial_interval_unit":{"type":["string","null"],"enum":["day","month","year","hour","minute",null],"description":"The unit of the trial. Required when `trial_interval` is sent."},"meta":{"description":"Any data you want to store on the plan, up to 2,048 characters."}},"required":["name","billing_interval","billing_interval_unit"],"example":{"name":"Monthly, 14-day trial","billing_interval":1,"billing_interval_unit":"month","trial_interval":14,"trial_interval_unit":"day"}},"subscription_plan_update_request":{"type":"object","title":"subscription_plan_update_request","description":"Changes to a subscription plan. Send only the fields to change. Existing subscriptions keep the values they copied when they were made.","properties":{"name":{"type":"string","maxLength":75,"description":"The plan name."},"description":{"type":"string","maxLength":256,"description":"A description."},"billing_interval":{"type":"integer","minimum":1,"description":"How many `billing_interval_unit` make one billing period. Same limits as on create."},"billing_interval_unit":{"type":"string","enum":["day","month","year","hour","minute"],"description":"The unit of the billing period. `hour` and `minute` only with a test token."},"end_at_billing_count":{"type":["integer","null"],"minimum":1,"description":"Stop billing after this many billings. `null` removes the limit."},"trial_interval":{"type":["integer","null"],"minimum":1,"description":"The trial length. `null` removes the trial (and its unit)."},"trial_interval_unit":{"type":["string","null"],"enum":["day","month","year","hour","minute",null],"description":"The unit of the trial. `null` removes the trial."},"meta":{"description":"Any data you want to store on the plan. Replaces the old value."}},"example":{"name":"Monthly, 30-day trial","trial_interval":30}},"subscription_list":{"type":"object","title":"subscription_list","description":"A cursor-based page of subscriptions.","properties":{"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_after_item":{"type":["string","null"],"description":"The `after_item` value for the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_before_item":{"type":["string","null"],"description":"The `before_item` value for the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The subscriptions on this page.","items":{"$ref":"#/components/schemas/subscription"}}},"required":["next_page_url","next_page_after_item","previous_page_url","previous_page_before_item","current_page_url","data"]},"subscription_options":{"type":"object","title":"subscription_options","description":"Choices to show when a subscription is managed, such as the cancellation reasons set in your subscription settings.","properties":{"account_id":{"type":"string","description":"The account."},"test":{"type":"boolean","description":"`true` when read with a test token."},"cancellation_reasons":{"type":"array","description":"The cancellation reasons from your subscription settings. Send one as `cancellation_reason` when you cancel. Empty when none are set.","items":{"type":"string"}}},"required":["account_id","test","cancellation_reasons"],"example":{"account_id":"AB1234","test":true,"cancellation_reasons":["Too expensive","No longer needed","Switching to another product"]}},"subscription_update_request":{"type":"object","title":"subscription_update_request","description":"Changes to a subscription. Only the fields below are applied. To change items, use the item endpoints. To cancel, `POST /subscriptions/{subscription_id}/cancel` is simpler.","properties":{"status":{"type":"string","enum":["cancelled"],"description":"Send `cancelled` to cancel at once. Only allowed when the status is `active` or `trial`. Cannot be sent with `cancel_at_current_period_end`."},"cancel_at_current_period_end":{"type":"boolean","description":"`true` schedules cancellation at the end of the current billing period and emails the customer a cancellation notice. `false` removes a scheduled cancellation. Only allowed when the status is `active` or `trial`."},"cancellation_reason":{"type":"string","maxLength":75,"description":"Why the subscription is cancelled. Only saved when the subscription is cancelled or scheduled to be cancelled."},"subscription_plan_id":{"type":"string","description":"Cannot be changed. If sent, it must match the current plan."},"meta":{"description":"Any data you want to store on the subscription, up to 2,048 characters. Replaces the old value."}},"example":{"cancel_at_current_period_end":true,"cancellation_reason":"No longer needed"}},"subscription_cancel_request":{"type":"object","title":"subscription_cancel_request","description":"How to cancel. The body is optional: with no body the cancellation is scheduled for the end of the current billing period.","properties":{"cancel_at_current_period_end":{"type":"boolean","default":true,"description":"`true` (the default) keeps billing until the end of the current period, then cancels. `false` cancels at once."},"cancellation_reason":{"type":["string","null"],"maxLength":75,"description":"Why it is cancelled. You can offer the reasons from `GET /subscriptions/options`."}},"example":{"cancel_at_current_period_end":false,"cancellation_reason":"Too expensive"}},"subscription_extend_request":{"type":"object","title":"subscription_extend_request","description":"How long to push back the next billing. During a trial the trial is extended; otherwise the current billing period is.","properties":{"interval":{"type":"integer","minimum":1,"description":"How many `interval_unit` to add."},"interval_unit":{"type":"string","enum":["minute","hour","day","month"],"description":"The unit of `interval`. `year` is not allowed."}},"required":["interval","interval_unit"],"example":{"interval":7,"interval_unit":"day"}},"subscription_change_summary":{"type":"object","title":"subscription_change_summary","description":"What a change to a subscription's items would do: what the customer pays or gets back now, when the change takes effect and the new billing terms. Returned by the preview endpoints. Nothing is changed and no money moves.","properties":{"object":{"type":"string","enum":["subscription_change_summary"],"description":"The object type. Always `subscription_change_summary`."},"payment_total":{"type":"number","description":"The prorated amount the customer would pay now, in `currency`. `0` when the change is scheduled for the period end."},"refund_total":{"type":"number","description":"The prorated amount the customer would get back now, in `currency`. A refund goes to the original payment method where possible, otherwise to the customer's account balance."},"net_total":{"type":"number","description":"`payment_total` minus `refund_total`, in `currency`."},"currency":{"type":"string","description":"The subscription currency."},"date_next_payment":{"type":"string","format":"date-time","description":"When the next regular renewal is billed."},"date_effective":{"type":"string","format":"date-time","description":"When the change takes effect, always in UTC. To apply exactly the previewed amounts, send this value back as `date_effective` with `apply_immediately: true`."},"generates_new_subscription":{"type":"boolean","description":"`true` when the change moves the item to a product on a different subscription plan, which makes a new subscription."},"apply_at_period_end":{"type":"boolean","description":"`true` when the change is scheduled for the end of the current billing period."},"subscription_terms":{"$ref":"#/components/schemas/subscription_terms"},"formatted":{"type":"object","description":"Display text for the totals and dates. Only with `formatted=true`."}},"required":["object","payment_total","refund_total","net_total","currency","date_next_payment","date_effective","generates_new_subscription","apply_at_period_end","subscription_terms"],"example":{"object":"subscription_change_summary","payment_total":13.3,"refund_total":0,"net_total":13.3,"currency":"USD","date_next_payment":"2026-12-02T15:21:28Z","date_effective":"2026-11-12T10:00:00Z","generates_new_subscription":false,"apply_at_period_end":false,"subscription_terms":{"object":"subscription_terms","price":19.95,"quantity":2,"currency":"USD","discount":0,"discount_price":null,"discount_apply_count":null,"discount_applied_count":0,"tax_inclusve":false,"billing_interval":1,"billing_interval_unit":"month","billing_interval_description":"1 month","trial_interval":null,"trial_interval_unit":null,"trial_interval_description":null,"date_trial_start":null,"date_trial_end":null,"end_at_billing_count":null,"date_billing_start":"2026-10-02T15:21:28Z","subscription_id":"0093799318129SuLByRPW8","description":"Acme Pro (monthly) is a subscription that renews every month with a payment of $19.95, per quantity.","price_per_day":0.66,"price_per_month":19.95,"price_per_year":239.4}}},"subscription_item_update_request":{"type":"object","title":"subscription_item_update_request","description":"Changes to one subscription item. A change to quantity, price or discount is applied at once (with a prorated charge or refund) or scheduled for the end of the period, by the same rules as adding an item.","properties":{"quantity":{"type":"integer","minimum":1,"description":"The new quantity. More is an upgrade, less is a downgrade. A limited token may only do this when your subscription settings allow customer upgrades or downgrades."},"reference_price":{"type":"number","description":"The new unit price, in `reference_currency`. Unless your account uses the agent model, you can lower the price but not raise it. A limited token may not send it (`403`)."},"reference_currency":{"type":"string","minLength":3,"maxLength":3,"description":"The new currency of `reference_price`. A limited token may not send it (`403`)."},"reference_discount":{"type":"number","minimum":0,"description":"The new discount per unit. Unless your account uses the agent model, you can raise the discount but not lower it. `0` removes it. A limited token may not send it (`403`)."},"discount_apply_count":{"type":["integer","null"],"description":"How many billings the discount applies to. Unless your account uses the agent model, it cannot be lowered. A limited token may not send it (`403`)."},"apply_immediately":{"type":"boolean","description":"`true` applies the change now, `false` schedules it for the period end. The default comes from the immediate upgrade and downgrade product types in your subscription settings. Sending a value other than the default needs permission to update subscription settings. A limited token may not send it (`403`)."},"date_effective":{"type":"string","format":"date-time","description":"Only with `apply_immediately`. The UTC time the change counts from. At most one hour in the past and not before the current period start."},"change_at_current_period_end":{"type":"null","description":"Send `null` to remove a scheduled change. Ignored for a limited token."},"cancellation_reason":{"type":"string","maxLength":75,"description":"Only saved when the item is cancelled or scheduled to be cancelled. Ignored for a limited token."},"meta":{"description":"Any data you want to store on the item. Replaces the old value. Ignored for a limited token."}},"example":{"quantity":2}},"subscription_notification_list":{"type":"object","title":"subscription_notification_list","description":"An offset-based page of the notifications (emails) sent about a subscription.","properties":{"total_items":{"type":"integer","description":"The number of items in the whole list."},"total_pages":{"type":"integer","description":"The number of pages."},"current_page":{"type":"integer","description":"The page number of this page, starting at 1."},"next_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the next page, or null on the last page."},"next_page_offset":{"type":["integer","null"],"description":"The `offset` of the next page, or null on the last page."},"previous_page_url":{"type":["string","null"],"format":"uri","description":"The URL of the previous page, or null on the first page."},"previous_page_offset":{"type":["integer","null"],"description":"The `offset` of the previous page, or null on the first page."},"current_page_url":{"type":"string","format":"uri","description":"The URL of this page."},"data":{"type":"array","description":"The notifications on this page.","items":{"$ref":"#/components/schemas/notification"}}},"required":["total_items","total_pages","current_page","next_page_url","next_page_offset","previous_page_url","previous_page_offset","current_page_url","data"]},"template_list":{"title":"template_list","description":"An offset-based page of templates.","allOf":[{"$ref":"#/components/schemas/list_offset"},{"type":"object","properties":{"data":{"type":"array","description":"The templates on this page.","items":{"$ref":"#/components/schemas/template"}}}}]},"template_request":{"type":"object","title":"template_request","description":"The fields you can set on a template. On create, `body` is required. On update, send only the fields to change.","properties":{"body":{"type":"string","description":"The Handlebars source, at most 128 kB (UTF-8)."},"default_subject":{"type":["string","null"],"writeOnly":true,"description":"The subject a notification subscription uses when it sets none. It is saved but not returned when you read the template."},"wrapper_template_id":{"type":["string","null"],"description":"The id of a template to place this one inside. It must be in your account, and templates may not wrap or embed each other in a loop (`400`)."},"expand":{"type":["string","null"],"description":"Comma-separated child objects of the data to expand."},"show":{"type":["string","null"],"description":"Comma-separated fields of the data to keep."},"hide":{"type":["string","null"],"description":"Comma-separated fields of the data to leave out."},"comments":{"type":["string","null"],"maxLength":256,"description":"Your own notes."},"template_type":{"type":["string","null"],"enum":["email","pdf",null],"description":"`email` (the default) or `pdf`. A PDF template cannot be changed back (`400`)."},"pdf_type":{"type":["string","null"],"description":"For a PDF template, what it renders, such as `invoice` or `order`."},"page_format":{"type":["string","null"],"description":"For a PDF template, the page size, such as `A4` or `Letter`."},"orientation":{"type":["string","null"],"description":"For a PDF template, `portrait` or `landscape`."},"margin_top":{"type":["integer","null"],"description":"For a PDF template, the top margin."},"margin_bottom":{"type":["integer","null"],"description":"For a PDF template, the bottom margin."},"margin_left":{"type":["integer","null"],"description":"For a PDF template, the left margin."},"margin_right":{"type":["integer","null"],"description":"For a PDF template, the right margin."}},"example":{"body":"<p>Hi {{customer.first_name}}, your download is ready: {{download_url}}</p>","default_subject":"Your download is ready","comments":"Download email"}},"template_build":{"type":"object","title":"template_build","description":"A template filled with your data.","properties":{"data":{"type":"string","description":"The rendered output, usually HTML, with CSS inlined."}},"example":{"data":"<p>Hi John, your download is ready: https://example.com/downloads/abc123</p>"}},"user_list":{"title":"user_list","description":"An offset-based list of users.","allOf":[{"$ref":"#/components/schemas/list_offset"},{"type":"object","properties":{"data":{"type":"array","description":"The users on this page.","items":{"$ref":"#/components/schemas/user"}}}}]},"user_request":{"type":"object","title":"user_request","description":"A new user.","required":["user_id","name","email","password"],"properties":{"user_id":{"type":"string","description":"The sign-in name: at least 5 and up to 100 characters, made of letters, numbers, underscores, dashes and periods. It is stored in lower case. In test mode `.test` is added to the end if it is not there. `409` if it is taken.","minLength":5,"maxLength":100},"name":{"type":"string","description":"The user's full name.","maxLength":75},"email":{"type":"string","format":"email","description":"The user's email address. It must not belong to another user of the account, test or live (`409`).","maxLength":100},"password":{"type":"string","format":"password","description":"The password, from 8 to 50 characters.","minLength":8,"maxLength":50,"writeOnly":true},"language":{"type":"string","description":"A two-letter ISO 639-1 language code."},"allow_test_transactions":{"type":"boolean","description":"True when the user may work in test mode. The default is `true`.","default":true},"roles":{"type":"array","description":"The `role_id` of each role to give the user. Each must exist (`400`).","items":{"type":"string"}},"permissions":{"type":"array","description":"Permissions to give the user directly.","items":{"$ref":"#/components/schemas/role_permission"}},"meta":{"description":"Your own data about the user, any JSON up to 2,048 characters.","type":["object","null"],"additionalProperties":true}},"example":{"user_id":"jane.smith","name":"Jane Smith","email":"jane@example.com","password":"correct-horse-battery","roles":["support"]}},"user_update_request":{"type":"object","title":"user_update_request","description":"The fields to change. Fields you leave out keep their value. A `roles` or `permissions` list you send replaces the old one; an empty list is ignored.","properties":{"name":{"type":"string","description":"The user's full name.","maxLength":75},"email":{"type":"string","format":"email","description":"The user's email address. It must not belong to another user of the account (`409`). The old address is told about the change.","maxLength":100},"password":{"type":"string","format":"password","description":"A new password, from 8 to 50 characters.","minLength":8,"maxLength":50,"writeOnly":true},"language":{"type":"string","description":"A two-letter ISO 639-1 language code."},"allow_test_transactions":{"type":"boolean","description":"True when the user may work in test mode. Ignored on `/users/me`."},"roles":{"type":"array","description":"The `role_id` of each role to give the user. Ignored on `/users/me`.","items":{"type":"string"}},"permissions":{"type":"array","description":"Permissions to give the user directly. Ignored on `/users/me`.","items":{"$ref":"#/components/schemas/role_permission"}},"is_account_owner":{"type":"boolean","description":"Makes the user an owner, or not. Only a trusted token of a user who is an owner can change it. From any other token it is ignored. Ignored on `/users/me`."},"meta":{"description":"Your own data about the user, any JSON up to 2,048 characters. Ignored on `/users/me`.","type":["object","null"],"additionalProperties":true}},"example":{"name":"Jane Smith-Jones","roles":["support","fulfillment"]}}},"responses":{"BadRequest":{"description":"Invalid input (type `bad_request`, usually code `invalid_input`). The message names the field or query parameter and why it was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"},"example":{"error":{"type":"bad_request","code":"invalid_input","message":"The value supplied for the url query string parameter 'limit' is invalid. The value must be between 1 and 100 or remove the parameter to use the default.","reference":"2mJgF4F","status":400,"meta":null}}}}},"Unauthorized":{"description":"The token is missing, expired or not valid (type `unauthorized`, code `invalid_token`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"},"example":{"error":{"type":"unauthorized","code":"invalid_token","message":"Authentication failed.","reference":"pre3XcJ","status":401,"meta":null}}}}},"Forbidden":{"description":"The token is valid but may not do this (type `forbidden`, code `insufficient_permissions`). For example a limited token on a route only secret and trusted tokens may call, or a token whose role lacks the permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"},"example":{"error":{"type":"forbidden","code":"insufficient_permissions","message":"The supplied bearer token does not have permission to execute the provided HTTP method on the given resource.","reference":"AxkklBY","status":403,"meta":null}}}}},"NotFound":{"description":"No such object (type `not_found`, code `resource_not_found`). It may belong to another account, or to the other mode: a test token cannot see live objects and a live token cannot see test ones. The message says so when the object exists in the other mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"},"example":{"error":{"type":"not_found","code":"resource_not_found","message":"Event not found: 0059847953278fQmIZHpIYdE does not exist.","reference":"qh81SPw","status":404,"meta":null}}}}},"ServerError":{"description":"Something failed on our side (type `internal_server_error`). Reads are safe to retry. Before you retry a write, get the object to check whether the first attempt took effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"},"example":{"error":{"type":"internal_server_error","code":"500","message":"An error occured while processing your request. Your request cannot be completed. If the problem persists, please contact support.","reference":"UjXiEpm","status":500,"meta":null}}}}},"Conflict":{"description":"The request clashes with the object's state or with another object (type `conflict`, code such as `in_use` or `duplicate`). For example a second active subscription of a kind that allows only one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"},"example":{"error":{"type":"conflict","code":"in_use","message":"There is already an active notification subscription of the same type in your account. Each notification type can have no more than one active subscription.","reference":"3RggedA","status":409,"meta":null}}}}},"Unprocessable":{"description":"The request is valid but cannot be done now (type `unprocessable`, code such as `invalid_state` or `account_limit_exceeded`). The message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"},"example":{"error":{"type":"unprocessable","code":"invalid_state","message":"This notification cannot be sent because a product in the order is awaiting a license. It will be automatically sent when the license is obtained.","reference":"ofWoxxY","status":422,"meta":null}}}}},"WebhookReceived":{"description":"Answer with any 2xx status within 60 seconds to mark the event `delivered`; the body is ignored. Anything else counts as a failure: another status (redirects are not followed), a timeout, or no connection. After a failure Comecero retries on a growing schedule: three times 2 minutes apart, then every 15 minutes, every hour, every 2 hours, every 4 hours and every 8 hours, 23 attempts over about 56 hours in all. Then the event is `failed` and is not tried again by itself; you can send it again with `POST /events/{event_id}/retry` while it is kept. Events are kept for 30 days after their last change, and for 7 days once delivered or in test mode. Deliveries can arrive more than once and out of order, so use `event_id` to skip repeats and compare `date_created` or get the object fresh before you overwrite newer data. Each event subscription gets its own copy: the same occurrence shares one `fingerprint` across subscriptions."}},"requestBodies":{"payment_request":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_request"},"examples":{"card":{"summary":"Pay a cart or invoice with a new card","value":{"customer":{"name":"John Smith","email":"john@example.com","billing_address":{"address_1":"1 Main St","city":"High Point","state_prov":"NC","postal_code":"27265","country":"US"}},"payment_method":{"type":"credit_card","data":{"number":"4444555566661111","exp_month":12,"exp_year":2030,"cvv":"123","cardholder_name":"John Smith"}}}},"saved_method":{"summary":"Pay with a saved payment method","value":{"customer_id":"0091304300408CuoxY9Pf3","payment_method_id":"0092503470929PmEP0ivO4"}},"amount":{"summary":"Charge an amount with no cart (POST /payments)","value":{"currency":"USD","total":25,"description":"Setup fee","customer_id":"0091304300408CuoxY9Pf3","payment_method_id":"0092503470929PmEP0ivO4"}}}}},"description":"A payment request object.","required":true},"refund_request":{"required":false,"description":"Optional. Leave the body out, or send `{}`, for a full refund of everything not refunded yet. Send amounts or items for a partial refund.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/refund_request"},"examples":{"full":{"summary":"Full refund (no body)","value":{}},"items":{"summary":"Refund one item","value":{"items":[{"item_id":"1","quantity":1}],"reason":"Customer request"}},"amount":{"summary":"Refund an amount","value":{"total":10,"reason":"Partial refund for a late delivery"}}}}}},"product_request":{"description":"The new product. `name`, `type` and at least one price in `prices` are required.","required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/product_request"},{"required":["name","type","prices"]}]},"examples":{"minimal":{"summary":"Name, type and one price","value":{"name":"Widget","type":"physical","prices":[{"price":49.95,"currency":"USD"}]}},"digital":{"summary":"A download product","value":{"product_id":"widget-pro","name":"Widget Pro","type":"digital","prices":[{"price":99,"currency":"USD"}],"file_id":"0095012700001FiQ2xT7Ab"}},"full":{"summary":"With prices, stock and translations","value":{"product_id":"widget","name":"Widget","type":"physical","description":"A simple widget for everyday use.","headline":"The widget you will use every day","prices":[{"price":49.95,"currency":"USD"},{"price":45.95,"currency":"EUR"}],"compare_at_prices":[{"price":59.95,"currency":"USD"}],"volume_prices":[{"low":10,"prices":[{"price":39.95,"currency":"USD"}]}],"weight":{"amount":3,"unit":"lb"},"active":true,"hidden":false,"image_ids":["0099844605810ImLAMbo73"],"inventory":{"current":120,"allow_oversells":false,"low_quantity_notification":10},"translations":{"de":{"name":"Widget","headline":"Das Widget fur jeden Tag","description":"Ein einfaches Widget fur jeden Tag."}}}}}}}}}},"x-tagGroups":[{"name":"Catalog","tags":["products","subscription_plans","promotions","shipping_methods","license_services"]},{"name":"Checkout","tags":["carts","payments","invoices"]},{"name":"After the sale","tags":["orders","refunds","subscriptions","shipments","licenses","license_requests","downloads"]},{"name":"Customers","tags":["customers"]},{"name":"Webhooks and email","tags":["event_subscriptions","events","notification_subscriptions","notifications","templates"]},{"name":"Files","tags":["files","images"]},{"name":"Money and reports","tags":["reports","fees","commissions","foreign_exchange"]},{"name":"Account","tags":["accounts","auths","users","roles","gateways","settings","countries"]}]}