List gift cards — API

GET/api/v1/gift-cards

Scope: gift_cards:read

Gift cards with their balances. The redeemable code is NEVER returned here — only its last four characters. Requires the "gift_cards:read" scope.

Query parameters#

Field	Type	Description
`limit`	integermin 1 · max 100 · default 25	How many results to return, 1-100. Defaults to 25.
`order`	stringdefault "desc"	Sort by creation time: "desc" (newest first, default) or "asc". `"asc""desc"`
`starting_after`	string≥ 1 chars	The next_cursor from a previous page. Opaque — pass it back verbatim.
`status`	string	Only cards with this status. Status is computed, not stored. `"active""expired""inactive"`
`updated_since`	string	Only gift cards changed at or after this ISO 8601 timestamp.

Example request#

bash

curl -X GET "https://your-site.awrora.app/api/v1/gift-cards" \
  -H "Authorization: Bearer $AWRORA_API_KEY"

Responses#

200A page of gift cards, without codes.
400Invalid request — codes "validation_failed" or, on an endpoint that requires one, "idempotency_key_required".
401Missing, invalid, revoked or expired API key — codes "api_key_missing", "api_key_invalid", "api_key_revoked", "api_key_expired".
403The API app is off, the plan does not include the API, or the key lacks the required scope — codes "app_not_enabled", "plan_upgrade_required", "insufficient_scope" (the last carries "required_scope").
429Rate limit exceeded — code "rate_limited". See the x-ratelimit-* headers.
500Something went wrong on our side — code "internal_error".

Response 200

Field Type Description

datarequired

object[]

The page of results, in the requested order.

Field Type Description

idrequired

string

Awrora id (UUID) for the gift card.

code_last4required

string | null

Last four characters of the code, for matching against a receipt without revealing it.

statusrequired

string

active = usable; expired = out of validity or fully spent; inactive = deactivated by the merchant.

"active""expired""inactive"

initial_amountrequired

object | null

Face value when the card was issued.

Field	Type	Description
`amount_minor`required	integermin -9007199254740991 · max 9007199254740991	Amount in the currency's minor unit (öre, cents). 120000 means 1200.00.
`currency`required	string	ISO 4217 currency code, uppercase. For example "SEK".

balancerequired

object | null

Remaining balance right now.

Field	Type	Description
`amount_minor`required	integermin -9007199254740991 · max 9007199254740991	Amount in the currency's minor unit (öre, cents). 120000 means 1200.00.
`currency`required	string	ISO 4217 currency code, uppercase. For example "SEK".

currencyrequired

string

ISO 4217 currency code for both amounts.

expires_atrequired

string | null

ISO 8601 timestamp with offset, or null when the card never expires.

purchaserrequired

object

Who bought the card.

recipientrequired

object

Who the card was bought for.

created_atrequired

string

ISO 8601 timestamp with offset.

has_morerequired

boolean

True when more results exist after this page. Fetch them with next_cursor.

next_cursorrequired

string | null

Pass this back as ?starting_after= to fetch the next page. Null when has_more is false. Opaque — do not parse it.

200 response

{
  "data": [
    {
      "id": "res_8f2k3n",
      "code_last4": "string",
      "status": "active",
      "initial_amount": {
        "amount_minor": -9007199254740991,
        "currency": "SEK"
      },
      "balance": {
        "amount_minor": -9007199254740991,
        "currency": "SEK"
      },
      "currency": "SEK",
      "expires_at": "string",
      "purchaser": {
        "name": "string",
        "email": "anna@example.com"
      },
      "recipient": {
        "name": "string",
        "email": "anna@example.com"
      },
      "created_at": "string"
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}