eMatjarak

Conventions

These apply everywhere and none of them raise an error when you get them wrong — they produce plausible, incorrect data instead. Worth ten minutes now.

Money is an integer

Every monetary value is an integer in the currency’s minor units. A total of 185000 in SYP is 1,850.00 — not one hundred and eighty-five thousand pounds. Never parse money into a float: divide by the currency’s minor-unit factor only at the moment you display it, and do all arithmetic on the integers.

Wholesale price bands and other base-currency fields are in USD minor units and are converted for the shopper at display time. Send the base price; converting before you send produces a number that drifts with the exchange rate.

Dates are ISO 8601, UTC

Every timestamp is ISO 8601 with a Z suffix. Convert to the merchant’s local time for display if you like, but store and compare in UTC — Syria’s offset is not the same all year, and "today’s orders" computed in local time will quietly include or drop an hour’s worth.

Ids are opaque

Treat every id as an opaque string. They happen to look numeric today; do not parse them into integers, do not assume they are ordered, and do not generate one yourself. Where an entity has a human-meaningful key as well — an order’s code, a customer group’s code, a product’s slug — that is the one to show people and to match on in your own system.

Lists take an options argument

List queries share one shape: `options` with `take`, `skip`, `sort` and `filter`, returning `items` and `totalItems`. Page with take and skip, and read totalItems to know when to stop rather than requesting until you get an empty page.

graphql
query {
  products(options: {
    take: 50,
    skip: 100,
    sort: { updatedAt: DESC },
    filter: { enabled: { eq: true } }
  }) {
    totalItems            # page until skip + take >= totalItems
    items { id name slug }
  }
}
Ask for a sensible page size. There is a per-key rate limit, and a hundred small pages costs a hundred requests against it where ten larger ones cost ten.

Customers belong to one store

A shopper’s identity is namespaced per store. The same person shopping at two eMatjarak stores has two separate customer records, and an email address is only unique within one store. If you integrate several merchants, key your own records on the store plus the customer — never on the email alone.

Everything is scoped to one store

The store token on your request decides what exists. An id belonging to another merchant does not resolve to a permission error — it simply is not found, because from your key’s point of view it does not exist. This is enforced by the server on every request, so you do not have to filter defensively.

The operations themselvesWhen a call does fail