Leal

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.

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

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.

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

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.

{
  "type": "object",
  "properties": {
    "store_name": {
      "type": "string",
      "description": "The business name, shown where the pass shows the store."
    },
    "designs": {
      "type": "array",
      "minItems": 1,
      "maxItems": 4,
      "description": "The designs to show side by side.",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "maxLength": 30,
            "description": "Short name for this direction, e.g. \"Espresso\" or \"Light & airy\"."
          },
          "rationale": {
            "type": "string",
            "maxLength": 160,
            "description": "One sentence on why this design suits the brand."
          },
          "reward": {
            "type": "object",
            "description": "The main reward, shown under the preview.",
            "properties": {
              "name": {
                "type": "string"
              },
              "stamps_required": {
                "type": "integer",
                "minimum": 1
              }
            }
          },
          "name": {
            "type": "string",
            "maxLength": 60,
            "description": "Internal name for the card, e.g. \"Coffee card\". Shown in Leal, not on the pass."
          },
          "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."
          },
          "card_color": {
            "type": "string",
            "description": "Pass background colour, hex (#RRGGBB)."
          },
          "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)."
          },
          "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."
          },
          "stamp_color": {
            "type": "string",
            "description": "Colour of the icon inside a collected stamp, hex. Must read clearly on stamp_background_color."
          },
          "stamp_icon": {
            "type": "string",
            "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"
            ],
            "description": "Icon shown in each collected stamp."
          },
          "stamps_required": {
            "type": "integer",
            "minimum": 1,
            "maximum": 21,
            "description": "Stamps needed to fill the card. 6, 8 or 10 are common."
          },
          "initial_stamps": {
            "type": "integer",
            "minimum": 0,
            "description": "Stamps a new customer starts with (a head start). Must be less than stamps_required."
          },
          "strip_type": {
            "type": "string",
            "enum": [
              "color",
              "preset",
              "image"
            ],
            "description": "Background of the stamp strip: a flat colour, one of Leal's preset photos, or an image from strip_image_url."
          },
          "strip_color": {
            "type": "string",
            "description": "Strip colour, hex. Also shows behind preset and image strips when strip_opacity is below 100."
          },
          "strip_opacity": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "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."
          },
          "strip_preset": {
            "type": "string",
            "enum": [
              "coffee_beans",
              "coffee_cup",
              "bakery",
              "pizza",
              "sushi",
              "burger",
              "ice_cream",
              "smoothie",
              "flowers",
              "spa"
            ],
            "description": "Preset strip photo, used when strip_type is preset."
          },
          "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."
          },
          "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."
          },
          "square_logo_url": {
            "type": "string",
            "description": "Public https URL of a square logo or icon, used as the round logo on Google Wallet."
          },
          "show_member_field": {
            "type": "boolean",
            "description": "Show the customer's name on the front of the pass. Default true."
          },
          "show_stamps_to_reward_field": {
            "type": "boolean",
            "description": "Show how many stamps until the next reward. Default true."
          },
          "auxiliary_fields": {
            "type": "array",
            "maxItems": 2,
            "description": "Up to two extra front-of-pass fields, e.g. {label: \"Perk\", value: \"10% off pastries\"}.",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string",
                  "maxLength": 20
                },
                "value": {
                  "type": "string",
                  "maxLength": 30
                }
              },
              "required": [
                "value"
              ]
            }
          }
        }
      }
    }
  },
  "required": [
    "designs"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

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.

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

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.

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

Lists a store's loyalty cards with their rewards.

{
  "type": "object",
  "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."
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

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

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

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.

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

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.

{
  "type": "object",
  "properties": {
    "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\"."
    },
    "logo_url": {
      "type": "string",
      "description": "Public https URL of the wide logo."
    },
    "square_logo_url": {
      "type": "string",
      "description": "Public https URL of a square logo or icon."
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

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.

{
  "type": "object",
  "properties": {
    "store_id": {
      "type": "integer",
      "description": "Store id from list_stores. Optional when the login has one store."
    },
    "name": {
      "type": "string",
      "maxLength": 60,
      "description": "Internal name for the card, e.g. \"Coffee card\". Shown in Leal, not on the pass."
    },
    "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."
    },
    "card_color": {
      "type": "string",
      "description": "Pass background colour, hex (#RRGGBB)."
    },
    "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)."
    },
    "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."
    },
    "stamp_color": {
      "type": "string",
      "description": "Colour of the icon inside a collected stamp, hex. Must read clearly on stamp_background_color."
    },
    "stamp_icon": {
      "type": "string",
      "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"
      ],
      "description": "Icon shown in each collected stamp."
    },
    "stamps_required": {
      "type": "integer",
      "minimum": 1,
      "maximum": 21,
      "description": "Stamps needed to fill the card. 6, 8 or 10 are common."
    },
    "initial_stamps": {
      "type": "integer",
      "minimum": 0,
      "description": "Stamps a new customer starts with (a head start). Must be less than stamps_required."
    },
    "strip_type": {
      "type": "string",
      "enum": [
        "color",
        "preset",
        "image"
      ],
      "description": "Background of the stamp strip: a flat colour, one of Leal's preset photos, or an image from strip_image_url."
    },
    "strip_color": {
      "type": "string",
      "description": "Strip colour, hex. Also shows behind preset and image strips when strip_opacity is below 100."
    },
    "strip_opacity": {
      "type": "integer",
      "minimum": 0,
      "maximum": 100,
      "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."
    },
    "strip_preset": {
      "type": "string",
      "enum": [
        "coffee_beans",
        "coffee_cup",
        "bakery",
        "pizza",
        "sushi",
        "burger",
        "ice_cream",
        "smoothie",
        "flowers",
        "spa"
      ],
      "description": "Preset strip photo, used when strip_type is preset."
    },
    "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."
    },
    "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."
    },
    "square_logo_url": {
      "type": "string",
      "description": "Public https URL of a square logo or icon, used as the round logo on Google Wallet."
    },
    "show_member_field": {
      "type": "boolean",
      "description": "Show the customer's name on the front of the pass. Default true."
    },
    "show_stamps_to_reward_field": {
      "type": "boolean",
      "description": "Show how many stamps until the next reward. Default true."
    },
    "auxiliary_fields": {
      "type": "array",
      "maxItems": 2,
      "description": "Up to two extra front-of-pass fields, e.g. {label: \"Perk\", value: \"10% off pastries\"}.",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "maxLength": 20
          },
          "value": {
            "type": "string",
            "maxLength": 30
          }
        },
        "required": [
          "value"
        ]
      }
    },
    "rewards": {
      "type": "array",
      "minItems": 1,
      "maxItems": 5,
      "description": "Rewards customers can redeem, e.g. [{name: \"Free coffee\", stamps_required: 10}]. The free plan allows one reward per card.",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 60
          },
          "stamps_required": {
            "type": "integer",
            "minimum": 1,
            "description": "Stamps spent to redeem. Usually equal to the card's stamps_required."
          },
          "description": {
            "type": "string",
            "maxLength": 200
          }
        },
        "required": [
          "name",
          "stamps_required"
        ]
      }
    }
  },
  "required": [
    "name",
    "rewards"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

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.

{
  "type": "object",
  "properties": {
    "card_id": {
      "type": "integer",
      "description": "Card id from list_cards."
    },
    "name": {
      "type": "string",
      "maxLength": 60,
      "description": "Internal name for the card, e.g. \"Coffee card\". Shown in Leal, not on the pass."
    },
    "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."
    },
    "card_color": {
      "type": "string",
      "description": "Pass background colour, hex (#RRGGBB)."
    },
    "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)."
    },
    "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."
    },
    "stamp_color": {
      "type": "string",
      "description": "Colour of the icon inside a collected stamp, hex. Must read clearly on stamp_background_color."
    },
    "stamp_icon": {
      "type": "string",
      "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"
      ],
      "description": "Icon shown in each collected stamp."
    },
    "stamps_required": {
      "type": "integer",
      "minimum": 1,
      "maximum": 21,
      "description": "Stamps needed to fill the card. 6, 8 or 10 are common."
    },
    "initial_stamps": {
      "type": "integer",
      "minimum": 0,
      "description": "Stamps a new customer starts with (a head start). Must be less than stamps_required."
    },
    "strip_type": {
      "type": "string",
      "enum": [
        "color",
        "preset",
        "image"
      ],
      "description": "Background of the stamp strip: a flat colour, one of Leal's preset photos, or an image from strip_image_url."
    },
    "strip_color": {
      "type": "string",
      "description": "Strip colour, hex. Also shows behind preset and image strips when strip_opacity is below 100."
    },
    "strip_opacity": {
      "type": "integer",
      "minimum": 0,
      "maximum": 100,
      "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."
    },
    "strip_preset": {
      "type": "string",
      "enum": [
        "coffee_beans",
        "coffee_cup",
        "bakery",
        "pizza",
        "sushi",
        "burger",
        "ice_cream",
        "smoothie",
        "flowers",
        "spa"
      ],
      "description": "Preset strip photo, used when strip_type is preset."
    },
    "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."
    },
    "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."
    },
    "square_logo_url": {
      "type": "string",
      "description": "Public https URL of a square logo or icon, used as the round logo on Google Wallet."
    },
    "show_member_field": {
      "type": "boolean",
      "description": "Show the customer's name on the front of the pass. Default true."
    },
    "show_stamps_to_reward_field": {
      "type": "boolean",
      "description": "Show how many stamps until the next reward. Default true."
    },
    "auxiliary_fields": {
      "type": "array",
      "maxItems": 2,
      "description": "Up to two extra front-of-pass fields, e.g. {label: \"Perk\", value: \"10% off pastries\"}.",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "maxLength": 20
          },
          "value": {
            "type": "string",
            "maxLength": 30
          }
        },
        "required": [
          "value"
        ]
      }
    }
  },
  "required": [
    "card_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

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

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

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

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

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

{
  "type": "object",
  "properties": {
    "store_id": {
      "type": "integer",
      "description": "Store id from list_stores. Optional when the login has one store."
    },
    "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."
    }
  },
  "required": [
    "name",
    "address"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

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.

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