---
title: "List promotions"
method: GET
path: "/promotions"
tags: ["Promotions"]
---

# List promotions

`GET /promotions`

This endpoint lists all promotions for a retailer.

There are optional query parameters that allow filtering promotions. They can't be combined:

 - `end_time_from` - only show promotions that have end\_time after or equal to this time
 - `end_time_to` - only show promotions that have end\_time before this time

For example. the time format for end\_time\_from and end\_time\_to are: `2047-06-21T13:00:00`

🔒 Requires: `promotions:read` scope

## Query parameters

- `end_time_to` string
- `end_time_from` string
- `page_size` integer

## Response `200`

- PromotionCollection
  - `data` PromotionResponse[]
    - `action` Action — Action triggered by a promotion.
      - `exclude` Filter[]
        - `field` 'brand_id' | 'product_id' | 'supplier_id' | 'tag_id' | 'type_id' | 'variant_parent_id', required — name of the filter field
        - `value` string, required — value of the filter field
      - `include` Filter[]
        - `field` 'brand_id' | 'product_id' | 'supplier_id' | 'tag_id' | 'type_id' | 'variant_parent_id', required — name of the filter field
        - `value` string, required — value of the filter field
      - `max_quantity` integer — Maximum quantity, if required by the action type.
      - `min_quantity` integer — Minimum quantity, if required by the action type.
      - `quantity` integer — Quantity, if required by the action type.
      - `type` 'basic_percent_discount' | 'basic_fixed_discount' | 'fixed_discount' | 'percent_discount' | 'loyalty' | 'fixed_price_discount' | 'fixed_pool_discount' | 'percent_pool_discount', required — The type of action.
      - `value` number, double, required — Value associated with the action.
    - `add_promo_code` PromoCode[] — A list of promo codes to associate with this promotion.
      - `code` string, required — Code for use in the promotion.
      - `created_at` string — Time the code was created.
      - `created_user` User
        - `account_type` 'cashier' | 'manager' | 'admin', required — User's account type.
        - `created_at` string, required — Creation timestamp in UTC.
        - `deleted_at` string, nullable — Deletion timestamp in UTC.
        - `display_name` string, nullable — Full user's name to be used for display in the UI.
        - `email` string, email, nullable — User's email address.
        - `email_verified_at` string, nullable — The timestamp of users email verification.
        - `enabled` boolean — Indicates whether the user is enabled.
        - `enabled_mfa` object, nullable — The user's enabled MFA factor, or null if MFA is not enabled.
          - `created_at` string — Timestamp when the MFA factor was created.
          - `id` string — Auto-generated MFA factor ID.
          - `type` 'otp' — The MFA factor type (e.g. "otp").
        - `id` string, uuid, required — Auto-generated object ID.
        - `image_source` string — URL of the default-sized user's avatar.
        - `images` UserImages, nullable — On object containing URLs for different sizes of the user’s avatar.
          - `original` string
          - `sl` string
          - `sm` string
          - `ss` string
          - `st` string
          - `standard` string
          - `thumb` string
        - `is_primary_user` boolean, required — Indicated whether this user is the primary user for the account.
        - `permissions` string[], nullable — The permissions assigned to the user.
        - `require_password_change` boolean — Indicates whether the user is required to change their password.
        - `restricted_outlet_id` string, nullable — **deprecated** Use the `restricted_outlet_ids` instead.
        - `restricted_outlet_ids` string[] — A list of outlet IDs the user is associated with
        - `roles` Role[] — The roles assigned to the user.
          - `id` string — Auto-generated object ID.
          - `name` string — The Role name.
          - `system_role_id` string — A system role id of the Role. Will be either '100', '200', or '300'.
        - `rules` object — The rules assigned to the user.
        - `seen_at` string — The timestamp of the user's last activity in the system.
        - `switch_id` string — The switch id for the user.
        - `target_daily` number, nullable — Daily sales target for the user.
        - `target_monthly` number, nullable — Monthly sales target for the user.
        - `target_weekly` number, nullable — Weekly sales target for the user.
        - `time_until_deletion` string, nullable — The time until the user is deleted.
        - `updated_at` string, required — Last update timestamp in UTC.
        - `username` string, required — User's username used for login.
        - `version` integer, required — Auto-incrementing object version number.
      - `created_user_id` string — Created User ID.
      - `group_name` string — Name of the group.
      - `id` string — Auto-generated object ID.
      - `limit` integer — Redemption limit for this promotion.
      - `promotion_id` string — Promotion ID.
      - `redeemed` integer — Number of times this code has been redeemed.
    - `channels` string[] — A list of channels for the promotion. Can be `Register`, `Ecommerce`.
    - `combinable_with_coupon` boolean, nullable — Whether this promotion can be combined with an online coupon.
    - `condition` Condition — A condition to determine whether a promotion should apply to a sale.
      - `exclude` Filter[]
        - `field` 'brand_id' | 'product_id' | 'supplier_id' | 'tag_id' | 'type_id' | 'variant_parent_id', required — name of the filter field
        - `value` string, required — value of the filter field
      - `include` Filter[]
        - `field` 'brand_id' | 'product_id' | 'supplier_id' | 'tag_id' | 'type_id' | 'variant_parent_id', required — name of the filter field
        - `value` string, required — value of the filter field
      - `max_quantity` integer — Minimum quantity, if required by the condition type.
      - `min_price` number, double — Minimum price, if required by the condition type.
      - `min_quantity` integer — Minimum quantity, if required by the condition type.
      - `quantity` integer, required — Quantity, if required by the condition type.
      - `type` 'product_set' | 'sale_price', required — Condition type.
    - `customer_group_ids` string[] — A list of customer group IDs for the promotion.
    - `description` string — A short description for the promotion.
    - `end_time` string, nullable — The time the promotion ends, in UTC, e.g. `2006-01-02T15:04:05` (no timezone suffix).
    - `id` string — Auto-generated object ID.
    - `loyalty_multiplier` number, double, nullable — The loyalty multiplier for the promotion.
    - `name` string — The name of the promotion.
    - `online_channel_ids` integer[] — A list of online channel IDs for the promotion.
    - `outlet_ids` string[], nullable — A list of outlet IDs for the promotion.
    - `promo_code_summary` PromotionPromoCodeSummary, nullable
      - `redeemed_amount` integer — The redeemed amount
      - `total_promo_code` integer — The total for the promo code
    - `recurring_promotion` RecurringPromotion, nullable
      - `end_time` string — The time the recurring promotion ends.
      - `id` string — Recurring Promotion ID.
      - `occurrence_type` string — The occurrence type of the recurring promotion.
      - `recurring_promotion_occurrences` RecurringPromotionOccurrence[] — A list of the promotion occurrences.
        - `day_of_week` string — The day of week of the recurring promotion.
        - `id` string — Recurring Promotion occurrence ID.
      - `start_time` string — The time the recurring promotion begins.
    - `show_potential` boolean — Whether this promotion is shown as part of potential promotions.
    - `start_time` string — The time the promotion begins, in UTC, e.g. `2006-01-02T15:04:05` (no timezone suffix).
    - `status` string — The status of the promotion.
    - `use_promo_code` boolean — Whether or not this promotion uses promo codes.

---

[API](https://skmtc.net/lightspeedhq/apis/api-2026-07.md) · [All operations](https://skmtc.net/lightspeedhq/apis/api-2026-07/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lightspeedhq/api-2026-07/revisions/72d4ceb46dbb/schema)