Skip to content

Checkout API

The checkout API answers one question for a shopper: does this order or cart qualify for a VAT refund, and how much should they expect? Shopify checkout extensions call it during and after checkout.

It is a separate GraphQL endpoint from the tenant API:

POST /api/checkout/graphql

Its schema holds the refundEstimate query and nothing else. It never exposes tenant data, and a shopper's token cannot reach the tenant API.

Authenticate

The credential is the session token Shopify gives a checkout UI extension (shopify.sessionToken.get()), sent as a bearer token:

Authorization: Bearer <session token>

The platform verifies the token (HS256, signed with the Shopify app's secret, audience matching the app's client id, the shop named in dest, expiry required). The token names a shop and, when the shopper is logged in, a customer. It does not name a tenant or a member, and the platform finds the shop's retailer from the shop itself.

Because only a checkout extension receives such a token, this endpoint is not something a server integration can call on its own. Use it from an extension. Riotbyte ships one that calls it for you (see Shopify).

Ask for an estimate

Pass exactly one of order or cart.

For an order

query RefundEstimate($input: RefundEstimateInput!) {
  refundEstimate(input: $input) {
    __typename
    ... on RefundEstimatePending {
      retryAfterMs
    }
    ... on RefundEstimateReady {
      estimate {
        vat
        fee
        payout
        currency
      }
      instructionsUrl
    }
    ... on RefundEstimateIneligible {
      reason
    }
  }
}
{ "input": { "order": { "orderId": "gid://shopify/Order/1234567890" } } }

orderId is the order id in Shopify's format: gid://shopify/Order/<digits>, gid://shopify/OrderIdentity/<digits> or the bare digits. Nothing else is accepted.

For a cart

Before an order exists, estimate from the cart's destination and total tax:

{
  "input": {
    "cart": {
      "countryCode": "GB",
      "totalTax": { "amount": "61.20", "currencyCode": "EUR" }
    }
  }
}

countryCode is an ISO 3166-1 alpha-2 code and amount a decimal string.

The request

API=https://<your ecomtaxfree host>

curl -sS -X POST "$API/api/checkout/graphql" \
  -H 'content-type: application/json' \
  -H "authorization: Bearer $SESSION_TOKEN" \
  -d '{
    "query": "query RefundEstimate($input: RefundEstimateInput!) { refundEstimate(input: $input) { __typename ... on RefundEstimatePending { retryAfterMs } ... on RefundEstimateReady { estimate { vat fee payout currency } instructionsUrl } ... on RefundEstimateIneligible { reason } } }",
    "variables": { "input": { "cart": { "countryCode": "GB", "totalTax": { "amount": "61.20", "currencyCode": "EUR" } } } }
  }'

$SESSION_TOKEN comes from Shopify; there is no way to mint one yourself.

Read the answer

The result is a union. Switch on __typename, never on an HTTP status.

__typename Meaning What to do
RefundEstimateReady Eligible. estimate holds vat, fee and payout as decimal strings in currency; payout is the 65% customer share, before payment costs, and fee is vat less payout. Show it
RefundEstimatePending The order is not imported yet, or is not visible to this token's shopper Ask again after retryAfterMs
RefundEstimateIneligible Not refundable: reason is EU_DESTINATION or NO_VAT Show that no refund applies

instructionsUrl, when present, links to the page where the shopper claims the refund. It is only set for a placed order that has a compliance case. It is a short-lived link carrying an opaque reference, never a case id.

Pending is deliberately vague

An order the platform has not imported yet and an order that belongs to someone else both answer RefundEstimatePending, so a shopper cannot learn which orders exist. A logged-in shopper's token matches only that customer's orders; a guest token (no customer) matches only guest orders. Orders entered manually by tenant members match no token.

Right after checkout the order often has not arrived from Shopify, so poll: wait retryAfterMs, ask again, and stop after a reasonable number of tries.

Errors

Refusals are GraphQL errors with a code in extensions.code:

Code Meaning
UNAUTHENTICATED The session token is missing, invalid or expired, or names a shop that is not connected to a retailer
TOO_MANY_REQUESTS Rate limit hit; wait and retry. Treat it as pending
BAD_REQUEST Both or neither of order and cart, an orderId in the wrong format, a bad countryCode, or an invalid totalTax
SERVICE_UNAVAILABLE Estimation is unavailable; retry later

Limits

  • Each session token may make 20 requests a minute, and each shop 600 a minute across all its tokens. A token that carries no id is counted by its customer instead, or for a guest against the shop as a whole.
  • A guest token that asks about orders it cannot see is budgeted by distinct orders, not requests: asking again about an order it already missed is free, so a thank-you page polling its own slow import never runs out. Each token may miss 3 distinct orders a minute, and the shop has a ceiling across tokens too.
  • Stay well under these. Past any limit the answer is TOO_MANY_REQUESTS, which you should treat as pending and retry after a pause.

CORS

Everything under /api/checkout/ answers with Access-Control-Allow-Origin: *, including the OPTIONS preflight, and allows the Authorization and Content-Type headers. The endpoint never reads cookies.