eMatjarak

Your first API call

Fifteen minutes, start to finish. You need one thing before you begin, and it is not something you can create yourself: a key from the merchant whose store you are integrating with.

  1. Ask the merchant for a key and a store token

    They issue both from their dashboard, under Settings → Developer. Ask for the narrowest set of scopes your integration actually needs — you can always ask for more later, and a key that can only read is a key that cannot break their shop.

  2. Note that the key is shown once

    It is stored hashed, so there is no "show it again". If it is lost the merchant rotates it and hands you a new one. Put it straight into your secret store, not into a config file you will commit.

  3. Make one authenticated request

    Every call is a POST to the same endpoint, carrying both headers. Start with something harmless that proves the key and token are both right.

  4. Read something real

    Fetch the store’s most recent orders. If this returns data, your credentials and scopes are correct and you can start building.

  5. Receive an event instead of polling

    Register an HTTPS endpoint, verify the signature on what arrives, and stop asking the API whether anything changed.

The first request

bash
curl https://api.ematjarak.example/admin-api \
  -H 'content-type: application/json' \
  -H 'ms-api-key: YOUR_KEY' \
  -H 'ms-store-token: STORE_TOKEN' \
  -d '{"query":"{ activeChannel { code } }"}'
  • ms-api-key — the merchant’s key. Send it on every request.
  • ms-store-token — the store’s token, which the merchant gives you alongside the key. Both are required; a key without a token does not identify a store.
A 401 here means the key is wrong, revoked, or belongs to a different store than the token. Check both before assuming the endpoint is down.

Reading orders

graphql
query {
  orders(options: { take: 5, sort: { orderPlacedAt: DESC } }) {
    totalItems
    items {
      id
      code                # show this to people, not the id
      state
      orderPlacedAt       # ISO 8601, UTC
      totalWithTax        # integer, minor units
      currencyCode
      customer { emailAddress }
    }
  }
}

Two things in that response catch people out on day one: money is an integer in minor units, not a decimal, and every date is UTC. Both are covered on the conventions page, and getting them wrong produces totals that are off by a hundred and shipments that appear to happen on the wrong day.

Your first webhook

The merchant registers your HTTPS URL and picks which events they want. We POST a signed JSON body to it and retry on failure. Verify the signature before you trust anything in the body, and reply quickly — do your real work after you have acknowledged.

Webhooks are not available on the free plan. If the merchant is on it, poll on a sensible interval instead and revisit this when they upgrade — building against an endpoint that will never fire is a wasted afternoon.

Where to go next

Money, dates, ids and paginationScopes, rotation and revocationEvery operation a key can callVerifying and handling deliveries