Quickstart

This walks you from no key to a successful call and a successful write. It takes about five minutes.

Create a secret key

In your dashboard, open Settings, API keys and create a key. Grant it only what your integration needs. For this walkthrough tick Read on Products.Your key is shown once, at creation. Copy it then. Mercemur stores only a hash, so nobody can recover the value for you later, including support.

export MERCEMUR_SECRET_KEY="sk_..."

A secret key can read and change your store. Keep it server side. Never put it in a browser bundle, a mobile app, or a public repository.

Make your first read

Every request goes to https://api.mercemur.com/api/v1 and carries the key as a bearer token.

curl https://api.mercemur.com/api/v1/products \
  -H "Authorization: Bearer $MERCEMUR_SECRET_KEY"

const res = await fetch("https://api.mercemur.com/api/v1/products", {
  headers: { Authorization: `Bearer ${process.env.MERCEMUR_SECRET_KEY}` },
})
const body = await res.json()
console.log(body.data)

import os, requests

res = requests.get(
    "https://api.mercemur.com/api/v1/products",
    headers={"Authorization": f"Bearer {os.environ['MERCEMUR_SECRET_KEY']}"},
)
print(res.json()["data"])

req, _ := http.NewRequest("GET", "https://api.mercemur.com/api/v1/products", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("MERCEMUR_SECRET_KEY"))
res, err := http.DefaultClient.Do(req)

$ch = curl_init("https://api.mercemur.com/api/v1/products");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer " . getenv("MERCEMUR_SECRET_KEY"),
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$body = json_decode(curl_exec($ch), true);

A successful list response has your records in data and paging state in page:

{
  "data": [
    { "id": "prod_01J...", "title": "Merino crew", "status": "published" }
  ],
  "page": {
    "has_more": true,
    "next_cursor": "eyJ2IjoxLCJrIjoi..."
  }
}

Handle the refusal you are most likely to hit first

If the key lacks the scope for the route, you get 403 and the message names the exact scope to tick:

{
  "error": {
    "code": "insufficient_scope",
    "message": "this api key requires the read_products scope"
  }
}

Add the scope in the dashboard and retry. Scope changes apply to the existing key, so you do not need to issue a new one. See Scopes.

Make your first write

Writes need one extra header: a unique Idempotency-Key. It is required, not optional, and it is what makes a retry safe after a timeout.

curl -X POST https://api.mercemur.com/api/v1/products \
  -H "Authorization: Bearer $MERCEMUR_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
        "title": "Merino crew",
        "status": "draft"
      }'

Generate a fresh key per logical operation, and reuse that same key when you retry that operation. Replaying it returns the original response instead of creating a second product. See Idempotency.

This write needs write_products. Read and write are separate grants, so a key with only Read will be refused here.

Page through a full collection

There is no page or offset. You pass the previous response’s page.next_cursor back as after, and stop when has_more is false.

curl "https://api.mercemur.com/api/v1/products?limit=100&after=eyJ2IjoxLCJrIjoi..." \
  -H "Authorization: Bearer $MERCEMUR_SECRET_KEY"

See Pagination.

API reference

Every endpoint, with a playground bound to your own store.

Money

Read this before you send an amount. Every value is an integer in minor units.

Get started

Essentials

Authentication

Make requests

Error handling

Next

API reference

Money

​Next

API reference

Money

Next