Skip to main content

Admin API

Use the Admin API to read and manage subscriptions from your own servers, without a customer signing in. Typical uses are a back office, a helpdesk integration, automated processes that change subscription content, or a backend that serves your own app. For what the API covers, see Zubs APIs.

Get an Admin API Key​

Email support@zubs.app with your store's .myshopify.com domain and what you want to build. We send you a key that starts with ZUBS_AT_, through a link you can open once. Save the key in your secrets manager straight away.

A key belongs to one store and reaches every customer and subscription in it. Treat it like a password:

  • Keep it on your servers. Never put it in a theme, a storefront script, a mobile app or a browser.
  • Don't commit it to source control or write it to logs.
  • If a key may have leaked, email us right away. We revoke it and issue a new one.

The key only works on the Admin API endpoint. Apps your customers use sign them in through the Customer API.

Make a Request​

Send a POST request to:

https://hub.zubs.app/api/admin/unstable/graphql.json

Use the key as a bearer token, and name the customer you're acting for in the X-Shopify-Customer-GID header:

curl -X POST https://hub.zubs.app/api/admin/unstable/graphql.json \
  -H "Authorization: Bearer ZUBS_AT_your_key" \
  -H "X-Shopify-Customer-GID: gid://shopify/Customer/7234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query Subs($id: ID!) { customer(id: $id) { subscriptionContracts(first: 20, reverse: true) { edges { node { id status nextBillingDate } } } } }",
    "variables": { "id": "gid://shopify/Customer/7234567890" }
  }'

IDs use Shopify's global ID format, for example gid://shopify/Customer/7234567890 and gid://shopify/SubscriptionContract/123456789.

Act on Behalf of a Customer​

When you work with one customer's subscriptions, set X-Shopify-Customer-GID to that customer's ID on every request:

  • Zubs checks that the subscription belongs to that customer and rejects the request if it doesn't. This protects you from showing one customer another customer's data.
  • Actions are attributed to that customer in the subscription timeline.
  • customerAddressUpdate and customerPaymentMethodSendUpdateEmail require the header and fail without it.

Because the key reaches every customer in your store, always filter what you show by the customer who is signed in to your own system.

Example: Skip an Order​

mutation Skip($contractId: ID!, $index: Int!) {
  subscriptionBillingCycleSkip(contractId: $contractId, billingCycleIndex: $index, skip: true) {
    billingCycle { cycleIndex skipped billingAttemptExpectedDate }
    userErrors { field message }
  }
}

Get the cycleIndex of an upcoming order from subscriptionBillingCycles(contractId: …). To unskip, send skip: false.

Browse every documented query and mutation in the API explorer. For operations that change subscription content, such as products, quantities or the delivery interval, see What the APIs Cover.

Rate Limits​

Most requests read or change data in Shopify on your behalf, so they count against Zubs' Shopify API limit for your store, which Zubs' own background work uses too. Spread bulk jobs out over time, cache what doesn't change often, and retry throttled requests with exponential backoff.

Errors​

A missing, malformed or unknown key returns HTTP 401:

{
  "errors": [{
    "message": "Authentication required",
    "extensions": { "code": "UNAUTHENTICATED", "details": "Missing or invalid token format." }
  }]
}

A mutation that can't be applied returns its problems in userErrors, with HTTP 200. Check userErrors before treating a change as done.