# Comecero Docs > Guides and the API reference for Comecero: take payments, sell subscriptions and run your shop through one REST API. - The complete API description (OpenAPI 3.1): https://docs.comecero.com/openapi.json - Every page in one file: https://docs.comecero.com/llms-full.txt - Any page as Markdown: add .md to its URL, for example https://docs.comecero.com/docs/guides/webhooks.md - MCP server (streamable HTTP, read-only, no sign-in): https://docs.comecero.com/mcp Examples use test mode: a test token (secret.test.…), product ids that end in .test, and card 4444555566661111. ## Guides # Docs - [Introduction](/docs): Learn how Comecero works and build your integration, from your first test payment to webhooks, subscriptions and going live. - Get started - [Overview](/docs/getting-started): What Comecero gives a developer, how the API, dashboard and hosted storefront fit together, and how test and live mode keep your data apart. - [Quickstart](/docs/getting-started/quickstart): Go from a new account to a paid test order with curl in about 5 minutes. Create a test token, a product and a cart, then pay with a test card. - [Account and test mode](/docs/getting-started/create-an-account): Sign up for Comecero, keep test and live tokens and data apart, test payments with test cards for success and decline, and get ready to go live. - [Build with AI](/docs/getting-started/build-with-ai): Connect Claude, Cursor, VS Code or ChatGPT to the Comecero docs with the MCP server, and read every page as Markdown, llms.txt or OpenAPI. - Guides - [Guides](/docs/guides): Step-by-step guides for the main jobs: take payments, receive webhooks, sell subscriptions, send invoices, refund and go live. - [Accept payments](/docs/guides/accept-payments): Build a checkout with the API. Create a cart, take a card, PayPal or Apple Pay payment, handle 3-D Secure and declines, and capture or void later. - [Webhooks](/docs/guides/webhooks): Get events such as order created or payment completed sent to your server, check the signature, answer fast, skip repeats and resend failed events. - [Subscriptions](/docs/guides/subscriptions): Sell a subscription with a plan and a cart, follow renewals with webhooks, change items with proration, cancel, retry failed payments and handle grace periods. - [Invoices](/docs/guides/invoices): Bill a customer with an invoice. Add products or custom items, publish the draft, send a payment link, take payment by API and follow the invoice events. - [Refunds](/docs/guides/refunds): Give money back with the API. Refund a whole order or part of it by amount or items, refund one payment, refund to store credit and follow the refund events. - [Going live](/docs/guides/going-live): A checklist for moving your Comecero integration from test to live mode. Tokens, gateways, webhooks, test leftovers, error handling and safe payment retries. - Concepts - [Concepts](/docs/basic-concepts): The rules every Comecero API endpoint follows: tokens, errors, lists and paging, expanding objects, dates, metadata and more. - [API endpoint and requests](/docs/basic-concepts/api-endpoint): The base URL of the Comecero API, why every call must use HTTPS, and the headers and JSON body format that every request and response uses. - [Authentication](/docs/basic-concepts/authentication): The three Comecero API token types, how long each one lasts, how to create a secret token in the dashboard and how a browser gets a limited token. - [Errors](/docs/basic-concepts/error-handling): The error object every failed Comecero API call returns, what each HTTP status code means, and what your code should do next, such as after a declined card. - [Lists and pagination](/docs/basic-concepts/lists-and-pagination): How Comecero API lists return pages of up to 100 items, the difference between offset and cursor lists, and how to sort them and filter them by date. - [Expanding objects](/docs/basic-concepts/expanding-objects): Use the expand query parameter to get related Comecero objects, such as an order's customer and payments, in the same API response instead of as URLs. - [Customizing output](/docs/basic-concepts/customizing-output): Use the show and hide query parameters to return only the fields you need from the Comecero API, which keeps responses small, especially for long lists. - [Partial updates](/docs/basic-concepts/partial-updates): How to update a Comecero object with a POST that holds only the fields you want to change, how null clears a field and which fields are replaced whole. - [Meta data](/docs/basic-concepts/meta-data): Store your own data on Comecero carts, orders, customers, products and more with the meta field, and carry it from a cart or invoice to the order. - [Dates and times](/docs/basic-concepts/dates-and-times): How the Comecero API writes dates in ISO 8601, how the timezone parameter changes them, and the full and shorthand date formats you can send in requests. - [Localized formatting](/docs/basic-concepts/localized-formatting): Add formatted=true to a Comecero API call to get money amounts and dates as display text in the shopper's language, and choose the locale with user_locale. - [API versioning](/docs/basic-concepts/api-versioning): How the Comecero API is versioned, which changes can arrive without notice in version 1, and how to write code that keeps working as the API grows. - [CORS](/docs/basic-concepts/cors): Call the Comecero API straight from a browser by adding your site's origin to the allowed CORS origins, and learn which origins are allowed without setup. - [License services](/docs/basic-concepts/license-services): Give buyers a license key after each sale, either from a list of keys you upload or from your own license server that Comecero calls with the order. - Tutorials - [Tutorials](/docs/tutorials): Step-by-step tutorials that build working Comecero integrations, starting with a browser checkout in one HTML page that uses a limited token. - [Hello World](/docs/tutorials/hello-world): Build a test checkout in one HTML page. Get a limited token from the browser, create a cart, pay it with a test card and show the result. - Settings reference - [Settings reference](/docs/reference): How Comecero settings work in detail. Gateway weight, automatic fulfillment and capture, shipping price rules and adjustments, and storefront analytics. - [Gateway weight](/docs/reference/gateway-weight): How the gateway weight decides which payment gateway takes a payment when more than one can, and how backup gateways and gateway attempts work. - [Auto fulfill and capture delay](/docs/reference/fulfillment-delay): How fulfillment settings decide when order items are marked fulfilled and when an authorized payment is captured, so you can take the money only after shipping. - [Shipping by quantity](/docs/reference/shipping-quantity): Price a shipping method by the number of physical items in the order, with a price per item and flat prices for quantity ranges, in one or more currencies. - [Shipping by subtotal](/docs/reference/shipping-subtotal): Price a shipping method by the order subtotal, with flat prices for subtotal ranges in each currency and an optional percentage of the subtotal. - [Shipping by weight](/docs/reference/shipping-weight): Price a shipping method by the total weight of the order, with a price per weight unit and flat prices for weight ranges, in any unit and currency. - [Shipping adjustments](/docs/reference/shipping-adjustments): Change a shipping method's price for some US states or Canadian provinces, such as Alaska and Hawaii, by a percentage or a fixed amount per currency. - [Analytics](/docs/reference/analytics): Send storefront page views and purchases to Google Analytics 4 and Google Ads conversions, and add your own tracking code to the hosted storefront. ## API reference # Docs - accounts - [List accounts](/api/accounts/list-accounts): 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`. The list is cursor-based. Page with `after_item` and `before_item`. - [Sign up for an account](/api/accounts/create-account): 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. The 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. - [Get your account](/api/accounts/get-account): 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). The account is not split by mode, so this 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` read permission. - [Update your account](/api/accounts/update-account): 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. This 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. - auths - [List tokens](/api/auths/list-auths): 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. To find one token, send the full token in `q`. You get that token, or an empty list. Secret and trusted tokens may call this with the `auths` read permission. - [Create a limited token](/api/auths/create-limited-auth): 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. Call 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`. Your 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. A 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. - [List token permission options](/api/auths/get-auth-options): 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. Any valid token may call this, including a limited token. No permission is needed. - [Create a secret token](/api/auths/create-secret-auth): 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. The 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`. Give 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. Secret and trusted tokens may call this with the `auths` create permission. - [Create a test trusted token](/api/auths/create-trusted-auth): 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. You 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). The new token lasts two hours from its last use. - [Get a token](/api/auths/get-auth): 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. Any 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`). - [Update a token](/api/auths/update-auth): 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`). The 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. Secret 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. - [Delete a token](/api/auths/delete-auth): 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. Any 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. - carts - [List all carts](/api/carts/list-carts): 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. - [Create a cart](/api/carts/create-cart): 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. - [Retrieve a cart](/api/carts/get-cart): 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`. - [Update a cart](/api/carts/update-cart): 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`). - [List cart cross-sells](/api/carts/list-cart-cross-sells): 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. - [List cart items](/api/carts/list-cart-items): 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. - [Add an item to a cart](/api/carts/create-cart-item): 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`. - [Remove all cart items](/api/carts/delete-cart-items): Empties a cart. Any token type may call it, a limited token too (only for a bound cart). A closed cart is `422`. - [Retrieve a cart item](/api/carts/get-cart-item): Returns one item of a cart. Any token type may call it; a limited token only for a bound cart. - [Update a cart item](/api/carts/update-cart-item): 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`. - [Remove a cart item](/api/carts/delete-cart-item): 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`. - [Retrieve cart item subscription terms](/api/carts/get-cart-item-subscription-terms): 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. - [Sign a customer in to a cart](/api/carts/login-cart): 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. - [Sign the customer out of a cart](/api/carts/logout-cart): 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. - [Retrieve cart options](/api/carts/get-cart-options): 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. - [List cart payments](/api/carts/list-cart-payments): 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. - [Pay for a cart](/api/carts/create-cart-payment): 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. A 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. 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`). A closed cart, an empty cart or a payment still being processed is `400`. - [List cart promotions](/api/carts/list-cart-promotions): 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. - [List related products for a cart](/api/carts/list-cart-related-products): 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. - [Retrieve the cart shipping item](/api/carts/get-cart-shipping-item): 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. - [List cart up-sells](/api/carts/list-cart-up-sells): 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. - [Retrieve a browser payment request](/api/carts/get-cart-user-agent-payment-request): 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. - [Update a browser payment request](/api/carts/update-cart-user-agent-payment-request): 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. - [Validate the Apple Pay merchant](/api/carts/validate-cart-user-agent-payment-request-merchant): 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. - commissions - [List commissions](/api/commissions/list-commissions): 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`). - [Get a commission](/api/commissions/get-commission): 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`). - countries - [List countries](/api/countries/list-countries): 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. This needs no token. Every country comes in one response, so there is no paging. - [Get a country](/api/countries/get-country): Gets one country by its two-letter code, in any case. This needs no token. - customers - [List customers](/api/customers/list-customers): Lists the customers of your account, oldest first. Search with `q` and filter by date or by whether the customer has paid. The 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`. Secret tokens only. A limited token cannot list customers. - [Create a customer](/api/customers/create-customer): 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). Secret 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`. You 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. - [Log in a customer](/api/customers/login-customer): Signs a customer in with the `username` and `password` set on the customer. Three ways to call it: - With a limited token: on success that token is tied to the customer. It can then read and change the customer, their payment methods, orders, subscriptions and invoices, and use `me` as the customer id. No new token is returned. - With no token: send `account_id` (and `test=true` for a test customer) in the query. A new limited token for the customer comes back in `auth`. - With a secret token: you must send the shopper's `user_ip_address` in the query, and the token needs permission to create auths and update customers. A new limited token for the customer comes back in `auth`. Every attempt waits about half a second. After too many failed attempts the customer is locked out for 10 minutes (`401`). - [Email a sign-in link](/api/customers/send-customer-link): 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). The link opens `https:///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`. No token is needed. Every input is in the query string; there is no body. - [Get a customer](/api/customers/get-customer): Gets one customer. Use `expand` to include the customer's `payment_methods`, `payments`, `refunds`, `orders`, `subscriptions`, `invoices` or `balance` in full. Secret tokens, and limited tokens tied to the customer. With a token from a customer login, send `me` as the id. - [Update a customer](/api/customers/update-customer): 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. Secret tokens, and limited tokens tied to the customer. A limited token cannot set `tax_exempt`. No email is sent and no event fires. - [Get a customer's balance](/api/customers/get-customer-balance): 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`. Send `currency` to see the amount in another currency, converted at the account's exchange rate. Send `expand=transactions` to include the transactions. Secret tokens, and limited tokens tied to the customer. - [Add store credit by payment](/api/customers/create-customer-balance-payment): 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. The payment cannot use `customer_account_balance` as its payment method. Money moves and the usual payment events fire. Secret tokens, and limited tokens. The id in the URL may be `me` only with a token from a customer login. - [List balance transactions](/api/customers/list-customer-balance-transactions): 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. The 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`). Secret tokens, and limited tokens tied to the customer. - [Get a balance transaction](/api/customers/get-customer-balance-transaction): Gets one change to a customer's store credit. Use `expand=payment` or `expand=refund` to include the payment or refund behind it. Secret tokens, and limited tokens tied to the customer. - [List a customer's invoices](/api/customers/list-customer-invoices): Lists a customer's invoices, oldest first. The list is offset-based: follow `next_page_url` or send `offset`. Secret tokens, and limited tokens tied to the customer. A limited token never sees draft invoices, whatever `draft` says. - [List a customer's orders](/api/customers/list-customer-orders): Lists a customer's orders, oldest first. The list is offset-based: follow `next_page_url` or send `offset`. Secret tokens, and limited tokens tied to the customer. This is how a signed-in customer sees their order history. - [List a customer's payment methods](/api/customers/list-customer-payment-methods): 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. Card and bank numbers are never returned, only masks, the last four digits and the brand. Secret tokens, and limited tokens tied to the customer. - [Add a payment method](/api/customers/create-customer-payment-method): 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. The customer's first payment method becomes the default. Send `is_default: true` to make a later one the default. If 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`. Secret tokens, and limited tokens tied to the customer. Only a secret token can skip the check with `validate: false`. - [Get a payment method](/api/customers/get-customer-payment-method): Gets one payment method saved to a customer. Secret tokens, and limited tokens tied to the customer. - [Update a payment method](/api/customers/update-customer-payment-method): 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. Secret tokens, and limited tokens tied to the customer. - [Delete a payment method](/api/customers/delete-customer-payment-method): Deletes a saved payment method. For a card, the number is also removed from the vault. This cannot be undone. A 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. Secret tokens, and limited tokens tied to the customer. - [List a customer's payments](/api/customers/list-customer-payments): Lists the payments made by a customer, oldest first. The list is offset-based: follow `next_page_url` or send `offset`. Secret tokens, and limited tokens tied to the customer (for example after Log in a customer). - [List a customer's refunds](/api/customers/list-customer-refunds): Lists the refunds and chargebacks on a customer's payments, oldest first. The list is offset-based: follow `next_page_url` or send `offset`. Secret tokens, and limited tokens tied to the customer. - [List a customer's subscriptions](/api/customers/list-customer-subscriptions): Lists a customer's subscriptions, oldest first. The list is offset-based: follow `next_page_url` or send `offset`. Secret tokens, and limited tokens tied to the customer. - [Create a subscription](/api/customers/create-customer-subscription): Starts a subscription for a customer without a cart or invoice. The customer must already have a saved payment method. Secret tokens only. A limited token cannot create subscriptions. - downloads - [List downloads](/api/downloads/list-downloads): Returns your download links, oldest first unless you send `desc=true`. Secret and trusted tokens may call it. - [Get a download](/api/downloads/get-download): 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. - [Update a download](/api/downloads/update-download): 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. - [Stop a download](/api/downloads/kill-download): 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. - [Reset a download](/api/downloads/reset-download): 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. - [Create a download](/api/downloads/create-download): 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. - event-subscriptions - [List event subscriptions](/api/event-subscriptions/list-event-subscriptions): 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`). - [Create an event subscription](/api/event-subscriptions/create-event-subscription): 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`). - [Get an event subscription](/api/event-subscriptions/get-event-subscription): 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`). - [Update an event subscription](/api/event-subscriptions/update-event-subscription): 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`). - [Delete an event subscription](/api/event-subscriptions/delete-event-subscription): 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`). - [Send a test event](/api/event-subscriptions/test-event-subscription): 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`). - events - [List events](/api/events/list-events): 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`). - [Get an event](/api/events/get-event): 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`). - [Delete an event](/api/events/delete-event): 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`). - [Send an event again](/api/events/retry-event): 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`). - fees - [List fees](/api/fees/list-fees): 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`). - [Get a fee](/api/fees/get-fee): 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`). - files - [List files](/api/files/list-files): Returns your files, oldest first unless you choose another `sort_by`. Secret and trusted tokens may call it. - [Upload a file](/api/files/create-file): 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. - [Get a file](/api/files/get-file): Returns one file. Secret and trusted tokens may call it. - [Update a file](/api/files/update-file): 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. - [Delete a file](/api/files/delete-file): 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. - foreign-exchange - [Convert an amount](/api/foreign-exchange/convert-amount): 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. Secret and trusted tokens may call this. No permission is needed. Limited tokens are refused (`403`): use `GET /fx/product` in the browser. - [Get a product price in a currency](/api/foreign-exchange/get-product-price): 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. Any token may call this, including a limited token. No permission is needed. - gateways - [List gateways](/api/gateways/list-gateways): Lists the gateways of your account in the mode of the token you call with. The list is offset-based. Secret and trusted tokens may call this with the `gateways` read permission. - [Add a gateway](/api/gateways/create-gateway): 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. Secret and trusted tokens may call this with the `gateways` create permission. - [List gateway options](/api/gateways/get-gateway-options): 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. Secret and trusted tokens may call this with the `gateways` read permission. - [Get a gateway](/api/gateways/get-gateway): Gets one gateway. A gateway of the other mode is not found (`404`). Secret and trusted tokens may call this with the `gateways` read permission. - [Update a gateway](/api/gateways/update-gateway): 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. Some 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`). Secret and trusted tokens may call this with the `gateways` update permission. - [Delete a gateway](/api/gateways/delete-gateway): 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. Secret and trusted tokens may call this with the `gateways` delete permission. - images - [List images](/api/images/list-images): Returns your images, oldest first unless you choose another `sort_by`. Secret and trusted tokens may call it. - [Upload an image](/api/images/create-image): 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. - [Get an image](/api/images/get-image): Returns one image. Secret and trusted tokens may call it. - [Delete an image](/api/images/delete-image): 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. - invoices - [List invoices](/api/invoices/list-invoices): 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. - [Create an invoice](/api/invoices/create-invoice): Creates an invoice. It is a draft unless you send `draft: false`. A draft can be changed freely and cannot be paid or seen by limited tokens. Creating fires `invoice:created`. Creating with `draft: false` also publishes it: `invoice:published` fires and the customer is emailed a payment link, unless you send `suppress_customer_notification: true` or have no notification subscription for invoice links. If you send `autopay: true` with a published invoice, Comecero charges the customer's saved payment method on the due date. Items can be catalog products or custom items (a name, a type and a price). Takes a secret or trusted token. Limited tokens cannot create invoices. - [Get an invoice](/api/invoices/get-invoice): 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. - [Update an invoice](/api/invoices/update-invoice): 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. - [Delete an invoice](/api/invoices/delete-invoice): 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. - [List invoice items](/api/invoices/list-invoice-items): 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. - [Add an invoice item](/api/invoices/create-invoice-item): 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`). - [Delete all invoice items](/api/invoices/delete-invoice-items): 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. - [Get an invoice item](/api/invoices/get-invoice-item): 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. - [Update an invoice item](/api/invoices/update-invoice-item): 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`). - [Delete an invoice item](/api/invoices/delete-invoice-item): 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. - [Create a payment link](/api/invoices/create-invoice-link): 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. - [List invoice notifications](/api/invoices/list-invoice-notifications): 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. - [Get invoice payment options](/api/invoices/get-invoice-options): 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. - [List invoice payments](/api/invoices/list-invoice-payments): 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. - [Pay an invoice](/api/invoices/create-invoice-payment): 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. - [List invoice promotions](/api/invoices/list-invoice-promotions): 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. - [List invoice refunds](/api/invoices/list-invoice-refunds): 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. - [Retry an invoice payment](/api/invoices/retry-invoice-payment): 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. - [Send an invoice](/api/invoices/send-invoice): 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. - [Get the invoice shipping item](/api/invoices/get-invoice-shipping-item): 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. - license-requests - [List license requests](/api/license-requests/list-license-requests): 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. - [Get a license request](/api/license-requests/get-license-request): 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. - [Delete a license request](/api/license-requests/delete-license-request): 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. - [Retry a license request](/api/license-requests/retry-license-request): 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. - license-services - [List license services](/api/license-services/list-license-services): 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. - [Create a license service](/api/license-services/create-license-service): 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. - [Get a license service](/api/license-services/get-license-service): Returns one license service, with every key of a `list` service. Secret and trusted tokens may call it. - [Update a license service](/api/license-services/update-license-service): 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. - [Delete a license service](/api/license-services/delete-license-service): 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. - licenses - [List licenses](/api/licenses/list-licenses): Returns the license keys issued for your orders, oldest first unless you send `desc=true`. Secret and trusted tokens may call it. - [Create a license](/api/licenses/create-license): 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. - [Get a license](/api/licenses/get-license): 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. - notification-subscriptions - [List notification subscriptions](/api/notification-subscriptions/list-notification-subscriptions): 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`). - [Create a notification subscription](/api/notification-subscriptions/create-notification-subscription): 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`). - [Get a notification subscription](/api/notification-subscriptions/get-notification-subscription): Gets one notification subscription. Secret and trusted tokens may call it; a limited token may not (`403`). - [Update a notification subscription](/api/notification-subscriptions/update-notification-subscription): 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`). - [Delete a notification subscription](/api/notification-subscriptions/delete-notification-subscription): 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`). - notifications - [List notifications](/api/notifications/list-notifications): 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`). - [Send an email](/api/notifications/send-notification): 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`). - [Get a notification](/api/notifications/get-notification): 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). - [Resend a notification](/api/notifications/resend-notification): 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). - orders - [List orders](/api/orders/list-orders): 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. The 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. Needs a secret or trusted token. Limited tokens get `403`; a customer reads their own orders with `GET /customers/{customer_id}/orders`. - [Get an order](/api/orders/get-order): Returns one order with its items. **PDF:** send `Accept: application/pdf` to get the order as a PDF receipt instead of JSON. The PDF uses your account's order template in the customer's language and comes back as a file named `.pdf`. Secret and trusted tokens can read any order on the account. A limited token can read an order only when it belongs to the token's customer, and the settlement amounts and some item fields are left out for it. - [Capture an order](/api/orders/capture-order): Captures the money that was only authorized on the order's pending payments. Money moves. To capture all of it, send no body at all: a JSON body without `total`, `items` or `shipping` (even `{}`) captures nothing and releases the rest. To capture part, send a `total`, or `items` and `shipping`. The part you do not capture is written down as a record-only refund (no money moves for it), so the order shows what was really charged. When the order has more than one pending payment, the largest is captured first and any payment left over once the amount is reached is voided. Returns `201` with a `payment_list` holding each payment and its result. When every capture fails, the API answers with an error instead and puts the `payment_list` in the error's `meta.payment_list`. Needs a secret or trusted token that may create or update payments. A token without that permission gets `401`, not `403`. - [Get an order's fee summary](/api/orders/get-order-fee-summary): Returns the Comecero fees on the order: the fees of all its payments and their refunds, added up per currency. Needs a secret or trusted token that may read fees. Limited tokens are refused. A token without the fees permission gets `401`, not `403`. - [List an order's items](/api/orders/list-order-items): 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`. A limited token may call this for an order of its own customer. - [Get an order item](/api/orders/get-order-item): Returns one line of an order. A limited token may call this for an order of its own customer. - [Update an order item](/api/orders/update-order-item): 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. Needs a secret or trusted token. Limited tokens get `403`. - [List an item's shipments](/api/orders/list-order-item-shipments): Lists the shipments of an order that contain this item. Offset-based (`offset`, `limit`). `sort_by` takes `date_created` (default) or `date_modified`. A limited token may call this for an order of its own customer. - [List an order's notifications](/api/orders/list-order-notifications): 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`. A limited token may call this for an order of its own customer. - [List an order's payments](/api/orders/list-order-payments): 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`. A limited token may call this for an order of its own customer. - [List an order's promotions](/api/orders/list-order-promotions): 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`. A limited token may call this for an order of its own customer. - [List an order's refunds](/api/orders/list-order-refunds): 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`. A limited token may call this for an order of its own customer. - [List an order's shipments](/api/orders/list-order-shipments): Lists the shipments made for an order. Offset-based (`offset`, `limit`). `sort_by` takes `date_created` (default) or `date_modified`. A limited token may call this for an order of its own customer. - [Void an order](/api/orders/void-order): 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. Returns `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`. Needs a secret or trusted token that may create or update payments. A token without that permission gets `401`, not `403`. - refunds - [Refund an order](/api/refunds/refund-order): Gives money back to the customer. Money moves. **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. An 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. To 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`. Needs a secret or trusted token. Limited tokens get `403`. - [Get a refund list](/api/refunds/get-refund-list): 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. Needs a secret or trusted token. Limited tokens get `403`. - [List refunds](/api/refunds/list-refunds): 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. The 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. Needs a secret or trusted token. Limited tokens get `403`. - [Get refund options](/api/refunds/get-refund-options): 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. Needs a secret or trusted token. Limited tokens get `403`. - [Get a refund](/api/refunds/get-refund): Returns one refund or chargeback. Secret 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. - [Update a refund](/api/refunds/update-refund): Changes your `comments` or `meta` on a refund. Amounts and status cannot be changed. No money moves and no event fires. Needs a secret or trusted token. Limited tokens get `403`. - [Delete a refund](/api/refunds/delete-refund): 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. Needs a secret or trusted token. Limited tokens get `403`. - [List a refund's commissions](/api/refunds/list-refund-commissions): 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. Needs a secret or trusted token that may read commissions. Limited tokens get `403`. - [Complete a pending refund](/api/refunds/complete-refund): 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. Only Comecero staff (admin tokens) may call this. Secret, trusted and limited tokens get `403`. - [Get a refund's fee summary](/api/refunds/get-refund-fee-summary): Returns the Comecero fees on one refund, added up per currency. Needs a secret or trusted token that may read fees. Limited tokens are refused. A token without the fees permission gets `401`, not `403`. - [List a refund's fees](/api/refunds/list-refund-fees): Lists the Comecero fees recorded for one refund. Offset-based (`offset`, `limit`). `sort_by` takes `date_created` (default) or `date_modified`. Needs a secret or trusted token that may read fees. Limited tokens get `403`. - [List a refund's items](/api/refunds/list-refund-items): 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. A limited token may call this for a refund it is bound to. - [Get a refund item](/api/refunds/get-refund-item): Returns one item of a refund. A limited token may call this for a refund it is bound to. - [List a refund's notifications](/api/refunds/list-refund-notifications): Lists the emails sent to the customer about this refund. Offset-based (`offset`, `limit`). `sort_by` takes `date_created` (default) or `date_modified`. A limited token may call this for a refund it is bound to. - [Get a refund's payment method](/api/refunds/get-refund-payment-method): 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 `{}`. A limited token may call this for a refund it is bound to. - shipments - [Create a shipment](/api/shipments/create-order-shipment): 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. Needs a secret or trusted token. Limited tokens get `403`. - [List shipments](/api/shipments/list-shipments): Lists the shipments on your account, oldest first unless you send `desc=true`. To create one, use `POST /orders/{order_id}/shipments`. The 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. Needs a secret or trusted token. Limited tokens get `403`. - [Get a shipment](/api/shipments/get-shipment): Returns one shipment. Secret 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. - [Update a shipment](/api/shipments/update-shipment): 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. Needs a secret or trusted token. Limited tokens get `403`. - [Delete a shipment](/api/shipments/delete-shipment): 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. Needs a secret or trusted token. Limited tokens get `403`. - [List a shipment's notifications](/api/shipments/list-shipment-notifications): 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`. A limited token may call this for a shipment it is bound to. - payments - [Retrieve a payment list](/api/payments/get-payment-list): 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`. - [List all payments](/api/payments/list-payments): 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. - [Create a payment](/api/payments/create-payment): 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`). Any 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. The 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`). - [Retrieve payment options](/api/payments/get-payment-options): 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. - [Retrieve a payment](/api/payments/get-payment): 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. - [Update a payment](/api/payments/update-payment): 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. - [Capture a payment](/api/payments/capture-payment): 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`. - [List payment commissions](/api/payments/list-payment-commissions): 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`. - [Commit a payment](/api/payments/commit-payment): 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. If 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`. Any 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. - [Retrieve a payment fee summary](/api/payments/get-payment-fee-summary): 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`. - [List payment fees](/api/payments/list-payment-fees): 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`. - [List payment notifications](/api/payments/list-payment-notifications): 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. - [Retrieve a payment's payment method](/api/payments/get-payment-payment-method): 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. - [List payment refunds](/api/payments/list-payment-refunds): 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. - [Refund a payment](/api/payments/create-payment-refund): 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`. - [Retrieve payment response data](/api/payments/get-payment-response-data): 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. - [Void a payment](/api/payments/void-payment): 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`. - products - [List products](/api/products/list-products): 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. - [Create a product](/api/products/create-product): 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. - [Get a product](/api/products/get-product): 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. - [Update a product](/api/products/update-product): 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. - [Delete a product](/api/products/delete-product): 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. - [List related products](/api/products/list-related-products): 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. - [List plan change products](/api/products/list-subscription-change-products): 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. - [List term change products](/api/products/list-subscription-term-change-products): 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. - [Get subscription terms](/api/products/get-product-subscription-terms): 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. - promotions - [List promotions](/api/promotions/list-promotions): Returns your coupons, cross-sells and up-sells, oldest first unless you choose another `sort_by`. Secret and trusted tokens may call it. - [Create a promotion](/api/promotions/create-promotion): 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. - [Get a promotion](/api/promotions/get-promotion): 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. - [Update a promotion](/api/promotions/update-promotion): 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. - [Delete a promotion](/api/promotions/delete-promotion): 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. - reports - [Get the commissions report](/api/reports/get-commissions-report): 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. Send `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. Without `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. - [Get the fees report](/api/reports/get-fees-report): 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`. Send `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. Without `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. - [Get the items report](/api/reports/get-items-report): 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. With 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. 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. - [Get the sales report](/api/reports/get-sales-report): 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. With 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. The 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. - [Get the sales summary](/api/reports/get-sales-summary-report): 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. With 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. Amounts 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. - [Get the tax report](/api/reports/get-tax-report): 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. With 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. Amounts 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. - roles - [List roles](/api/roles/list-roles): Lists the roles of your account in the mode of the token you call with. The list is offset-based. Secret and trusted tokens may call this with the `roles` read permission. - [Create a role](/api/roles/create-role): Creates a role in the mode of the token you call with. Give it to users and secret tokens through their `roles` list. Secret and trusted tokens may call this with the `roles` create permission. - [Get a role](/api/roles/get-role): Gets one role. A role of the other mode is not found (`404`). Secret and trusted tokens may call this with the `roles` read permission. - [Delete a role](/api/roles/delete-role): Deletes a role. Users and tokens that list it keep the `role_id` but no longer get its permissions. Secret and trusted tokens may call this with the `roles` delete permission. - [Replace a role](/api/roles/update-role): 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. Secret and trusted tokens may call this with the `roles` update permission. - settings - [Get analytics settings](/api/settings/get-analytics-settings): 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. - [Update analytics settings](/api/settings/update-analytics-settings): 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. - [Get fraud settings](/api/settings/get-fraud-settings): 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. - [Update fraud settings](/api/settings/update-fraud-settings): 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. - [Get fulfillment settings](/api/settings/get-fulfillment-settings): 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. - [Update fulfillment settings](/api/settings/update-fulfillment-settings): 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. - [Get general settings](/api/settings/get-general-settings): 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. - [Update general settings](/api/settings/update-general-settings): 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. - [Get payment settings](/api/settings/get-payment-settings): 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. - [Update payment settings](/api/settings/update-payment-settings): 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. - [Get pricing settings](/api/settings/get-pricing-settings): 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. - [Update pricing settings](/api/settings/update-pricing-settings): 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. - [Get shipping settings](/api/settings/get-shipping-settings): 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. - [Update shipping settings](/api/settings/update-shipping-settings): 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. - [List shipping methods in settings](/api/settings/list-settings-shipping-methods): 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. - [Create a shipping method in settings](/api/settings/create-settings-shipping-method): 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. - [Get a shipping method in settings](/api/settings/get-settings-shipping-method): 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. - [Update a shipping method in settings](/api/settings/update-settings-shipping-method): 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. - [Delete a shipping method in settings](/api/settings/delete-settings-shipping-method): 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. - [Get storefront settings](/api/settings/get-storefront-settings): 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. - [Update storefront settings](/api/settings/update-storefront-settings): 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. - [Get subscription settings](/api/settings/get-subscription-settings): 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. - [Update subscription settings](/api/settings/update-subscription-settings): 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. - [Get tax settings](/api/settings/get-tax-settings): 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. - [Update tax settings](/api/settings/update-tax-settings): 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. - [Get technical settings](/api/settings/get-technical-settings): 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. - [Update technical settings](/api/settings/update-technical-settings): 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. - shipping-methods - [List shipping methods](/api/shipping-methods/list-shipping-methods): 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`. - [Create a shipping method](/api/shipping-methods/create-shipping-method): 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. - [Get a shipping method](/api/shipping-methods/get-shipping-method): 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. - [Update a shipping method](/api/shipping-methods/update-shipping-method): 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. - [Delete a shipping method](/api/shipping-methods/delete-shipping-method): Removes a shipping method for good. Shoppers can no longer pick it. Secret and trusted tokens may call it. - subscription-plans - [List subscription plans](/api/subscription-plans/list-subscription-plans): 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`). - [Create a subscription plan](/api/subscription-plans/create-subscription-plan): 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`). - [Get a subscription plan](/api/subscription-plans/get-subscription-plan): 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. - [Update a subscription plan](/api/subscription-plans/update-subscription-plan): 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`). - [Delete a subscription plan](/api/subscription-plans/delete-subscription-plan): 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`). - subscriptions - [List subscriptions](/api/subscriptions/list-subscriptions): 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`. - [Get subscription options](/api/subscriptions/get-subscription-options): 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`). - [Get a subscription](/api/subscriptions/get-subscription): 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). - [Update a subscription](/api/subscriptions/update-subscription): 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. - [Remove scheduled item additions](/api/subscriptions/delete-subscription-scheduled-additions): 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. - [Cancel a subscription](/api/subscriptions/cancel-subscription): 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`). - [Extend a subscription period](/api/subscriptions/extend-subscription): 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`). - [Fast forward a test subscription](/api/subscriptions/fast-forward-subscription): 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. - [Get subscription history](/api/subscriptions/get-subscription-history): 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`). - [List subscription invoices](/api/subscriptions/list-subscription-invoices): 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. - [List subscription items](/api/subscriptions/list-subscription-items): 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. - [Add a subscription item](/api/subscriptions/create-subscription-item): 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. - [Preview adding an item](/api/subscriptions/preview-subscription-item): 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. - [Get a subscription item](/api/subscriptions/get-subscription-item): 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. - [Update a subscription item](/api/subscriptions/update-subscription-item): 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). - [Cancel a subscription item](/api/subscriptions/cancel-subscription-item): 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`). - [Remove an item's scheduled change](/api/subscriptions/delete-subscription-item-scheduled-change): 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. - [Preview an item change](/api/subscriptions/preview-subscription-item-update): 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. - [Get an item's billing terms](/api/subscriptions/get-subscription-item-terms): 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. - [Undo an item's scheduled cancellation](/api/subscriptions/uncancel-subscription-item): 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`). - [List subscription notifications](/api/subscriptions/list-subscription-notifications): 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. - [Retry a failed renewal payment](/api/subscriptions/retry-subscription-payment): 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`). - [Undo a scheduled cancellation](/api/subscriptions/uncancel-subscription): 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`). - templates - [List templates](/api/templates/list-templates): 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`). - [Create a template](/api/templates/create-template): 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`). - [Get a template](/api/templates/get-template): Gets one template with its `body`. Secret and trusted tokens may call it; a limited token may not (`403`). - [Update a template](/api/templates/update-template): 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`). - [Delete a template](/api/templates/delete-template): 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`). - [Render a template](/api/templates/build-template): 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`). - users - [List users](/api/users/list-users): 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. Secret and trusted tokens may call this with the `users` read permission. - [Create a user](/api/users/create-user): 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. Secret and trusted tokens may call this with the `users` create permission. - [Get a user](/api/users/get-user): 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`). - [Update a user](/api/users/update-user): Changes a user. Only the fields you send change. Fires the `user:modified` event. A 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. - [Delete a user](/api/users/delete-user): Deletes a user so they can no longer sign in. You cannot delete yourself or use `me` (`400`). Secret and trusted tokens may call this with the `users` delete permission. - webhooks - [Account modified](/api/webhooks/account-modified): 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`. - [Cart payment completed](/api/webhooks/cart-payment-completed): 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`. - [Gateway created](/api/webhooks/gateway-created): Fires when a payment gateway is added to your account. The body is an event object with the gateway in `data`. - [Gateway modified](/api/webhooks/gateway-modified): 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`. - [Event subscription created](/api/webhooks/event-subscription-created): 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`. - [Event subscription modified](/api/webhooks/event-subscription-modified): 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`. - [Event subscription deleted](/api/webhooks/event-subscription-deleted): 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`. - [License service low on licenses](/api/webhooks/license-service-low-licenses): 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`. - [Invoice created](/api/webhooks/invoice-created): 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`. - [Invoice published](/api/webhooks/invoice-published): 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`. - [Invoice paid](/api/webhooks/invoice-paid): 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`. - [Invoice payment completed](/api/webhooks/invoice-payment-completed): 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`. - [Order created](/api/webhooks/order-created): 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`. - [Order payment completed](/api/webhooks/order-payment-completed): 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`. - [Order fulfilled](/api/webhooks/order-fulfilled): 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`. - [Order licenses assigned](/api/webhooks/order-licenses-assigned): 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`. - [Payment completed](/api/webhooks/payment-completed): 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`. - [Payment succeeded](/api/webhooks/payment-created-success): 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`. - [Payment failed](/api/webhooks/payment-created-failure): 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`. - [Payment captured](/api/webhooks/payment-captured-success): Fires when an authorized payment is captured. `payment:completed` fires with it. The body is an event object with the payment in `data`. - [Payment capture failed](/api/webhooks/payment-captured-failure): Fires when capturing an authorized payment fails. The body is an event object with the payment in `data`. - [Payment voided](/api/webhooks/payment-voided): 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`. - [Product created](/api/webhooks/product-created): Fires when a product is created. The body is an event object with the product in `data`. - [Product modified](/api/webhooks/product-modified): Fires when a product is changed. The body is an event object with the product in `data`. - [Product deleted](/api/webhooks/product-deleted): 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`. - [Product low on inventory](/api/webhooks/product-low-inventory): 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`. - [Refund succeeded](/api/webhooks/refund-created-success): Fires when a refund completes. The body is an event object with the refund in `data`. - [Refund failed](/api/webhooks/refund-created-failure): 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`. - [Refund deleted](/api/webhooks/refund-deleted): 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`. - [User created](/api/webhooks/user-created): 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`. - [User modified](/api/webhooks/user-modified): 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`. - [Shipment created](/api/webhooks/shipment-created): Fires when a shipment is created on an order. The body is an event object with the shipment in `data`. - [Shipment modified](/api/webhooks/shipment-modified): Fires when a shipment is changed, for example when tracking is added. The body is an event object with the shipment in `data`. - [Shipment deleted](/api/webhooks/shipment-deleted): 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`. - [Subscription created](/api/webhooks/subscription-created): 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`. - [Subscription modified](/api/webhooks/subscription-modified): 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`. - [Subscription cancelled](/api/webhooks/subscription-cancelled): 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`. - [Subscription cancellation scheduled](/api/webhooks/subscription-cancellation-scheduled): 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`. - [Subscription cancellation unscheduled](/api/webhooks/subscription-cancellation-unscheduled): Fires when a scheduled cancellation is taken back, so the subscription renews again. The body is an event object with the subscription in `data`. - [Subscription completed](/api/webhooks/subscription-completed): 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`. - [Subscription converted](/api/webhooks/subscription-converted): Fires when a subscription in a trial makes its first paid renewal. The body is an event object with the subscription in `data`. - [Subscription item added](/api/webhooks/subscription-item-added): Fires when an item is added to a subscription. The body is an event object with the subscription item in `data`. - [Subscription item cancelled](/api/webhooks/subscription-item-cancelled): Fires when an item on a subscription is cancelled and ends now. The body is an event object with the subscription item in `data`. - [Subscription item cancellation scheduled](/api/webhooks/subscription-item-cancellation-scheduled): 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`. - [Subscription item cancellation unscheduled](/api/webhooks/subscription-item-cancellation-unscheduled): Fires when a scheduled cancellation of an item is taken back. The body is an event object with the subscription item in `data`. - [Subscription item modified](/api/webhooks/subscription-item-modified): 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`. - [Subscription renewed](/api/webhooks/subscription-renewal-success): 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`. - [Subscription renewal failed](/api/webhooks/subscription-renewal-failure): Fires when a renewal payment fails. The subscription may enter its grace period. The body is an event object with the subscription in `data`.