Create Loyalty Template API

Overview

A loyalty pass is a Dynamic Pass with a progress counter — a stamp card ("buy 5, get 1 free") or a points counter. This endpoint creates the loyalty template, which behaves like a dynamic pass template plus a loyaltyProgressData block describing the counter.

Authentication

All API requests must include your API key in the request headers:

"apikey": "your-api-key-here"

Request Body

The body is a pass template (same design fields as the Dynamic Pass template — see Create Template for the shared fields and {placeholder} syntax) with two loyalty additions: cardSubType and loyaltyProgressData.

loyaltyProgressData

This block is what makes the pass a loyalty card, and it comes in two shapes — pick one with loyaltyType and send the matching counter object:

• STAMP — a row of stamp icons that fill up (e.g. "buy 5 coffees, get 1 free"). Send stampCounter.
• TEXT — a "current / max" points counter (e.g. "60 / 100 pts"). Send textCounter.

Stamp icons

For STAMP cards, stampIconName chooses the icon drawn in each stamp slot. Use one of these built-in names:

• coffeeIcon2 — Coffee cup (default)
• coffeeIcon3 — Coffee cup (alternate style)
• burgerIcon1 — Burger
• donut1 — Donut
• iceCream1 — Ice cream
• pizza1 — Pizza slice
• sandwich1 — Sandwich

Request Examples

The two loyalty types take different bodies. Switch tabs to see a complete, copy-pasteable request for each:

curl -X POST 'https://app.addtowallet.co/api/v2/loyaltyPass/template' \
  -H 'apikey: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Cafe Muse Loyalty Card",
  "cardSubType": "dynamic_loyalty_stamp_card",
  "groupId": "66b6005bb7bddce8f05a3392",
  "cardTitle": "Cafe Muse",
  "hexBackgroundColor": "#45290d",
  "appleFontColor": "#ffffff",
  "logoUrl": "https://s3.amazonaws.com/i.addtowallet.co/assets/cafe-muse-logo.png",
  "barcodeType": "QR_CODE",
  "barcodeValue": "{_customerId}",
  "textModulesData": [
    {
      "id": "r1start",
      "header": "Member",
      "body": "{name}"
    }
  ],
  "header": "FREE COFFEE",
  "subheader": "REWARD ON 5TH VISIT",
  "loyaltyProgressData": {
    "loyaltyType": "STAMP",
    "stampCounter": {
      "maxStampCount": 5,
      "initialStampCount": 0,
      "stampIconName": "coffeeIcon2",
      "stampBannerBgColor": "#45290d",
      "stampBannerIconBgColor": "#ffffff"
    }
  }
}'

Response

On success the API returns:

• dynamicPassId (string): ID of the created loyalty template. Use it as the dynamicPassId when checking members in.
• message (string): Confirmation message.

Response Example

{
  "dynamicPassId": "686d0d92c2f0bc5cdf25c834",
  "message": "Template created successfully"
}

Updating & deleting a loyalty template

A loyalty template is stored as a dynamic pass template, so you manage its lifecycle with the same template endpoints — there is no separate loyalty update/delete:

• Fetch / list — Get Template and List Templates return loyalty templates too (the loyaltyProgressData block is included).
• Update — Update Template works, with the caveats below.
• Delete — Delete Template behaves exactly like a dynamic template: it soft-deletes the template and queues removal of every pass issued from it.