comecerodocs
Get started

Overview

What Comecero gives a developer, how the API, dashboard and hosted storefront fit together, and how test and live mode keep your data apart.

Comecero is one REST API for selling online: carts, payments, subscriptions, invoices, refunds, customers and webhooks. This page explains how the parts fit, so you know where your code goes before you write any.

What you build with

PartWhat it is for
REST APIEverything. Your server or your browser code calls https://api.comecero.com/api/v1 with JSON over HTTPS.
DashboardWhere you and your team set up the account: products, payment gateways, tax, tokens, webhooks and settings. It runs on the same API you call.
Hosted storefrontA ready shop, cart, checkout, payment page, invoice page and customer account for merchants who do not build their own. Every hosted shop runs on the API too.

Because the dashboard and the hosted storefront use the public API, your own code can do anything they do. You can use the hosted storefront for checkout and the API for the rest, or build everything yourself.

How a sale works

  1. You create products in the dashboard or with the API.
  2. A shopper fills a cart with those products. Comecero works out prices, tax, shipping and promotions.
  3. You take a payment on the cart. The cart closes and becomes an order.
  4. Comecero sends the receipt email and webhooks so your systems hear about the sale.

There is no call that creates an order directly. Orders come from paid carts and paid invoices. Refunds, subscriptions, invoices, license keys and downloads all build on the same objects.

Tokens decide who can do what

Every request sends a token in the Authorization: Bearer <token> header. There are three kinds:

  • Secret: for your server only. Never put one in a browser or an app.
  • Trusted: for a browser tool used by a signed-in merchant. It may set prices.
  • Limited: for one shopper's browser. It can read your public catalog and change only the carts and payments it created. It may not set prices.

The API allows calls from browsers (CORS), so a checkout page can call it directly with a limited token. Authentication explains each token in full.

Test and live mode

Each account has two separate sets of data: test and live. The token decides which one a request uses. A test token sees only test data and a live token sees only live data. There is no test header or test URL: the base URL is the same for both.

In test mode, card payments go to a built-in test gateway and no money moves. Use test mode until your integration works end to end, then switch to live tokens. Account and test mode lists the test cards and the steps to go live.

The API in short

  • Resources have plain URLs, such as /carts/{cart_id} and /orders/{order_id}/refunds, and use the usual HTTP methods and status codes.
  • Related objects come back as URLs. Add expand to get them in full in the same response.
  • Lists return up to 100 items per page and say how to get the next page.
  • Errors come back as JSON with a type, a code and a message. See Error handling.

Next steps

On this page