GraphQL API¶
The tenant API is one GraphQL endpoint. It serves everything a signed-in person can do in the web app: retailers, orders, products, compliance cases, shipping labels and rates, and shop connections.
| Endpoint | Credential | Purpose |
|---|---|---|
POST /api/graphql |
A session (see Authentication) | Tenant operations (this guide) |
POST /api/checkout/graphql |
A Shopify session token | Refund estimates, see Checkout API |
The two endpoints have separate schemas. The checkout schema has no tenant operations, and the tenant schema has no
refundEstimate.
Make your first query¶
Sign in and choose a tenant first (Authentication, Tenants and members). Then:
API=https://<your ecomtaxfree host>
curl -sS -b cookies.txt -X POST "$API/api/graphql" \
-H 'content-type: application/json' \
-H 'x-tenant-id: <tenantId>' \
-d '{"query": "{ orders { id orderReference status destinationCountry exportEligible gross { amount currency } } }"}'
A successful answer is {"data": {"orders": [...]}}. Pass variables the usual way, as
{"query": "...", "variables": {...}}.
orders needs only read access, so it works for every role. Operations that manage retailers or members need an owner
or admin; see roles.
Operations¶
Queries:
| Area | Queries |
|---|---|
| Orders | orders, order(id), actableRetailers |
| Products | products (paged), product(id) |
| Retailers | retailers, retailer(id), tenantMembers |
| Compliance | complianceCases, complianceCase, dossierTimeline |
| Shipping | shippingLabels, shippingLabel, shippingZones, shippingRules, shippingRateSettings, testShippingRate |
| Connections | providerAccounts, providerCatalog, importRuns(accountId) |
Mutations:
| Area | Mutations |
|---|---|
| Orders | enterOrder, recordOrderShipment |
| Products | enrichProduct, enrichProducts |
| Retailers | createRetailer, archiveRetailer, grantRetailerAccess |
| Compliance | openComplianceCase, uploadExportEvidence, recordExportAssessment |
| Shipping | generateShippingLabel, uploadShippingLabel, assignLabelTracking, confirmLabelExit, voidShippingLabel, createShippingZone, updateShippingZone, deleteShippingZone, createShippingRule, updateShippingRule, deleteShippingRule, reorderShippingRules, pauseShippingRule, resumeShippingRule, updateShippingRateSettings, registerShippingCarrier, rotateShippingCarrierToken |
| Connections | beginShopifyInstall, connectProviderAccount, retryShopifyImport, registerShopifyWebhooks |
| Maintenance | rebuildReadModel(kind: ReadModelKind!) truncates and replays one read model of your tenant (ORDER, IMPORT_RUN, COMPLIANCE_CASE, PROVIDER_ACCOUNT, SHIPPING_LABEL); owners and admins only |
The schema is generated from the code at build time. There is no published schema file yet, so for exact field names read the operations the web app uses or ask Riotbyte for the current schema.
Enter an order¶
Retailers whose shops are connected get orders imported automatically. You can also enter an order by hand. First find a retailer you may act for:
query ActableRetailers {
actableRetailers {
id
name
}
}
Then enter the order:
mutation EnterOrder($input: EnterOrderInput!) {
enterOrder(input: $input) {
id
orderReference
status
caseId
destinationCountry
exportEligible
vat {
amount
amountMinor
currency
}
}
}
{
"input": {
"retailerId": "<retailerId>",
"orderReference": "WEB-1001",
"customer": { "reference": "customer-42", "email": "[email protected]" },
"destination": {
"countryCode": "GB",
"city": "London",
"postalCode": "SW1A 1AA"
},
"currency": "EUR",
"placedAt": "2026-11-01T10:15:00+01:00",
"lines": [
{
"description": "Leather wallet",
"sku": "WALLET-1",
"quantity": 1,
"unitPriceGross": "121.00",
"vatRate": 2100
}
]
}
}
Amounts are decimal strings ("121.00"), vatRate is in basis points (2100 is 21%), and placedAt is an ISO 8601
timestamp with an offset. Output money carries both amount (decimal string) and amountMinor (minor units as a
string).
Entering the same orderReference again with different details answers CONFLICT.
Pagination¶
Most lists return a plain array. Lists that can grow large are Relay-style connections with forward paging. products
is one:
query Products($first: Int, $after: String) {
products(first: $first, after: $after) {
edges {
cursor
node {
id
status
}
}
pageInfo {
hasNextPage
endCursor
}
totalCount
}
}
firstis 0 to 200 and defaults to 50. A larger value is refused withBAD_REQUEST, not clamped.first: 0returns no rows but still givestotalCount.aftertakes anendCursor(or an edge'scursor) from the same list. Cursors are opaque and keyset-based, so paging stays stable while rows are added. A malformed cursor answersBAD_REQUEST.- Page until
pageInfo.hasNextPageisfalse.hasPreviousPageis alwaysfalse: there is no backward paging. totalCountcounts the whole list, not the page.
Errors¶
GraphQL errors carry a stable code in extensions.code. Branch on the code, not on the message or the HTTP status.
{
"errors": [
{
"message": "Order not found",
"extensions": { "code": "NOT_FOUND" }
}
],
"data": null
}
Every domain refusal passes through one catalogue, so the same condition answers the same code everywhere. Codes you will meet:
| Code | Meaning |
|---|---|
UNAUTHENTICATED |
No valid credential |
TENANT_REQUIRED, TENANT_MISMATCH |
Tenant selection, see Tenants and members |
FORBIDDEN |
Role or retailer access does not allow it |
NOT_FOUND |
The resource does not exist, or you may not know that it does |
BAD_REQUEST |
Input refused: malformed id, invalid amount or currency, paging out of range |
BAD_USER_INPUT |
A value could not be parsed, such as a malformed DateTime |
CONFLICT |
The change clashes with current state: closed order, duplicate reference, concurrent update, already assessed case |
SERVICE_UNAVAILABLE |
A dependency is down (credential vault, document store, Shopify app not configured); retry later |
PROVIDED_BY_SHOP |
You tried to set a product value the shop already provides |
SHOP_NOT_CONNECTED, SCOPE_MISSING, SHOPIFY_API_FAILED, SHOPIFY_RESPONSE_INVALID, SHOPIFY_UNAVAILABLE |
Shopify-related failures, see Shopify |
Two cases deserve care:
FORBIDDENandNOT_FOUNDcan mean the same thing to you. For shipping zones and rules, a cross-retailer id answersNOT_FOUND, so ids of other retailers are never confirmed.SERVICE_UNAVAILABLEis an outage, never a denial. Retry with backoff.
Read your own writes¶
Writes append events, and the lists you query are projections that catch up a moment later. The API hides that: a mutation that changed something returns only after the projections have applied it (bounded by a short timeout, 2 seconds by default).
If the wait runs out, the response carries two headers:
| Header | Meaning |
|---|---|
x-position |
The position your write has reached |
x-position-timeout |
1 when the wait gave up |
Send the position back as x-min-position on your next request, and the API holds that read until the write is visible:
curl -sS -b cookies.txt -X POST "$API/api/graphql" \
-H 'content-type: application/json' \
-H 'x-min-position: <position from x-position>' \
-d '{"query": "{ orders { id status } }"}'
The wait is bounded by the same timeout. If it runs out, the read still runs and answers x-position-timeout: 1 without
an x-position, so check the follow-up response's headers too and retry after a short delay if it matters. You only
need this when a response carried x-position-timeout. A malformed x-min-position is ignored. When a browser calls
the API directly (the deployment must configure an allowed CORS origin), x-min-position is an allowed request header
and the other two are exposed.
Only your own request's events are covered. Work the platform triggers afterwards, such as a compliance case opened by a policy reacting to a new order, may appear on the next refetch rather than in the same response.
Dates, money and ids¶
DateTimeis an ISO 8601 string with an offset in both directions.- Money you read is a decimal
amount, anamountMinor(minor units as a string) and acurrency. Money you send (MoneyInput) isamountandcurrencyonly. - Ids are opaque strings. Do not parse them.