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.