API

The API is a single GraphQL endpoint. Send a POST request with a JSON body containing your query (or mutation) and optional variables:

POST https://app.gibbond.com/api/v1/graphql

All timestamps are ISO-8601 strings and all IDs are Shopify GIDs (for example gid://shopify/Customer/123) unless noted. Points are whole integers.

Authentication

Every request carries a credential in the Authorization header. There are two kinds of credentials, for two different situations.

API keys (server-side)

API keys identify your backend. Create them in the API keys page of the Gibbond admin, where each key is issued a scope (READ, WRITE or ADMIN). A key is shown once at creation and looks like glk_live_…. Pass it as a bearer token:

Authorization: Bearer glk_live_xxxxxxxxxxxxxxxxxxxx

Customer tokens (client-side)

When you need to call the API from a customer-facing surface (a storefront widget, a mobile app), mint a customer token with the mintCustomerToken mutation from your backend, then hand the token to the client. Customer tokens are short-lived and scoped to a single customer: a request made with one can only read and act on that customer. The me query resolves to the token's customer, and redeemReward works for that customer without a merchant key — so a token is safe to ship to the browser.

Authorization: Bearer <customer token>

Scopes

An API key's scope controls which operations it may run. Scopes are cumulative.

Rate limits

Each credential (every API key and every customer token) is limited to 600 requests per minute. Over the limit, the API returns HTTP 429 with a Retry-After header telling you how many seconds to wait before retrying.

Queries

Queries require a key with at least READ scope, or a customer token (which can only read its own customer).

Mutations

Mutations require a WRITE key unless noted; ADMIN operations are flagged.

Example request

Read a customer's balance and tier with a server-side API key:

curl https://app.gibbond.com/api/v1/graphql \
  -X POST \
  -H "Authorization: Bearer glk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query($id: ID!) { customer(id: $id) { email balance pending lifetime tier { name multiplier } } }",
    "variables": { "id": "gid://shopify/Customer/123456789" }
  }'

Error codes

Errors follow the GraphQL convention: a top-level errors array, each entry carrying a code in extensions and a matching HTTP status.