Cards

Manage loyalty stamp card templates

Cards are loyalty stamp card templates that define the look, feel, and rules for a store’s loyalty program. Each card specifies how many stamps are required, which icon to use, the colour scheme, and the strip image style.

Customers receive individual instances of a card (CustomerCards) and collect stamps toward rewards. A store may have multiple active card templates (e.g. a coffee card and a haircut card).

Cards can be archived to hide them from the default listing without deleting historical data. Use the scope query parameter on the index endpoint to control which cards are returned.

All card endpoints are scoped to a store via the :account_id URL parameter.

index

GET /api/v1/accounts/:account_id/cards

List loyalty cards

Returns loyalty card templates for the specified store. By default, only active (unarchived) cards are returned. Use the scope parameter to include archived cards.

Parameters

Name Type Required Description
account_id Must be a Integer Required

Parent store ID
scope Must be a String Optional

Filter cards by archive status. Default: active only.

(blank allowed)

Error Codes

Code Description
401 Unauthorized – invalid or missing API token
404 Store not found or not accessible

Returns

Code: 200

An array of card objects

Name Type Required Description
id Must be a Integer Required

Unique card ID
name Must be a String Required

Card name (e.g. ‘Coffee Loyalty Card’)
card_color Must be a String Required

Hex colour for the card background (e.g. ‘#6B4226’)
text_color Must be a String Required

Hex colour for card text
stamp_icon Must be a String Required

Icon used for stamps (e.g. ‘coffee’, ‘heart’, ‘star’)
stamp_color Must be a String Required

Hex colour for stamp icons
stamps_required Must be a Integer Required

Number of stamps needed to complete the card (1–18)
initial_stamps Must be a Integer Required

Number of stamps pre-filled on new customer cards (0 to stamps_required - 1)
strip_type Must be a String Required

Strip image type: ‘color’, ‘image’, or ‘preset’
strip_color Must be a String Required

Hex colour for the strip (when strip_type is ‘color’)

(nil allowed)
strip_preset Must be a String Required

Preset strip image identifier (when strip_type is ‘preset’)

(nil allowed)
header_text Must be a String Required

Optional header text displayed on the card

(nil allowed)
archived_at Must be a String Required

ISO 8601 timestamp when the card was archived, or null if active

(nil allowed)
rewards_count Must be a Integer Required

Number of rewards defined for this card
customer_cards_count Must be a Integer Required

Number of customer card instances issued
created_at Must be a String Required

ISO 8601 creation timestamp
updated_at Must be a String Required

ISO 8601 last-update timestamp

show

GET /api/v1/accounts/:account_id/cards/:id

Show a loyalty card

Returns a single loyalty card template by ID, including reward and customer card counts.

Parameters

Name Type Required Description
account_id Must be a Integer Required

Parent store ID
id Must be a Integer Required

Card ID

Error Codes

Code Description
401 Unauthorized – invalid or missing API token
404 Card not found

Returns

Code: 200

A card object

Name Type Required Description
id Must be a Integer Required

Unique card ID
name Must be a String Required

Card name (e.g. ‘Coffee Loyalty Card’)
card_color Must be a String Required

Hex colour for the card background (e.g. ‘#6B4226’)
text_color Must be a String Required

Hex colour for card text
stamp_icon Must be a String Required

Icon used for stamps (e.g. ‘coffee’, ‘heart’, ‘star’)
stamp_color Must be a String Required

Hex colour for stamp icons
stamps_required Must be a Integer Required

Number of stamps needed to complete the card (1–18)
initial_stamps Must be a Integer Required

Number of stamps pre-filled on new customer cards (0 to stamps_required - 1)
strip_type Must be a String Required

Strip image type: ‘color’, ‘image’, or ‘preset’
strip_color Must be a String Required

Hex colour for the strip (when strip_type is ‘color’)

(nil allowed)
strip_preset Must be a String Required

Preset strip image identifier (when strip_type is ‘preset’)

(nil allowed)
header_text Must be a String Required

Optional header text displayed on the card

(nil allowed)
archived_at Must be a String Required

ISO 8601 timestamp when the card was archived, or null if active

(nil allowed)
rewards_count Must be a Integer Required

Number of rewards defined for this card
customer_cards_count Must be a Integer Required

Number of customer card instances issued
created_at Must be a String Required

ISO 8601 creation timestamp
updated_at Must be a String Required

ISO 8601 last-update timestamp

create

POST /api/v1/accounts/:account_id/cards

Create a loyalty card

Creates a new loyalty stamp card template for the store. The card defines the visual design (colours, icon, strip) and program rules (stamps required, initial stamps).

Parameters

Name Type Required Description
account_id Must be a Integer Required

Parent store ID
card Must be a Hash Required

Card attributes
card[name] Must be a String Required

Card name (e.g. ‘Coffee Loyalty Card’)
card[card_color] Must be a String Optional

Hex colour for the card background (e.g. ‘#6B4226’)
card[text_color] Must be a String Optional

Hex colour for card text
card[stamp_icon] Must be a String Optional

Stamp icon identifier
card[stamp_color] Must be a String Optional

Hex colour for stamp icons
card[stamps_required] Must be a Integer Optional

Number of stamps needed to complete the card (1–18)
card[initial_stamps] Must be a Integer Optional

Number of stamps pre-filled on new customer cards (must be >= 0 and < stamps_required)
card[strip_type] Must be a String Optional

Strip image type
card[strip_color] Must be a String Optional

Hex colour for the strip (used when strip_type is ‘color’)
card[strip_preset] Must be a String Optional

Preset strip image identifier (used when strip_type is ‘preset’)
card[header_text] Must be a String Optional

Optional header text displayed on the card

Error Codes

Code Description
401 Unauthorized – invalid or missing API token
404 Store not found or not accessible
422 Validation failed – check the `errors` object for details

Returns

Code: 201

The newly created card object

Name Type Required Description
id Must be a Integer Required

Unique card ID
name Must be a String Required

Card name (e.g. ‘Coffee Loyalty Card’)
card_color Must be a String Required

Hex colour for the card background (e.g. ‘#6B4226’)
text_color Must be a String Required

Hex colour for card text
stamp_icon Must be a String Required

Icon used for stamps (e.g. ‘coffee’, ‘heart’, ‘star’)
stamp_color Must be a String Required

Hex colour for stamp icons
stamps_required Must be a Integer Required

Number of stamps needed to complete the card (1–18)
initial_stamps Must be a Integer Required

Number of stamps pre-filled on new customer cards (0 to stamps_required - 1)
strip_type Must be a String Required

Strip image type: ‘color’, ‘image’, or ‘preset’
strip_color Must be a String Required

Hex colour for the strip (when strip_type is ‘color’)

(nil allowed)
strip_preset Must be a String Required

Preset strip image identifier (when strip_type is ‘preset’)

(nil allowed)
header_text Must be a String Required

Optional header text displayed on the card

(nil allowed)
archived_at Must be a String Required

ISO 8601 timestamp when the card was archived, or null if active

(nil allowed)
rewards_count Must be a Integer Required

Number of rewards defined for this card
customer_cards_count Must be a Integer Required

Number of customer card instances issued
created_at Must be a String Required

ISO 8601 creation timestamp
updated_at Must be a String Required

ISO 8601 last-update timestamp

update

PATCH /api/v1/accounts/:account_id/cards/:id

Update a loyalty card

Updates an existing loyalty card template. Only the provided attributes are changed.

Parameters

Name Type Required Description
account_id Must be a Integer Required

Parent store ID
id Must be a Integer Required

Card ID
card Must be a Hash Required

Card attributes
card[name] Must be a String Optional

Card name
card[card_color] Must be a String Optional

Hex colour for the card background
card[text_color] Must be a String Optional

Hex colour for card text
card[stamp_icon] Must be a String Optional

Stamp icon identifier
card[stamp_color] Must be a String Optional

Hex colour for stamp icons
card[stamps_required] Must be a Integer Optional

Number of stamps needed (1–18)
card[initial_stamps] Must be a Integer Optional

Pre-filled stamps (must be >= 0 and < stamps_required)
card[strip_type] Must be a String Optional

Strip image type
card[strip_color] Must be a String Optional

Hex colour for the strip
card[strip_preset] Must be a String Optional

Preset strip image identifier
card[header_text] Must be a String Optional

Optional header text displayed on the card

Error Codes

Code Description
401 Unauthorized – invalid or missing API token
404 Card not found
422 Validation failed – check the `errors` object for details

Returns

Code: 200

The updated card object

Name Type Required Description
id Must be a Integer Required

Unique card ID
name Must be a String Required

Card name (e.g. ‘Coffee Loyalty Card’)
card_color Must be a String Required

Hex colour for the card background (e.g. ‘#6B4226’)
text_color Must be a String Required

Hex colour for card text
stamp_icon Must be a String Required

Icon used for stamps (e.g. ‘coffee’, ‘heart’, ‘star’)
stamp_color Must be a String Required

Hex colour for stamp icons
stamps_required Must be a Integer Required

Number of stamps needed to complete the card (1–18)
initial_stamps Must be a Integer Required

Number of stamps pre-filled on new customer cards (0 to stamps_required - 1)
strip_type Must be a String Required

Strip image type: ‘color’, ‘image’, or ‘preset’
strip_color Must be a String Required

Hex colour for the strip (when strip_type is ‘color’)

(nil allowed)
strip_preset Must be a String Required

Preset strip image identifier (when strip_type is ‘preset’)

(nil allowed)
header_text Must be a String Required

Optional header text displayed on the card

(nil allowed)
archived_at Must be a String Required

ISO 8601 timestamp when the card was archived, or null if active

(nil allowed)
rewards_count Must be a Integer Required

Number of rewards defined for this card
customer_cards_count Must be a Integer Required

Number of customer card instances issued
created_at Must be a String Required

ISO 8601 creation timestamp
updated_at Must be a String Required

ISO 8601 last-update timestamp