Skip to content

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
  }
}
  • first is 0 to 200 and defaults to 50. A larger value is refused with BAD_REQUEST, not clamped. first: 0 returns no rows but still gives totalCount.
  • after takes an endCursor (or an edge's cursor) from the same list. Cursors are opaque and keyset-based, so paging stays stable while rows are added. A malformed cursor answers BAD_REQUEST.
  • Page until pageInfo.hasNextPage is false. hasPreviousPage is always false: there is no backward paging.
  • totalCount counts 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:

  • FORBIDDEN and NOT_FOUND can mean the same thing to you. For shipping zones and rules, a cross-retailer id answers NOT_FOUND, so ids of other retailers are never confirmed.
  • SERVICE_UNAVAILABLE is 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

  • DateTime is an ISO 8601 string with an offset in both directions.
  • Money you read is a decimal amount, an amountMinor (minor units as a string) and a currency. Money you send (MoneyInput) is amount and currency only.
  • Ids are opaque strings. Do not parse them.