create_card

Saves a loyalty card design and its rewards to a Leal store, ready for customers to add to Apple Wallet or Google Wallet. Takes the same design fields as preview_card_designs. Logos and strip photos are fetched from their URLs; if the store has no logo yet, the card's logo becomes the store logo. Needs a Leal account: the person is asked to sign in or create one.

Argument	Type	Description
name*	string	Internal name for the card, e.g. "Coffee card". Shown in Leal, not on the pass.
rewards*	array	Rewards customers can redeem, e.g. [{name: "Free coffee", stamps_required: 10}]. The free plan allows one reward per card.
logo_url	string	Public https URL of the wide logo shown top-left of the Apple pass (PNG, JPEG, WebP, GIF or SVG; transparent PNG works best). Ideally a version that reads on card_color.
store_id	integer	Store id from list_stores. Optional when the login has one store.
card_color	string	Pass background colour, hex (#RRGGBB).
stamp_icon	string	Icon shown in each collected stamp.
strip_type	string	Background of the stamp strip: a flat colour, one of Leal's preset photos, or an image from strip_image_url.
text_color	string	Colour of all text on the pass, hex. Must read clearly on card_color (4.5:1 contrast or better).
header_text	string	Text at the top of the pass. Defaults to the store name. Wallet apps truncate long headers, so keep it short.
stamp_color	string	Colour of the icon inside a collected stamp, hex. Must read clearly on stamp_background_color.
strip_color	string	Strip colour, hex. Also shows behind preset and image strips when strip_opacity is below 100.
strip_preset	string	Preset strip photo, used when strip_type is preset.
strip_opacity	integer	Opacity of the strip colour or image over the card colour. 100 shows it exactly; 60–85 tints a photo with the card colour so stamps stand out.
initial_stamps	integer	Stamps a new customer starts with (a head start). Must be less than stamps_required.
square_logo_url	string	Public https URL of a square logo or icon, used as the round logo on Google Wallet.
stamps_required	integer	Stamps needed to fill the card. 6, 8 or 10 are common.
strip_image_url	string	Public https URL of a wide photo for the strip (strip_type image), e.g. a hero image from the brand's website. Cropped to 375×144.
auxiliary_fields	array	Up to two extra front-of-pass fields, e.g. {label: "Perk", value: "10% off pastries"}.
show_member_field	boolean	Show the customer's name on the front of the pass. Default true.
stamp_background_color	string	Fill colour of a collected stamp circle, hex. Empty stamp slots use a translucent version of it, so it should stand out from the strip.
show_stamps_to_reward_field	boolean	Show how many stamps until the next reward. Default true.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "name",
    "rewards"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 60,
      "description": "Internal name for the card, e.g. \"Coffee card\". Shown in Leal, not on the pass."
    },
    "rewards": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "name",
          "stamps_required"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 60
          },
          "description": {
            "type": "string",
            "maxLength": 200
          },
          "stamps_required": {
            "type": "integer",
            "minimum": 1,
            "description": "Stamps spent to redeem. Usually equal to the card's stamps_required."
          }
        }
      },
      "maxItems": 5,
      "minItems": 1,
      "description": "Rewards customers can redeem, e.g. [{name: \"Free coffee\", stamps_required: 10}]. The free plan allows one reward per card."
    },
    "logo_url": {
      "type": "string",
      "description": "Public https URL of the wide logo shown top-left of the Apple pass (PNG, JPEG, WebP, GIF or SVG; transparent PNG works best). Ideally a version that reads on card_color."
    },
    "store_id": {
      "type": "integer",
      "description": "Store id from list_stores. Optional when the login has one store."
    },
    "card_color": {
      "type": "string",
      "description": "Pass background colour, hex (#RRGGBB)."
    },
    "stamp_icon": {
      "enum": [
        "star",
        "heart",
        "coffee",
        "coffee_bean",
        "pint_glass",
        "cake",
        "barbell",
        "check",
        "spray_bottle",
        "shopping_trolley",
        "diamond",
        "high_heel",
        "hairdryer",
        "paw_print",
        "scissors",
        "sun",
        "flower",
        "coat_hanger"
      ],
      "type": "string",
      "description": "Icon shown in each collected stamp."
    },
    "strip_type": {
      "enum": [
        "color",
        "preset",
        "image"
      ],
      "type": "string",
      "description": "Background of the stamp strip: a flat colour, one of Leal's preset photos, or an image from strip_image_url."
    },
    "text_color": {
      "type": "string",
      "description": "Colour of all text on the pass, hex. Must read clearly on card_color (4.5:1 contrast or better)."
    },
    "header_text": {
      "type": "string",
      "maxLength": 40,
      "description": "Text at the top of the pass. Defaults to the store name. Wallet apps truncate long headers, so keep it short."
    },
    "stamp_color": {
      "type": "string",
      "description": "Colour of the icon inside a collected stamp, hex. Must read clearly on stamp_background_color."
    },
    "strip_color": {
      "type": "string",
      "description": "Strip colour, hex. Also shows behind preset and image strips when strip_opacity is below 100."
    },
    "strip_preset": {
      "enum": [
        "coffee_beans",
        "coffee_cup",
        "bakery",
        "pizza",
        "sushi",
        "burger",
        "ice_cream",
        "smoothie",
        "flowers",
        "spa"
      ],
      "type": "string",
      "description": "Preset strip photo, used when strip_type is preset."
    },
    "strip_opacity": {
      "type": "integer",
      "maximum": 100,
      "minimum": 0,
      "description": "Opacity of the strip colour or image over the card colour. 100 shows it exactly; 60–85 tints a photo with the card colour so stamps stand out."
    },
    "initial_stamps": {
      "type": "integer",
      "minimum": 0,
      "description": "Stamps a new customer starts with (a head start). Must be less than stamps_required."
    },
    "square_logo_url": {
      "type": "string",
      "description": "Public https URL of a square logo or icon, used as the round logo on Google Wallet."
    },
    "stamps_required": {
      "type": "integer",
      "maximum": 21,
      "minimum": 1,
      "description": "Stamps needed to fill the card. 6, 8 or 10 are common."
    },
    "strip_image_url": {
      "type": "string",
      "description": "Public https URL of a wide photo for the strip (strip_type image), e.g. a hero image from the brand's website. Cropped to 375×144."
    },
    "auxiliary_fields": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "value"
        ],
        "properties": {
          "label": {
            "type": "string",
            "maxLength": 20
          },
          "value": {
            "type": "string",
            "maxLength": 30
          }
        }
      },
      "maxItems": 2,
      "description": "Up to two extra front-of-pass fields, e.g. {label: \"Perk\", value: \"10% off pastries\"}."
    },
    "show_member_field": {
      "type": "boolean",
      "description": "Show the customer's name on the front of the pass. Default true."
    },
    "stamp_background_color": {
      "type": "string",
      "description": "Fill colour of a collected stamp circle, hex. Empty stamp slots use a translucent version of it, so it should stand out from the strip."
    },
    "show_stamps_to_reward_field": {
      "type": "boolean",
      "description": "Show how many stamps until the next reward. Default true."
    }
  }
}

create_location

Adds a physical location to a store. The address is geocoded so wallet passes can remind customers nearby.

Argument	Type	Description
name*	string	e.g. "Main Street" or the store name for a single shop.
address*	string	Full street address including town and postcode.
store_id	integer	Store id from list_stores. Optional when the login has one store.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "name",
    "address"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 60,
      "description": "e.g. \"Main Street\" or the store name for a single shop."
    },
    "address": {
      "type": "string",
      "maxLength": 300,
      "description": "Full street address including town and postcode."
    },
    "store_id": {
      "type": "integer",
      "description": "Store id from list_stores. Optional when the login has one store."
    }
  }
}

create_poster

Creates a printable poster with a QR code for a card. Customers scan it, fill in a short form on a public Leal signup page, and add the card to their wallet. Returns the signup link and a print link. Colours default to the card's.

Argument	Type	Description
title	string	Headline, e.g. "Join our coffee club". Defaults to the card name.
card_id*	integer	Card id from list_cards.
paper_size	string	Default a4.
text_color	string	Poster text colour, hex. Defaults to the card's text colour.
primary_color	string	Poster background colour, hex. Defaults to the card colour.
secondary_color	string	Accent panel colour, hex.
require_birthday	boolean	Ask for a birthday (for birthday rewards). Default false.
contact_collection_mode	string	What the signup form asks for. Default email_and_phone.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "card_id"
  ],
  "properties": {
    "title": {
      "type": "string",
      "maxLength": 60,
      "description": "Headline, e.g. \"Join our coffee club\". Defaults to the card name."
    },
    "card_id": {
      "type": "integer",
      "description": "Card id from list_cards."
    },
    "paper_size": {
      "enum": [
        "a4",
        "a5",
        "a6",
        "letter"
      ],
      "type": "string",
      "description": "Default a4."
    },
    "text_color": {
      "type": "string",
      "description": "Poster text colour, hex. Defaults to the card's text colour."
    },
    "primary_color": {
      "type": "string",
      "description": "Poster background colour, hex. Defaults to the card colour."
    },
    "secondary_color": {
      "type": "string",
      "description": "Accent panel colour, hex."
    },
    "require_birthday": {
      "type": "boolean",
      "description": "Ask for a birthday (for birthday rewards). Default false."
    },
    "contact_collection_mode": {
      "enum": [
        "email_and_phone",
        "email_only",
        "phone_only"
      ],
      "type": "string",
      "description": "What the signup form asks for. Default email_and_phone."
    }
  }
}

create_reward

Adds a reward that customers can redeem with stamps from a card, e.g. a free coffee at 10 stamps.

Argument	Type	Description
name*	string	What the customer gets, e.g. "Free coffee".
card_id*	integer	Card id from list_cards.
description	string	Optional details, e.g. "Any size, any drink".
stamps_required*	integer	Stamps spent to redeem it.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "card_id",
    "name",
    "stamps_required"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 60,
      "description": "What the customer gets, e.g. \"Free coffee\"."
    },
    "card_id": {
      "type": "integer",
      "description": "Card id from list_cards."
    },
    "description": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional details, e.g. \"Any size, any drink\"."
    },
    "stamps_required": {
      "type": "integer",
      "minimum": 1,
      "description": "Stamps spent to redeem it."
    }
  }
}

create_store

Adds a new, empty store to the login's agency, with its own cards, posters and locations: for a client, a second business, or a demo to show a prospect. Then set it up with create_card, create_poster and create_location using the returned store_id. Don't use this to set up a store the login already has: call list_stores first and use the existing store if it's the same business.

Argument	Type	Description
name*	string	Store name in Leal, usually the business or client name, e.g. "Bean There Coffee".
logo_url	string	Public https URL of the wide logo (PNG, JPEG, WebP, GIF or SVG), e.g. from get_brand_kit.
agency_id	integer	Agency id from list_stores. Only needed when this login runs several agencies.
store_name	string	Public name customers see on cards and signup pages, if different from name.
square_logo_url	string	Public https URL of a square logo or icon.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 60,
      "description": "Store name in Leal, usually the business or client name, e.g. \"Bean There Coffee\"."
    },
    "logo_url": {
      "type": "string",
      "description": "Public https URL of the wide logo (PNG, JPEG, WebP, GIF or SVG), e.g. from get_brand_kit."
    },
    "agency_id": {
      "type": "integer",
      "description": "Agency id from list_stores. Only needed when this login runs several agencies."
    },
    "store_name": {
      "type": "string",
      "maxLength": 60,
      "description": "Public name customers see on cards and signup pages, if different from name."
    },
    "square_logo_url": {
      "type": "string",
      "description": "Public https URL of a square logo or icon."
    }
  }
}

get_brand_kit

Reads a business's public website and returns its name, a colour palette (with where each colour was found; colours read from the logo are the most reliable, and website-builder default colours are filtered out), logo and icon image URLs, a hero image, a guess at the type of business, and a suggested starting card design built from those. Works without a Leal account. Use the result to propose card designs with preview_card_designs.

read-only

Argument	Type	Description
url*	string	The business's website, e.g. https://beanthere.coffee or beanthere.coffee.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "url"
  ],
  "properties": {
    "url": {
      "type": "string",
      "description": "The business's website, e.g. https://beanthere.coffee or beanthere.coffee."
    }
  }
}

get_card

Shows a saved loyalty card's design and rewards, with an Apple and Google Wallet preview.

read-only

Argument	Type	Description
card_id*	integer	Card id from list_cards.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "card_id"
  ],
  "properties": {
    "card_id": {
      "type": "integer",
      "description": "Card id from list_cards."
    }
  }
}

get_store_setup

Shows a store's setup checklist (store details, card, poster, first customer, staff app), plan limits and usage, and its cards with rewards, locations and posters.

read-only

Argument	Type	Description
store_id	integer	Store id from list_stores. Optional when the login has one store.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "store_id": {
      "type": "integer",
      "description": "Store id from list_stores. Optional when the login has one store."
    }
  }
}

list_cards

Lists a store's loyalty cards with their rewards.

read-only

Argument	Type	Description
store_id	integer	Store id from list_stores. Optional when the login has one store.
include_archived	boolean	Include archived cards. Default false.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "store_id": {
      "type": "integer",
      "description": "Store id from list_stores. Optional when the login has one store."
    },
    "include_archived": {
      "type": "boolean",
      "description": "Include archived cards. Default false."
    }
  }
}

list_design_options

Lists what a Leal loyalty card can look like: stamp icons, preset strip photos, limits, and how the pass is laid out on Apple and Google Wallet. Works without a Leal account.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {}
}

list_stores

Lists the Leal stores this login can manage, with each store's id, plan and how far through setup it is, and the agencies it can add new stores to with create_store.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {}
}

preview_card_designs

Renders one to four loyalty card designs as Apple Wallet and Google Wallet passes so the person can compare them and pick one. Checks each design against Leal's rules and flags hard-to-read colour combinations. Returns a shareable preview link per design. Works without a Leal account; nothing is saved.

read-only

Argument	Type	Description
designs*	array	The designs to show side by side.
store_name	string	The business name, shown where the pass shows the store.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "designs"
  ],
  "properties": {
    "designs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 60,
            "description": "Internal name for the card, e.g. \"Coffee card\". Shown in Leal, not on the pass."
          },
          "label": {
            "type": "string",
            "maxLength": 30,
            "description": "Short name for this direction, e.g. \"Espresso\" or \"Light & airy\"."
          },
          "reward": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "stamps_required": {
                "type": "integer",
                "minimum": 1
              }
            },
            "description": "The main reward, shown under the preview."
          },
          "logo_url": {
            "type": "string",
            "description": "Public https URL of the wide logo shown top-left of the Apple pass (PNG, JPEG, WebP, GIF or SVG; transparent PNG works best). Ideally a version that reads on card_color."
          },
          "rationale": {
            "type": "string",
            "maxLength": 160,
            "description": "One sentence on why this design suits the brand."
          },
          "card_color": {
            "type": "string",
            "description": "Pass background colour, hex (#RRGGBB)."
          },
          "stamp_icon": {
            "enum": [
              "star",
              "heart",
              "coffee",
              "coffee_bean",
              "pint_glass",
              "cake",
              "barbell",
              "check",
              "spray_bottle",
              "shopping_trolley",
              "diamond",
              "high_heel",
              "hairdryer",
              "paw_print",
              "scissors",
              "sun",
              "flower",
              "coat_hanger"
            ],
            "type": "string",
            "description": "Icon shown in each collected stamp."
          },
          "strip_type": {
            "enum": [
              "color",
              "preset",
              "image"
            ],
            "type": "string",
            "description": "Background of the stamp strip: a flat colour, one of Leal's preset photos, or an image from strip_image_url."
          },
          "text_color": {
            "type": "string",
            "description": "Colour of all text on the pass, hex. Must read clearly on card_color (4.5:1 contrast or better)."
          },
          "header_text": {
            "type": "string",
            "maxLength": 40,
            "description": "Text at the top of the pass. Defaults to the store name. Wallet apps truncate long headers, so keep it short."
          },
          "stamp_color": {
            "type": "string",
            "description": "Colour of the icon inside a collected stamp, hex. Must read clearly on stamp_background_color."
          },
          "strip_color": {
            "type": "string",
            "description": "Strip colour, hex. Also shows behind preset and image strips when strip_opacity is below 100."
          },
          "strip_preset": {
            "enum": [
              "coffee_beans",
              "coffee_cup",
              "bakery",
              "pizza",
              "sushi",
              "burger",
              "ice_cream",
              "smoothie",
              "flowers",
              "spa"
            ],
            "type": "string",
            "description": "Preset strip photo, used when strip_type is preset."
          },
          "strip_opacity": {
            "type": "integer",
            "maximum": 100,
            "minimum": 0,
            "description": "Opacity of the strip colour or image over the card colour. 100 shows it exactly; 60–85 tints a photo with the card colour so stamps stand out."
          },
          "initial_stamps": {
            "type": "integer",
            "minimum": 0,
            "description": "Stamps a new customer starts with (a head start). Must be less than stamps_required."
          },
          "square_logo_url": {
            "type": "string",
            "description": "Public https URL of a square logo or icon, used as the round logo on Google Wallet."
          },
          "stamps_required": {
            "type": "integer",
            "maximum": 21,
            "minimum": 1,
            "description": "Stamps needed to fill the card. 6, 8 or 10 are common."
          },
          "strip_image_url": {
            "type": "string",
            "description": "Public https URL of a wide photo for the strip (strip_type image), e.g. a hero image from the brand's website. Cropped to 375×144."
          },
          "auxiliary_fields": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "value"
              ],
              "properties": {
                "label": {
                  "type": "string",
                  "maxLength": 20
                },
                "value": {
                  "type": "string",
                  "maxLength": 30
                }
              }
            },
            "maxItems": 2,
            "description": "Up to two extra front-of-pass fields, e.g. {label: \"Perk\", value: \"10% off pastries\"}."
          },
          "show_member_field": {
            "type": "boolean",
            "description": "Show the customer's name on the front of the pass. Default true."
          },
          "stamp_background_color": {
            "type": "string",
            "description": "Fill colour of a collected stamp circle, hex. Empty stamp slots use a translucent version of it, so it should stand out from the strip."
          },
          "show_stamps_to_reward_field": {
            "type": "boolean",
            "description": "Show how many stamps until the next reward. Default true."
          }
        }
      },
      "maxItems": 4,
      "minItems": 1,
      "description": "The designs to show side by side."
    },
    "store_name": {
      "type": "string",
      "description": "The business name, shown where the pass shows the store."
    }
  }
}

update_card

Changes a saved card's design. Only the fields passed change; the rest stay as they are. Customers' passes in Apple Wallet and Google Wallet update automatically.

destructive

Argument	Type	Description
name	string	Internal name for the card, e.g. "Coffee card". Shown in Leal, not on the pass.
card_id*	integer	Card id from list_cards.
logo_url	string	Public https URL of the wide logo shown top-left of the Apple pass (PNG, JPEG, WebP, GIF or SVG; transparent PNG works best). Ideally a version that reads on card_color.
card_color	string	Pass background colour, hex (#RRGGBB).
stamp_icon	string	Icon shown in each collected stamp.
strip_type	string	Background of the stamp strip: a flat colour, one of Leal's preset photos, or an image from strip_image_url.
text_color	string	Colour of all text on the pass, hex. Must read clearly on card_color (4.5:1 contrast or better).
header_text	string	Text at the top of the pass. Defaults to the store name. Wallet apps truncate long headers, so keep it short.

update_reward

Changes a reward's name, stamps needed or description, or turns it off. Only the fields passed change.

destructive

Argument	Type	Description
name	string
active	boolean	false hides the reward from customers and staff.
reward_id*	integer	Reward id from list_cards or get_store_setup.
description	string
stamps_required	integer

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "reward_id"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 60
    },
    "active": {
      "type": "boolean",
      "description": "false hides the reward from customers and staff."
    },
    "reward_id": {
      "type": "integer",
      "description": "Reward id from list_cards or get_store_setup."
    },
    "description": {
      "type": "string",
      "maxLength": 200
    },
    "stamps_required": {
      "type": "integer",
      "minimum": 1
    }
  }
}

update_store

Sets a store's public name and logos, which Leal uses on cards, posters and signup pages. Logos are fetched from public image URLs (PNG, JPEG, WebP, GIF or SVG). Replaces the current values.

destructive

Argument	Type	Description
logo_url	string	Public https URL of the wide logo.
store_id	integer	Store id from list_stores. Optional when the login has one store.
store_name	string	The business name customers know, e.g. "Bean There Coffee".
square_logo_url	string	Public https URL of a square logo or icon.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "logo_url": {
      "type": "string",
      "description": "Public https URL of the wide logo."
    },
    "store_id": {
      "type": "integer",
      "description": "Store id from list_stores. Optional when the login has one store."
    },
    "store_name": {
      "type": "string",
      "maxLength": 60,
      "description": "The business name customers know, e.g. \"Bean There Coffee\"."
    },
    "square_logo_url": {
      "type": "string",
      "description": "Public https URL of a square logo or icon."
    }
  }
}

Leal

Try it

create_card

Leal

Try it

create_card

Tools (15)