# Overview (/docs/getting-started)

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 [#what-you-build-with]

| Part | What it is for |
|------|----------------|
| REST API | Everything. Your server or your browser code calls `https://api.comecero.com/api/v1` with JSON over HTTPS. |
| Dashboard | Where 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 storefront | A 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 [#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 [#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](/docs/basic-concepts/authentication) explains each token in full.

## Test and live mode [#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](/docs/getting-started/create-an-account) lists the test cards and the steps to go live.

## The API in short [#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](/docs/basic-concepts/error-handling).

## Next steps [#next-steps]

<Cards>
  <Card title="Quickstart" href="/docs/getting-started/quickstart">Create a product, a cart and a paid test order with curl in about 5 minutes.</Card>
  <Card title="Account and test mode" href="/docs/getting-started/create-an-account">Sign up, get test and live tokens, and find the test card numbers.</Card>
  <Card title="Hello World tutorial" href="/docs/tutorials/hello-world">Build a browser checkout in one HTML page with a limited token.</Card>
  <Card title="API reference" href="/api">Every endpoint, with its fields and examples.</Card>
</Cards>
