openapi: 3.0.3
info:
title: Admin Account / Address Gift Cards API
contact:
name: Spree Commerce
url: https://spreecommerce.org
email: hello@spreecommerce.org
description: "Spree Admin API v3 - Administrative API for managing products, orders, and store settings.\n\n## Authentication\n\nThe Admin API requires a secret API key passed in the `x-spree-api-key` header.\nSecret API keys can be generated in the Spree admin dashboard.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\nSingle resource endpoints return a flat JSON object.\n\n## Resource IDs\n\nEvery resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,\n`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,\nrequest bodies, and Ransack filters all accept them directly.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n \"error\": {\n \"code\": \"validation_error\",\n \"message\": \"Validation failed\",\n \"details\": { \"name\": [\"can't be blank\"] }\n }\n}\n```\n"
version: v3
servers:
- url: http://{defaultHost}
variables:
defaultHost:
default: localhost:3000
tags:
- name: Gift Cards
paths:
/api/v3/admin/gift_card_batches:
get:
summary: List gift card batches
tags:
- Gift Cards
security:
- api_key: []
bearer_auth: []
description: 'Returns the gift card batches issued by the current store. Each batch
groups the cards generated together for a campaign or bulk-issuance
— the cards themselves live under `/admin/gift_cards` and reference
the batch via `gift_card_batch_id`.
**Required scope:** `read_gift_cards` (for API-key authentication).'
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
source: "import { createAdminClient } from '@spree/admin-sdk'\n\nconst client = createAdminClient({\n baseUrl: 'https://your-store.com',\n secretKey: 'sk_xxx',\n})\n\nconst { data: batches } = await client.giftCardBatches.list({ page: 1, limit: 25 })"
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
description: Bearer token for admin authentication
schema:
type: string
- name: page
in: query
required: false
description: Page number
schema:
type: integer
- name: limit
in: query
required: false
description: Records per page
schema:
type: integer
- name: q[prefix_cont]
in: query
required: false
description: Filter by prefix (contains)
schema:
type: string
- name: sort
in: query
required: false
description: Sort by field. Prefix with `-` for descending.
schema:
type: string
responses:
'200':
description: gift card batches found
content:
application/json:
example:
data:
- id: gcb_UkLWZg9DAJ
codes_count: 2
currency: USD
prefix: WELCOME
created_at: '2026-05-24T17:36:57.736Z'
updated_at: '2026-05-24T17:36:57.736Z'
amount: '50.0'
expires_at: null
created_by_id: null
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous: null
next: null
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/GiftCardBatch'
meta:
$ref: '#/components/schemas/PaginationMeta'
required:
- data
- meta
post:
summary: Create a gift card batch
tags:
- Gift Cards
security:
- api_key: []
bearer_auth: []
description: 'Issues a batch of gift cards in a single call. The server generates
`codes_count` cards inline for small batches (configurable via
`Spree.config.gift_card_batch_web_limit`, default 500) or enqueues
a background job for larger ones. Each card''s code is the batch
`prefix` followed by random hex.
**Required scope:** `write_gift_cards` (for API-key authentication).'
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
source: "import { createAdminClient } from '@spree/admin-sdk'\n\nconst client = createAdminClient({\n baseUrl: 'https://your-store.com',\n secretKey: 'sk_xxx',\n})\n\nconst batch = await client.giftCardBatches.create({\n prefix: 'WELCOME',\n amount: '25.00',\n currency: 'USD',\n codes_count: 100,\n expires_at: '2030-12-31',\n})"
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'201':
description: gift card batch created
content:
application/json:
example:
id: gcb_gbHJdmfrXB
codes_count: 5
currency: USD
prefix: NEWCAMP
created_at: '2026-05-24T17:36:58.306Z'
updated_at: '2026-05-24T17:36:58.306Z'
amount: '25.0'
expires_at: '2030-12-31'
created_by_id: admin_UkLWZg9DAJ
schema:
$ref: '#/components/schemas/GiftCardBatch'
'422':
description: validation error
content:
application/json:
example:
error:
code: validation_error
message: Prefix can't be blank
details:
prefix:
- can't be blank
schema:
$ref: '#/components/schemas/ErrorResponse'
requestBody:
content:
application/json:
schema:
type: object
required:
- prefix
- amount
- codes_count
properties:
prefix:
type: string
example: WELCOME
description: Lowercased and prepended to every generated code.
amount:
type: string
example: '25.00'
description: Decimal amount per card, greater than zero.
currency:
type: string
example: USD
description: ISO 4217 currency code. Defaults to the store currency.
codes_count:
type: integer
example: 100
description: Number of cards to generate. Capped at `gift_card_batch_limit`.
expires_at:
type: string
example: '2030-12-31'
nullable: true
/api/v3/admin/gift_card_batches/{id}:
parameters:
- name: id
in: path
required: true
description: Gift card batch prefixed ID
schema:
type: string
get:
summary: Get a gift card batch
tags:
- Gift Cards
security:
- api_key: []
bearer_auth: []
description: 'Returns a single batch.
**Required scope:** `read_gift_cards` (for API-key authentication).'
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
source: "import { createAdminClient } from '@spree/admin-sdk'\n\nconst client = createAdminClient({\n baseUrl: 'https://your-store.com',\n secretKey: 'sk_xxx',\n})\n\nconst batch = await client.giftCardBatches.get('gcb_K3zr8x')"
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: gift card batch found
content:
application/json:
example:
id: gcb_UkLWZg9DAJ
codes_count: 2
currency: USD
prefix: WELCOME
created_at: '2026-05-24T17:36:58.593Z'
updated_at: '2026-05-24T17:36:58.593Z'
amount: '50.0'
expires_at: null
created_by_id: null
schema:
$ref: '#/components/schemas/GiftCardBatch'
'404':
description: gift card batch not found
content:
application/json:
example:
error:
code: record_not_found
message: Gift card batch not found
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/v3/admin/gift_cards:
get:
summary: List gift cards
tags:
- Gift Cards
security:
- api_key: []
bearer_auth: []
description: 'Returns the gift cards issued by the current store. Filter by
`q[code_cont]` for code search, `q[user_id_eq]` for cards issued
to a specific customer, or `q[state_eq]` for status filtering.
**Required scope:** `read_gift_cards` (for API-key authentication).'
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
source: "import { createAdminClient } from '@spree/admin-sdk'\n\nconst client = createAdminClient({\n baseUrl: 'https://your-store.com',\n secretKey: 'sk_xxx',\n})\n\nconst { data: giftCards } = await client.giftCards.list({\n page: 1,\n limit: 25,\n expand: ['customer', 'created_by'],\n})"
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
description: Bearer token for admin authentication
schema:
type: string
- name: page
in: query
required: false
description: Page number
schema:
type: integer
- name: limit
in: query
required: false
description: Number of records per page
schema:
type: integer
- name: q[code_cont]
in: query
required: false
description: Filter by gift card code (contains)
schema:
type: string
- name: q[state_eq]
in: query
required: false
description: Filter by status (active, redeemed, partially_redeemed, canceled)
schema:
type: string
- name: sort
in: query
required: false
description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include. id is always included.
schema:
type: string
responses:
'200':
description: gift cards found
content:
application/json:
example:
data:
- id: gc_UkLWZg9DAJ
code: CC7B2B4D3AB3008C
status: active
currency: USD
amount: '50.0'
amount_used: '0.0'
amount_authorized: '0.0'
amount_remaining: '50.0'
display_amount: $50.00
display_amount_used: $0.00
display_amount_remaining: $50.00
expires_at: null
redeemed_at: null
expired: false
active: true
created_at: '2026-05-24T17:36:59.157Z'
updated_at: '2026-05-24T17:36:59.157Z'
customer_id: null
created_by_id: null
- id: gc_gbHJdmfrXB
code: DDB3EA9E5861FC28
status: active
currency: USD
amount: '25.0'
amount_used: '0.0'
amount_authorized: '0.0'
amount_remaining: '25.0'
display_amount: $25.00
display_amount_used: $0.00
display_amount_remaining: $25.00
expires_at: null
redeemed_at: null
expired: false
active: true
created_at: '2026-05-24T17:36:59.158Z'
updated_at: '2026-05-24T17:36:59.158Z'
customer_id: null
created_by_id: null
meta:
page: 1
limit: 25
count: 2
pages: 1
from: 1
to: 2
in: 2
previous: null
next: null
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/GiftCard'
meta:
$ref: '#/components/schemas/PaginationMeta'
required:
- data
- meta
'401':
description: unauthorized
content:
application/json:
example:
error:
code: authentication_required
message: Authentication required
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
summary: Create a gift card
tags:
- Gift Cards
security:
- api_key: []
bearer_auth: []
description: 'Issues a gift card scoped to the current store. The code is
auto-generated when omitted. `currency` defaults to the store''s
configured currency. Pass `user_id` (prefixed ID) to attach the
card to a specific customer.
**Required scope:** `write_gift_cards` (for API-key authentication).'
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
source: "import { createAdminClient } from '@spree/admin-sdk'\n\nconst client = createAdminClient({\n baseUrl: 'https://your-store.com',\n secretKey: 'sk_xxx',\n})\n\nconst giftCard = await client.giftCards.create({\n amount: '25.00',\n currency: 'USD',\n expires_at: '2030-12-31',\n user_id: 'cus_UkLWZg9DAJ',\n})"
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'201':
description: gift card created
content:
application/json:
example:
id: gc_EfhxLZ9ck8
code: A45E3AF0F74D82E8
status: active
currency: USD
amount: '25.0'
amount_used: '0.0'
amount_authorized: '0.0'
amount_remaining: '25.0'
display_amount: $25.00
display_amount_used: $0.00
display_amount_remaining: $25.00
expires_at: '2030-12-31'
redeemed_at: null
expired: false
active: true
created_at: '2026-05-24T17:36:59.731Z'
updated_at: '2026-05-24T17:36:59.731Z'
customer_id: null
created_by_id: admin_UkLWZg9DAJ
schema:
$ref: '#/components/schemas/GiftCard'
'422':
description: validation error
content:
application/json:
example:
error:
code: validation_error
message: Amount must be greater than 0
details:
amount:
- must be greater than 0
schema:
$ref: '#/components/schemas/ErrorResponse'
requestBody:
content:
application/json:
schema:
type: object
required:
- amount
properties:
amount:
type: string
example: '25.00'
description: Decimal amount, greater than zero.
currency:
type: string
example: USD
description: ISO 4217 currency code. Defaults to the store currency.
code:
type: string
example: WELCOME50
description: Optional caller-supplied code. Auto-generated when omitted.
expires_at:
type: string
example: '2030-12-31'
description: ISO 8601 date.
nullable: true
user_id:
type: string
example: cus_UkLWZg9DAJ
description: Optional customer prefixed ID.
nullable: true
/api/v3/admin/gift_cards/{id}:
parameters:
- name: id
in: path
required: true
description: Gift card prefixed ID
schema:
type: string
get:
summary: Get a gift card
tags:
- Gift Cards
security:
- api_key: []
bearer_auth: []
description: 'Returns a single gift card.
**Required scope:** `read_gift_cards` (for API-key authentication).'
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
source: "import { createAdminClient } from '@spree/admin-sdk'\n\nconst client = createAdminClient({\n baseUrl: 'https://your-store.com',\n secretKey: 'sk_xxx',\n})\n\nconst giftCard = await client.giftCards.get('gc_K3zr8x', {\n expand: ['customer', 'created_by', 'orders'],\n})"
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include. id is always included.
schema:
type: string
responses:
'200':
description: gift card found
content:
application/json:
example:
id: gc_UkLWZg9DAJ
code: 62E9760F39DB00B8
status: active
currency: USD
amount: '50.0'
amount_used: '0.0'
amount_authorized: '0.0'
amount_remaining: '50.0'
display_amount: $50.00
display_amount_used: $0.00
display_amount_remaining: $50.00
expires_at: null
redeemed_at: null
expired: false
active: true
created_at: '2026-05-24T17:37:00.039Z'
updated_at: '2026-05-24T17:37:00.039Z'
customer_id: null
created_by_id: null
schema:
$ref: '#/components/schemas/GiftCard'
'404':
description: gift card not found
content:
application/json:
example:
error:
code: record_not_found
message: Gift card not found
schema:
$ref: '#/components/schemas/ErrorResponse'
patch:
summary: Update a gift card
tags:
- Gift Cards
security:
- api_key: []
bearer_auth: []
description: 'Updates an active gift card''s editable attributes. Redeemed or
partially-redeemed cards cannot be edited.
**Required scope:** `write_gift_cards` (for API-key authentication).'
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
source: "import { createAdminClient } from '@spree/admin-sdk'\n\nconst client = createAdminClient({\n baseUrl: 'https://your-store.com',\n secretKey: 'sk_xxx',\n})\n\nconst giftCard = await client.giftCards.update('gc_K3zr8x', {\n amount: '75.00',\n})"
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: gift card updated
content:
application/json:
example:
id: gc_UkLWZg9DAJ
code: 80360376B43E9B35
status: active
currency: USD
amount: '75.0'
amount_used: '0.0'
amount_authorized: '0.0'
amount_remaining: '75.0'
display_amount: $75.00
display_amount_used: $0.00
display_amount_remaining: $75.00
expires_at: null
redeemed_at: null
expired: false
active: true
created_at: '2026-05-24T17:37:00.647Z'
updated_at: '2026-05-24T17:37:00.941Z'
customer_id: null
created_by_id: null
schema:
$ref: '#/components/schemas/GiftCard'
requestBody:
content:
application/json:
schema:
type: object
properties:
amount:
type: string
example: '75.00'
expires_at:
type: string
example: '2031-12-31'
nullable: true
user_id:
type: string
example: cus_UkLWZg9DAJ
nullable: true
delete:
summary: Delete a gift card
tags:
- Gift Cards
security:
- api_key: []
bearer_auth: []
description: 'Deletes an unused gift card. Cards that have been redeemed or
partially redeemed cannot be deleted and return 422.
**Required scope:** `write_gift_cards` (for API-key authentication).'
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
source: "import { createAdminClient } from '@spree/admin-sdk'\n\nconst client = createAdminClient({\n baseUrl: 'https://your-store.com',\n secretKey: 'sk_xxx',\n})\n\nawait client.giftCards.delete('gc_K3zr8x')"
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'204':
description: gift card deleted
'422':
description: redeemed gift card cannot be deleted
content:
application/json:
example:
error:
code: validation_error
message: Gift card cannot be deleted
components:
schemas:
GiftCardBatch:
type: object
properties:
id:
type: string
codes_count:
type: number
currency:
type: string
nullable: true
prefix:
type: string
nullable: true
created_at:
type: string
updated_at:
type: string
amount:
type: string
nullable: true
expires_at:
type: string
nullable: true
created_by_id:
type: string
nullable: true
required:
- id
- codes_count
- currency
- prefix
- created_at
- updated_at
- amount
- expires_at
- created_by_id
x-typelizer: true
Fulfillment:
type: object
properties:
id:
type: string
number:
type: string
tracking:
type: string
nullable: true
tracking_url:
type: string
nullable: true
cost:
type: string
display_cost:
type: string
total:
type: string
display_total:
type: string
discount_total:
type: string
display_discount_total:
type: string
additional_tax_total:
type: string
display_additional_tax_total:
type: string
included_tax_total:
type: string
display_included_tax_total:
type: string
tax_total:
type: string
display_tax_total:
type: string
status:
type: string
fulfillment_type:
type: string
fulfilled_at:
type: string
nullable: true
items:
type: array
items:
$ref: '#/components/schemas/FulfillmentManifestItem'
delivery_method:
$ref: '#/components/schemas/DeliveryMethod'
stock_location:
$ref: '#/components/schemas/StockLocation'
delivery_rates:
type: array
items:
$ref: '#/components/schemas/DeliveryRate'
metadata:
type: object
adjustment_total:
type: string
pre_tax_amount:
type: string
created_at:
type: string
updated_at:
type: string
order_id:
type: string
nullable: true
stock_location_id:
type: string
nullable: true
order:
$ref: '#/components/schemas/Order'
adjustments:
type: array
items:
$ref: '#/components/schemas/Adjustment'
required:
- id
- number
- tracking
- tracking_url
- cost
- display_cost
- total
- display_total
- discount_total
- display_discount_total
- additional_tax_total
- display_additional_tax_total
- included_tax_total
- display_included_tax_total
- tax_total
- display_tax_total
- status
- fulfillment_type
- fulfilled_at
- items
- metadata
- adjustment_total
- pre_tax_amount
- created_at
- updated_at
- order_id
- stock_location_id
x-typelizer: true
DeliveryRate:
type: object
properties:
id:
type: string
delivery_method_id:
type: string
name:
type: string
selected:
type: boolean
cost:
type: string
total:
type: string
additional_tax_total:
type: string
included_tax_total:
type: string
tax_total:
type: string
display_cost:
type: string
display_total:
type: string
display_additional_tax_total:
type: string
display_included_tax_total:
type: string
display_tax_total:
type: string
delivery_method:
$ref: '#/components/schemas/DeliveryMethod'
created_at:
type: string
updated_at:
type: string
required:
- id
- delivery_method_id
- name
- selected
- cost
- total
- additional_tax_total
- included_tax_total
- tax_total
- display_cost
- display_total
- display_additional_tax_total
- display_included_tax_total
- display_tax_total
- created_at
- updated_at
x-typelizer: true
DeliveryMethod:
type: object
properties:
id:
type: string
name:
type: string
code:
type: string
nullable: true
created_at:
type: string
updated_at:
type: string
required:
- id
- name
- code
- created_at
- updated_at
x-typelizer: true
TaxCategory:
type: object
properties:
id:
type: string
name:
type: string
tax_code:
type: string
nullable: true
description:
type: string
nullable: true
is_default:
type: boolean
created_at:
type: string
updated_at:
type: string
required:
- id
- name
- tax_code
- description
- is_default
- created_at
- updated_at
x-typelizer: true
State:
type: object
properties:
abbr:
type: string
name:
type: string
created_at:
type: object
updated_at:
type: object
required:
- abbr
- name
- created_at
- updated_at
x-typelizer: true
CustomField:
type: object
properties:
id:
type: string
label:
type: string
type:
type: string
deprecated: true
field_type:
type: string
enum:
- short_text
- long_text
- rich_text
- number
- boolean
- json
key:
type: string
value:
type: object
created_at:
type: string
updated_at:
type: string
storefront_visible:
type: boolean
custom_field_definition_id:
type: string
required:
- id
- label
- type
- field_type
- key
- value
- created_at
- updated_at
- storefront_visible
- custom_field_definition_id
x-typelizer: true
LineItem:
type: object
properties:
id:
type: string
variant_id:
type: string
quantity:
type: number
currency:
type: string
name:
type: string
slug:
type: string
options_text:
type: string
price:
type: string
display_price:
type: string
total:
type: string
display_total:
type: string
adjustment_total:
type: string
display_adjustment_total:
type: string
additional_tax_total:
type: string
display_additional_tax_total:
type: string
included_tax_total:
type: string
display_included_tax_total:
type: string
discount_total:
type: string
display_discount_total:
type: string
pre_tax_amount:
type: string
display_pre_tax_amount:
type: string
discounted_amount:
type: string
display_discounted_amount:
type: string
display_compare_at_amount:
type: string
nullable: true
compare_at_amount:
type: string
nullable: true
thumbnail_url:
type: string
nullable: true
option_values:
type: array
items:
$ref: '#/components/schemas/OptionValue'
digital_links:
type: array
items:
$ref: '#/components/schemas/DigitalLink'
metadata:
type: object
created_at:
type: string
updated_at:
type: string
cost_price:
type: string
nullable: true
tax_category_id:
type: string
nullable: true
variant:
$ref: '#/components/schemas/Variant'
tax_category:
$ref: '#/components/schemas/TaxCategory'
adjustments:
type: array
items:
$ref: '#/components/schemas/Adjustment'
required:
- id
- vari
# --- truncated at 32 KB (73 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spree-commerce/refs/heads/main/openapi/spree-commerce-gift-cards-api-openapi.yml