## Does Mercemur take a cut of my sales?

No. There is no per-transaction platform fee. A Stripe charge carries no application
fee, a Razorpay order carries no Route transfer, and nothing is deducted in between.
You connect your own provider account and the money settles there. Mercemur is paid
through your subscription.

Dodo Payments is the one case worth reading twice: it acts as merchant of record and
charges you for handling tax and chargebacks. That is Dodo's fee, not ours.

## What are the rate limits?

Two limits apply to every `/api/v1` request over a rolling one minute window, and
they are counted differently.

| Limit | Budget | Counted per | Scope |
|---|---|---|---|
| Per resource family | 600 requests / minute | **Your API key** | One family, such as products or orders |
| Global ceiling | 1,500 requests / minute | Calling IP address | All families combined |

There are 65 families. The per-family budget stops one workload starving another; the
global ceiling stops a caller multiplying their budget by the number of families.

Your family budget follows the **credential**, not the machine, so running one key from
ten workers shares one counter rather than giving you ten budgets, and another company
behind the same NAT cannot eat into your budget. Need more throughput? Mint a second
key. See [rate limits](/essentials/rate-limits).

Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`,
and a 429 carries `Retry-After`. Read those rather than guessing.

## How do I page through a list?

By cursor, forwards only. Send `limit`, then send the `page.next_cursor` from the
previous response back as `after`.

There is no `offset` and no `page` number. Asking for one is a 400 rather than being
ignored, and the message says so:

```json
{"error":{"code":"invalid_query","message":"unknown query parameter \"offset\";
 this api pages forward only, by cursor"}}
```

The cursor is opaque. Do not decode it or construct one by hand: its encoding is not
part of the contract and it is bound to the route and store that issued it.

## Why is my query parameter rejected?

Because the endpoint does not read it. An unrecognised parameter is a 400, never
silently ignored, and the same parameter sent twice is also a 400.

That is deliberate. A typo'd filter that is ignored returns the UNFILTERED set with a
200 on it, which is the worst of both worlds: wrong data that looks right.

## How is money represented?

As an integer in the currency's minor units, never a float. 1250 in `usd` is $12.50.
Totals are recomputed on the server, and tax is applied to the discounted base.

## Do I need an Idempotency-Key?

Yes, on every write. Send a fresh key per request. Reusing one with a different body
is refused rather than silently applied, so a per-client constant key will fail on the
second write.

## Which key can call this API?

A secret key only. Publishable keys cannot reach `/api/v1` at all.

When you roll a key's secret you choose a grace window of up to three days, and for
its duration both the new secret and the one it replaced authenticate. That lets an
integration move on its own deploy schedule rather than at the instant you press the
button. The key keeps its id and its scopes, so the credential is the only thing that
changes.

## What can a key be allowed to do?

Scopes, granted per key. There are 122, plus a separate tier of 24 ending in
`:delete`.

That second tier is the part worth knowing. Irreversible operations sit behind their
own scope, so granting `write_marketing_campaigns` does not also grant the ability to
cancel a send. A key with every ordinary write scope still cannot perform them.

## How is the API versioned?

The version is in the URL path. There is no version header and no date pinning, so the
URL you call is the whole answer to which version you get.

## Why does an endpoint in the docs return an error on my store?

A few route families are only mounted when their dependency is configured on the
deployment, so an endpoint the reference documents may not be served by your store.
Scheduled gift-card delivery is the usual example: without an encryption key set, codes
go out when the order settles and the delivery endpoints are absent.

If a documented endpoint fails in a way that names no status at all, that is the shape
this produces. [Contact support](/essentials/status) rather than retrying.

## Where do I check whether the API is up?

The [status page](/essentials/status), which also publishes a JSON feed you can poll.