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

# List promotions

`GET /v1/promotions`

Retrieve promotions

## Query parameters

- `ids` string[]
- `activeAt` string
- `shopId` string, required
- `page` integer
- `perPage` integer

## Response `200`

request successful

- PromotionsResponse
  - `entities` Promotion[]
    - `id` string — The unique identifier of the promotion
    - `name` string — Promotion name
    - `schedule` object — Promotion's initial and end date, formatted according to RFC 3339.
      - `from` string — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00
      - `to` string — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00
    - `isActive` boolean — Promotion's status
    - `effect` union
      - AutomaticDiscountEffect — Promotion's effect
        - `type` 'buy_x_get_y' | 'automatic_discount'
        - `additionalData` object
          - `type` 'absolute' | 'relative' — The type is either `absolute` or `relative`.
          - `value` number, float — The value is either a relative percentage or an absolute reduction in cents, determined by the additionalData.type field. If the type is relative, the value should be expressed as a percentage; if the type is absolute, the value will be in cents.
      - BuyXGetYEffect — Promotion's effect
        - `type` 'buy_x_get_y' | 'automatic_discount'
        - `additionalData` object
          - `eligibleItemsQuantity` integer
          - `maxCount` integer
          - `maxCountType` 'per_eligible_items_quantity' | 'per_eligible_uniq_items'
          - `variantIds` integer[]
    - `conditions` Condition[] — Promotion's conditions
      - `level` string
      - `key` string
      - `condition` string
    - `customData` object — Promotion's custom data
    - `priority` number — The priority of the promotion compared to other promotions. This can be used to decide which promotion to apply if there is a conflict between two.
    - `tiers` Tier[]
      - `id` integer
      - `name` string
      - `MOV` integer
      - `effect` object
        - `additionalData` object
          - `type` string
          - `value` number, float
  - `pagination` Pagination
    - `current` integer, required
    - `first` integer, required
    - `last` integer, required
    - `next` integer, required
    - `page` integer, required
    - `perPage` integer, required
    - `prev` integer, required
    - `total` integer, required

## Other responses

- `401` — authentication failed

## Changes

- **2026-07-17** `8cfa924ae703` — 1 info
  - endpoint added
- **2023-08-06** `302b7c443b51` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/scayle/apis/storefront-api-documentation/changes/v1/promotions/get.md)

---

[API](https://skmtc.dev/scayle/apis/storefront-api-documentation.md) · [All operations](https://skmtc.dev/scayle/apis/storefront-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/scayle/storefront-api-documentation/revisions/8cfa924ae703/schema)