GET promotions

Endpoint

GET /public-api/v1/promotions

Purpose

Returns all non-deleted promotion definitions for the organization. Both ACTIVE and INACTIVE promotions are returned unless the active filter is provided.

Each promotion includes its complete rule configuration and safe assignment summaries for stores, categories, products, and targeted customers. Customer summaries contain only id, firstName, and lastName.

Parameters

• limit: optional page size, default 25, maximum 100.
• cursor: optional UUID from pagination.nextCursor.
• storeIds: optional branch applicability filter, comma-separated or repeated.
• categoryIds: optional filter for directly assigned categories.
• productIds: optional filter for directly assigned products.
• active: optional boolean; true selects ACTIVE, and false selects INACTIVE.
• triggers: optional comma-separated or repeated promotion trigger filter.
• from: optional ISO timestamp. Excludes promotions that ended before this time.
• to: optional ISO timestamp. Excludes promotions that start after this time.
• search: optional case-insensitive promotion-name search.

from and to use schedule-overlap semantics. Promotions without a schedule remain eligible. When storeIds is supplied, promotions assigned to one of those stores and global promotions with an empty stores array are returned.

Response fields

Each promotion includes id, timestamps, name, status, trigger, triggerThreshold, discountType, discountValue, freeQuantity, unlockedPrice, from, to, stores, categories, products, and customers.

An empty stores array means the promotion applies to every organization store. An empty customers array means the promotion is not restricted to named customers.

Example request

curl "https://api.klupos.com/public-api/v1/promotions?limit=25&active=true&storeIds=00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer klu_live_replace_me"

Example response

{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000010",
      "createdAt": "2026-06-01T00:00:00.000Z",
      "updatedAt": "2026-06-24T00:00:00.000Z",
      "name": "Example summer discount",
      "status": "ACTIVE",
      "trigger": "DISCOUNT",
      "triggerThreshold": null,
      "discountType": "PERCENTAGE",
      "discountValue": 10,
      "freeQuantity": null,
      "unlockedPrice": null,
      "from": "2026-06-01T00:00:00.000Z",
      "to": "2026-08-31T23:59:59.999Z",
      "stores": [
        {
          "id": "00000000-0000-4000-8000-000000000001",
          "name": "Example Branch",
          "branchNo": "001"
        }
      ],
      "categories": [
        {
          "id": "00000000-0000-4000-8000-000000000020",
          "name": "Example Category",
          "color": "GREEN",
          "unit": "PIECE",
          "group": null
        }
      ],
      "products": [],
      "customers": [
        {
          "id": "00000000-0000-4000-8000-000000000030",
          "firstName": "Example",
          "lastName": "Customer"
        }
      ]
    }
  ],
  "pagination": {
    "nextCursor": "00000000-0000-4000-8000-000000000010"
  }
}

Common errors

• 400: invalid filter, cursor, or date range.
• 401: invalid key.
• 403: requested storeIds are outside the organization.
• 429: rate limit exceeded.