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[stamp_background_color]`	Must be a String	Optional	Hex colour for stamp backgrounds
`card[stamps_required]`	Must be a Integer	Optional	Number of stamps needed to complete the card (1–21)
`card[initial_stamps]`	Must be a Integer	Optional	Number of stamps pre-filled on new customer cards (must be >= 0 and < stamps_required)
`card[show_member_field]`	Must be one of: `true`, `false`, `1`, `0`.	Optional	Whether wallet passes show the member name field
`card[show_stamps_to_reward_field]`	Must be one of: `true`, `false`, `1`, `0`.	Optional	Whether wallet passes show the stamps-to-reward field
`card[auxiliary_fields]`	Must be an Array of nested elements	Optional	Up to two extra front-of-pass fields. Blank values are ignored.
`card[auxiliary_fields][label]`	Must be a String	Optional	Optional label displayed above the value
`card[auxiliary_fields][value]`	Must be a String	Required	Value displayed on the pass
`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
`card[expires_at]`	Must be a String	Optional	Card expiry timestamp (ISO 8601)

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
`stamp_background_color`	Must be a String	Required	Hex colour for stamp backgrounds
`stamps_required`	Must be a Integer	Required	Number of stamps needed to complete the card (1–21)
`initial_stamps`	Must be a Integer	Required	Number of stamps pre-filled on new customer cards (0 to stamps_required - 1)
`show_member_field`	Must be one of: `true`, `false`, `1`, `0`.	Required	Whether wallet passes show the member name field
`show_stamps_to_reward_field`	Must be one of: `true`, `false`, `1`, `0`.	Required	Whether wallet passes show the stamps-to-reward field
`auxiliary_fields`	Must be an Array of nested elements	Required	Up to two extra front-of-pass fields
`auxiliary_fields[key]`	Must be a String	Required	Generated wallet pass field key
`auxiliary_fields[label]`	Must be a String	Required	Optional field label (nil allowed)
`auxiliary_fields[value]`	Must be a String	Required	Field value
`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)
`expires_at`	Must be a String	Required	ISO 8601 timestamp when the card expires, or null if it does not expire (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