REST API - Docs

Cardigan exposes an HTTP API covering the same operations its own storefront and POS extensions use, so you can integrate gift card functionality into a headless storefront, a middleware layer, or your own internal tooling.

Base URL

All endpoints live under a versioned, store-scoped path:

https://app.runcardigan.com/api/v1/{store-subdomain}/

The subdomain is your store's .myshopify.com prefix - for mystore.myshopify.com, use mystore.

Responses are JSON. Errors return an errors array, each entry carrying a code, a human-readable description, and a message:

{
  "errors": [
    {
      "code": "card_not_found",
      "description": "We couldn't find a gift card with those details.",
      "message": "mystore.myshopify.com"
    }
  ]
}

The description is localised and safe to show to a customer. The code is stable and is what you should branch on.

Authentication

The endpoints split into two groups.

Card operations - balance checks, applying and removing cards, and verifying authorizations - are unauthenticated. They're designed to be called from a customer's browser, so they can't require a secret. They're safe in that context because a caller must already know the card number and PIN to get anything back.

Card creation - issuing and activating cards - requires your store's API token, sent as a bearer token:

Authorization: Bearer {your-api-token}

Requesting an API token

Your store's API token is issued by the Cardigan team rather than generated in the admin. Contact support to request one.

The token allows cards to be issued against your provider account, so treat it as a production secret. Never expose it in browser-side code.

Request context

Several optional parameters affect how a request is handled. All are accepted on every endpoint.

Parameter	Purpose
`currency`	The currency of the transaction. Defaults to your store's currency. Used to select a matching profile.
`location_id`	The Shopify location involved. Used to select a matching profile.
`locale`	The locale to return error descriptions in. Defaults to your store's primary locale.

An X-Identity header of pos marks the request as originating from the point of sale, which is also used in profile selection.

See Profile routing for how these combine to determine which provider account a request is sent to. A request that matches no profile returns a no_matching_profile error.

Store configuration

Get store configuration

GET /shop_config

Returns your store's Cardigan configuration - line item property names, PIN behaviour, card length and related settings. This is the same payload exposed to themes via the configuration metafield.

Fetch it once and use it to drive your own forms, rather than hard-coding property names that a merchant may later change.

Card operations

Check a balance

POST /cards/balance

Field	Required	Notes
`number`	Yes	The gift card number
`pin`	Depends	Required unless your store's PIN behaviour says otherwise
`include_transactions`	No	Set to `true` to include the card's transaction history, for providers that support it

Returns the card's balance, currency and expiry date. Returns 404 if the card can't be found or the PIN is wrong.

Apply a card

POST /cards/apply

Field	Required	Notes
`number`	Yes	The gift card number
`pin`	Depends	As above

Checks the card, mirrors it into Shopify as a native gift card, and places a hold on the external card where the provider supports one. See How redemption works for the full mechanism.

The response contains a card object with the Shopify gift card code to apply to the order, along with the card's id, balance, balance_formatted, currency and last_characters. Where the provider supports holds, an authorization object is also returned.

Use last_characters rather than the full number when showing the applied card back to a customer.

Remove a card

POST /cards/{card-id}/remove

Releases the hold placed by apply. The card-id is the id returned in the apply response, not the card number.

Always call this when a customer removes a card, so funds aren't left held unnecessarily.

Verify an authorization

POST /authorizations/{authorization-id}/verify

Confirms a hold is still active and refreshes its expiry. Returns the authorization's id, expires_at and touched_at.

Holds expire after a period of inactivity. If your integration keeps a customer on a page for an extended time with a card applied, call this periodically to keep the hold alive.

Card creation

Both endpoints below require your API token.

Issue a card

POST /issued_cards

Issues a new gift card through your provider and delivers it, without an associated Shopify order.

Field	Required	Notes
`amount`	Yes	The value of the card
`currency_code`	Yes	The currency of the card
`shopify_order_id`	No	Associate the card with an existing Shopify order
`source_name`	No	A label identifying where the request came from, shown in the admin
`source_shopify_id`	No	A Shopify ID to record against the card
`metadata`	No	`recipient_name`, `recipient_email`, `sender_name`, `sender_email`, `greeting`, `delivery_date`, `card_face_id`, `locale`

The card is provisioned immediately rather than waiting for your provisioning trigger. The response contains the card's id, status, provider_id and amount_formatted.

If provisioning fails, the response is a 400 carrying the provider's failure details.

Activate a card

POST /activated_cards

Activates a physical gift card.

Field	Required	Notes
`number`	Yes	The number of the physical card to activate
`amount`	Yes	The value to load onto the card
`currency_code`	Yes	The currency of the card
`source_name`	No	A label identifying where the request came from

The response contains the card's id, status, amount_formatted and last_characters.

Provider capability

The API surface is the same for every provider, but what each provider actually supports differs - not all support issuing cards, holds, or transaction history.

Check the relevant page in the Providers section before building against an endpoint, and expect an error rather than silent success where an operation isn't supported.