Promotions

Promotions give customers a discount (or extra loyalty points) automatically when a sale meets your rules. The register checks your promotions as items are added, so staff don't have to remember them. You set them up in the app or through the API.

In the app

Go to Sales → Promotions. Create a promotion, choose the discount, which products and stores it applies to, who it's for, and when it runs.

The main settings

Setting	API field	What it does
Name	`name`	Shown to staff and on the sale line.
Discount type	`discount_type`	`Percentage`, `Fixed Item Amount` or `Fixed Total Amount`. If you run a loyalty program, `Fixed Loyalty Points` and `Multiply Loyalty Points` give points instead of money off.
Discount	`discount`	The amount, percentage or points, depending on the type.
Products	`product_ids`, `product_tags`, `product_types`, `product_vendors`, `option1`–`option3`	Which products it covers.
Product filter	`product_filter`	`require_any`, `require_all` or `exclude_all`: how the product rules are applied.
Markdowns	`product_marked_down`	Whether marked-down products count.
Stores	`store_ids`, `store_tags`, `store_filter`	Which stores it runs in. `store_filter` is `in` or `not_in`.
Market	`market_id`	Limit it to one market.
Customer	`customer_required`, `customer_loyalty_tier`	Require a customer on the sale, or limit it to a loyalty tier.
Dates	`from_date`, `to_date`	When it runs.
Requirements	`minimum_item_quantity_requirement`, `minimum_order_total_requirement` and friends	Quantity or spend the sale has to reach.
Usage limits	`limit_usage`, `limit_customer_usage`, `limit_customer_usage_months`	How many times it can be used, in total and per customer. `used_times` counts uses so far.
Suggest on POS	`show_on_pos`	Suggest the promotion to staff at the register.
Stackable	`stackable`	Whether it can combine with other promotions.
Discount reason	`discount_reason`	The reason recorded on discounted lines.

Promo codes are managed on the promotion in the app.

Through the API

Create a promotion: POST /promotion.json
Update a promotion: PUT /promotion.json, with its id
Get a promotion and List promotions
Delete a promotion

Here's 20% off everything tagged summer, in every store, for November:

{
  "name": "Summer 20% off",
  "discount_type": "Percentage",
  "discount": 20,
  "product_tags": ["summer"],
  "product_filter": "require_any",
  "store_filter": "in",
  "from_date": "2026-11-01T00:00:00+11:00",
  "to_date": "2026-11-30T23:59:59+11:00",
  "show_on_pos": true
}

📘
Update with the whole promotion
Fetch the promotion first, change what you need and send it all back with its id.

See which promotions were used

Each sale line records the promotions applied to it in item_promotions, so you can report on them with List sale lines or a report.

Prices vs promotions

A promotion is a rule the register applies. If you just want a different price for a product, maybe for a set period or a market, use a price instead (Sales → Prices, or Bulk create or update prices).

React to changes in Glue

promotion_create, promotion_update and promotion_delete fire when promotions change, so you can mirror them to your website or let the team know.

Example: Post new promotions to Teams

Trigger: System Hook, promotion_create.

API Request: Get Private Data for your Teams webhook, Response variable teams_res.

Script: Read the promotion

var promo = JSON.parse($.default);
$.promo = promo;
$.promo_dates = (promo.from_date || "now") + " to " + (promo.to_date || "no end date");
var pd = JSON.parse($.teams_res.body);
$.teams_url = pd[Object.keys(pd)[0]].trim();

Send Notification: Tell the stores, Channel Microsoft Teams, Webhook URL {{ teams_url }}, Title New promotion: {{ promo.name }}, Message {{ promo.discount_type }} {{ promo.discount }}, running {{ promo_dates }}.

See Slack and Teams notifications for setting up the webhook.