Posters

Manage QR code signup posters

Posters are printable QR code signup sheets that customers scan to join your loyalty program. Each poster is tied to a loyalty card and generates a unique public signup URL. Posters can be customized with colors, titles, and paper sizes to match your store branding.

index

GET /api/v1/accounts/:account_id/posters

List posters

Returns all posters for the store. Optionally filter by card or active status.

Parameters

Name Type Required Description
account_id Must be a number. Required

Store (account) ID
card_id Must be a number. Optional

Filter posters belonging to a specific card
active Must be a String Optional

When present, return only active posters

Error Codes

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

Returns

Code: 200

An array of poster objects

Name Type Required Description
id Must be a Integer Required

Unique poster ID
account_id Must be a Integer Required

Parent store ID
card_id Must be a Integer Required

Loyalty card customers are signed up to
title Must be a String Required

Heading printed on the poster

(nil allowed)
paper_size Must be a String Required

Paper size the poster is laid out for
primary_color Must be a String Required

Hex colour for the poster background

(nil allowed)
secondary_color Must be a String Required

Hex accent colour

(nil allowed)
text_color Must be a String Required

Hex colour for poster text

(nil allowed)
contact_collection_mode Must be a String Required

Which contact fields appear on the public signup form: ‘email_and_phone’, ‘email_only’, or ‘phone_only’
collect_email Must be one of: true, false, 1, 0. Required

Whether the public signup form collects email
collect_phone Must be one of: true, false, 1, 0. Required

Whether the public signup form collects phone number
require_email Must be one of: true, false, 1, 0. Required

Whether email is required when it is collected
require_phone Must be one of: true, false, 1, 0. Required

Whether phone number is required when it is collected
require_birthday Must be one of: true, false, 1, 0. Required

Whether date of birth is required on the public signup form
minimum_age Must be a Integer Required

Minimum customer age required for signup

(nil allowed)
active Must be one of: true, false, 1, 0. Required

Whether the public signup URL is live
signup_url Must be a String Required

Public URL the QR code points at
display_url Must be a String Required

URL of the on screen version of the poster
qr_code_url Must be a String Required

URL encoded in the QR code
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/posters/:id

Show a poster

Returns a single poster by ID, including generated signup and display URLs.

Parameters

Name Type Required Description
account_id Must be a number. Required

Store (account) ID
id Must be a number. Required

Poster ID

Error Codes

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

Returns

Code: 200

A poster object

Name Type Required Description
id Must be a Integer Required

Unique poster ID
account_id Must be a Integer Required

Parent store ID
card_id Must be a Integer Required

Loyalty card customers are signed up to
title Must be a String Required

Heading printed on the poster

(nil allowed)
paper_size Must be a String Required

Paper size the poster is laid out for
primary_color Must be a String Required

Hex colour for the poster background

(nil allowed)
secondary_color Must be a String Required

Hex accent colour

(nil allowed)
text_color Must be a String Required

Hex colour for poster text

(nil allowed)
contact_collection_mode Must be a String Required

Which contact fields appear on the public signup form: ‘email_and_phone’, ‘email_only’, or ‘phone_only’
collect_email Must be one of: true, false, 1, 0. Required

Whether the public signup form collects email
collect_phone Must be one of: true, false, 1, 0. Required

Whether the public signup form collects phone number
require_email Must be one of: true, false, 1, 0. Required

Whether email is required when it is collected
require_phone Must be one of: true, false, 1, 0. Required

Whether phone number is required when it is collected
require_birthday Must be one of: true, false, 1, 0. Required

Whether date of birth is required on the public signup form
minimum_age Must be a Integer Required

Minimum customer age required for signup

(nil allowed)
active Must be one of: true, false, 1, 0. Required

Whether the public signup URL is live
signup_url Must be a String Required

Public URL the QR code points at
display_url Must be a String Required

URL of the on screen version of the poster
qr_code_url Must be a String Required

URL encoded in the QR code
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/posters

Create a poster

Creates a new printable QR code poster for customer signup. The poster will automatically generate a unique public signup URL and QR code. The card_id is required on create to associate the poster with a loyalty card.

Parameters

Name Type Required Description
account_id Must be a number. Required

Store (account) ID
poster Must be a Hash Required

Poster attributes
poster[card_id] Must be a number. Required

ID of the loyalty card this poster links to
poster[title] Must be a String Optional

Headline text displayed on the poster
poster[paper_size] Must be a String Optional

Print size – one of: a4, a5, a6, letter
poster[primary_color] Must be a String Optional

Primary brand color as a hex string (e.g. ‘#FF5733’)
poster[secondary_color] Must be a String Optional

Secondary brand color as a hex string
poster[text_color] Must be a String Optional

Text color as a hex string
poster[contact_collection_mode] Must be a String Optional

Which contact fields appear on the public signup form
poster[require_email] Must be one of: true, false, 1, 0. Optional

Whether email is required when it is collected
poster[require_phone] Must be one of: true, false, 1, 0. Optional

Whether phone number is required when it is collected
poster[require_birthday] Must be one of: true, false, 1, 0. Optional

Whether date of birth is required on the public signup form
poster[minimum_age] Must be a number. Optional

Minimum customer age required for signup. Requires require_birthday to be true.
poster[active] Must be one of: true, false, 1, 0. Optional

Whether the poster is active (defaults to true)

Error Codes

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

Returns

Code: 201

The newly created poster object

Name Type Required Description
id Must be a Integer Required

Unique poster ID
account_id Must be a Integer Required

Parent store ID
card_id Must be a Integer Required

Loyalty card customers are signed up to
title Must be a String Required

Heading printed on the poster

(nil allowed)
paper_size Must be a String Required

Paper size the poster is laid out for
primary_color Must be a String Required

Hex colour for the poster background

(nil allowed)
secondary_color Must be a String Required

Hex accent colour

(nil allowed)
text_color Must be a String Required

Hex colour for poster text

(nil allowed)
contact_collection_mode Must be a String Required

Which contact fields appear on the public signup form: ‘email_and_phone’, ‘email_only’, or ‘phone_only’
collect_email Must be one of: true, false, 1, 0. Required

Whether the public signup form collects email
collect_phone Must be one of: true, false, 1, 0. Required

Whether the public signup form collects phone number
require_email Must be one of: true, false, 1, 0. Required

Whether email is required when it is collected
require_phone Must be one of: true, false, 1, 0. Required

Whether phone number is required when it is collected
require_birthday Must be one of: true, false, 1, 0. Required

Whether date of birth is required on the public signup form
minimum_age Must be a Integer Required

Minimum customer age required for signup

(nil allowed)
active Must be one of: true, false, 1, 0. Required

Whether the public signup URL is live
signup_url Must be a String Required

Public URL the QR code points at
display_url Must be a String Required

URL of the on screen version of the poster
qr_code_url Must be a String Required

URL encoded in the QR code
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/posters/:id

Update a poster

Updates an existing poster. The card_id cannot be changed after creation.

Parameters

Name Type Required Description
account_id Must be a number. Required

Store (account) ID
id Must be a number. Required

Poster ID
poster Must be a Hash Required

Poster attributes to update
poster[title] Must be a String Optional

Headline text displayed on the poster
poster[paper_size] Must be a String Optional

Print size – one of: a4, a5, a6, letter
poster[primary_color] Must be a String Optional

Primary brand color as a hex string
poster[secondary_color] Must be a String Optional

Secondary brand color as a hex string
poster[text_color] Must be a String Optional

Text color as a hex string
poster[contact_collection_mode] Must be a String Optional

Which contact fields appear on the public signup form
poster[require_email] Must be one of: true, false, 1, 0. Optional

Whether email is required when it is collected
poster[require_phone] Must be one of: true, false, 1, 0. Optional

Whether phone number is required when it is collected
poster[require_birthday] Must be one of: true, false, 1, 0. Optional

Whether date of birth is required on the public signup form
poster[minimum_age] Must be a number. Optional

Minimum customer age required for signup. Requires require_birthday to be true.
poster[active] Must be one of: true, false, 1, 0. Optional

Whether the poster is active

Error Codes

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

Returns

Code: 200

The updated poster object

Name Type Required Description
id Must be a Integer Required

Unique poster ID
account_id Must be a Integer Required

Parent store ID
card_id Must be a Integer Required

Loyalty card customers are signed up to
title Must be a String Required

Heading printed on the poster

(nil allowed)
paper_size Must be a String Required

Paper size the poster is laid out for
primary_color Must be a String Required

Hex colour for the poster background

(nil allowed)
secondary_color Must be a String Required

Hex accent colour

(nil allowed)
text_color Must be a String Required

Hex colour for poster text

(nil allowed)
contact_collection_mode Must be a String Required

Which contact fields appear on the public signup form: ‘email_and_phone’, ‘email_only’, or ‘phone_only’
collect_email Must be one of: true, false, 1, 0. Required

Whether the public signup form collects email
collect_phone Must be one of: true, false, 1, 0. Required

Whether the public signup form collects phone number
require_email Must be one of: true, false, 1, 0. Required

Whether email is required when it is collected
require_phone Must be one of: true, false, 1, 0. Required

Whether phone number is required when it is collected
require_birthday Must be one of: true, false, 1, 0. Required

Whether date of birth is required on the public signup form
minimum_age Must be a Integer Required

Minimum customer age required for signup

(nil allowed)
active Must be one of: true, false, 1, 0. Required

Whether the public signup URL is live
signup_url Must be a String Required

Public URL the QR code points at
display_url Must be a String Required

URL of the on screen version of the poster
qr_code_url Must be a String Required

URL encoded in the QR code
created_at Must be a String Required

ISO 8601 creation timestamp
updated_at Must be a String Required

ISO 8601 last-update timestamp

destroy

DELETE /api/v1/accounts/:account_id/posters/:id

Delete a poster

Permanently deletes a poster. The public signup URL will stop working.

Parameters

Name Type Required Description
account_id Must be a number. Required

Store (account) ID
id Must be a number. Required

Poster ID

Error Codes

Code Description
401 Unauthorized – invalid or missing API token
404 Store or poster not found
422 Poster could not be deleted

Returns

Code: 204

No content. The poster was deleted and its signup URL deactivated.