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. `code` is a code customers can share (never a single-use or customer-specific one); `availability` and `next_starts_at` say whether it applies right now.
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.

codestringoptional

For code promotions, an active promo code customers can share and enter in the cart. Null for automatic promotions and when only single-use or customer-specific codes exist.

availabilityenumoptional

live applies now; scheduled is active but outside its dates or weekly schedule; ended is past ends_at or ended. Paused promotions are not returned by the public API, so inactive doesn't appear here. One of live, scheduled, ended, inactive.

next_starts_attimestampoptional

For scheduled promotions, when it next starts applying (looking up to a week ahead). Null otherwise.

ownerobjectoptional

Who runs it: type (store or network), id, name and logo_url.

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 lists of public IDs. 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",
  "code": null,
  "availability": "scheduled",
  "next_starts_at": "2026-10-08T15:00:00Z",
  "owner": {
    "type": "store",
    "id": "store_3Xb9kL2",
    "name": "Corner Bistro",
    "logo_url": "https://files.example.com/bistro.png"
  },
  "type": "percentage",
  "value": 20,
  "max_discount_amount": 1000,
  "currency": "USD",
  "min_subtotal": 1500,
  "min_items": null,
  "applies_to": {
    "categories": [
      "category_8Lq2nT4"
    ]
  },
  "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. Pass include=scheduled to also list active promotions that start later or are outside their weekly hours. 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.

includestringoptional

scheduled to also list active promotions that are outside their dates or weekly schedule right now (availability: scheduled), e.g. for an "upcoming offers" list.

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

Retrieve a Promotion

Retrieves one public promotion of the storefront, including ones that are scheduled or have ended, so a shared link still explains the offer; check availability. Returns 404 for promotions that are paused, not public, or owned by another storefront.

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