FleetbaseFleetbase

Promotions

Promotions are discounts a store or network offers at checkout: percentage or amount off, free delivery, or buy X get Y. They apply automatically or with a promo code. These endpoints list the storefront's live, public promotions ("deals") for the app. Codes are applied to carts with the Cart endpoints, and discounts are priced into the checkout amount.

The Promotion object

A live, public promotion of the store (or, with a network key, of the network or one of its member stores). Money values are integers in the currency's minor unit, like cart subtotals. Promo codes are never included.
Attributes
idstringoptional

Public identifier of the promotion.

namestringoptional

Promotion name, also shown on applied discounts.

descriptionstringoptional

Optional details for customers.

triggerenumoptional

automatic promotions apply to every eligible cart; code promotions need a promo code. One of automatic, code.

typeenumoptional

How the discount is calculated. One of percentage, fixed_amount, free_delivery, bogo.

valuenumberoptional

Percent off for percentage, amount off (minor units) for fixed_amount.

max_discount_amountintegeroptional

Maximum discount per order, in minor units.

currencystringoptional

Currency of fixed_amount promotions.

min_subtotalintegeroptional

Minimum spend on the targeted items, in minor units.

min_itemsintegeroptional

Minimum number of targeted items.

applies_toobjectoptional

Targeting: products, categories, stores, exclude_products and exclude_categories identifier lists. Empty means the whole cart (of the owning store, for store promotions).

bogo_configobjectoptional

For bogo: buy_quantity, get_quantity and discount_percent (100 means free). The cheapest units of each group are discounted.

first_order_onlybooleanoptional

Only customers who have never placed a storefront order can use it.

usage_limit_per_customerintegeroptional

How many times one customer can use it.

stackablebooleanoptional

Whether it combines with other stackable promotions.

starts_attimestampoptional

When the promotion starts.

ends_attimestampoptional

When the promotion ends.

schedulearray of objectsoptional

Optional weekly windows (days as ISO weekdays, start/end as HH:MM) in timezone when it applies.

timezonestringoptional

Timezone of the schedule windows.

image_urlstringoptional

Promotion image.

translationsobjectoptional

Translated content.

created_attimestampoptional

Time the promotion was created.

updated_attimestampoptional

Time the promotion was last updated.

The Promotion object
{
  "id": "promotion_7Hq2xL9",
  "name": "Weekday lunch 20% off",
  "description": "20% off mains, weekdays 11:00-14:00.",
  "trigger": "automatic",
  "type": "percentage",
  "value": 20,
  "max_discount_amount": 1000,
  "currency": "USD",
  "min_subtotal": 1500,
  "min_items": null,
  "applies_to": {
    "categories": [
      "category_uuid"
    ]
  },
  "bogo_config": null,
  "first_order_only": false,
  "usage_limit_per_customer": 1,
  "stackable": false,
  "starts_at": "2026-10-01T00:00:00Z",
  "ends_at": "2026-12-31T23:59:59Z",
  "schedule": [
    {
      "days": [
        1,
        2,
        3,
        4,
        5
      ],
      "start": "11:00",
      "end": "14:00"
    }
  ],
  "timezone": "America/New_York",
  "image_url": "https://files.example.com/lunch.png",
  "translations": null,
  "created_at": "2026-09-26T09:30:00Z",
  "updated_at": "2026-09-26T09:30:00Z"
}
GET/v1/promotions

Query Promotions

Lists the storefront's live, public promotions: active, inside their date range and weekly schedule. With a network key the network's promotions and those of its member stores are returned; pass store to only list one member store's.

Query parameters
storestringoptional

Network member store public ID, to only list that store's promotions. Ignored for store keys.

GET/v1/promotions
curl https://api.fleetbase.io/v1/promotions?store= \
  -H "Authorization: Bearer flb_live_…"
GET/v1/promotions

Retrieve a Promotion

Retrieves one live, public promotion of the storefront. Returns 404 for promotions that are not active, not public, outside their schedule, or owned by another storefront.

GET/v1/promotions
curl https://api.fleetbase.io/v1/promotions \
  -H "Authorization: Bearer flb_live_…"
Promotions | Fleetbase