---
title: "Get Store Promotion"
method: GET
path: "/v1/store_promotions/{store_promotion_id}"
tags: ["Store Promotions"]
---

# Get Store Promotion

`GET /v1/store_promotions/{store_promotion_id}`

## Request

- Base URL: `https://api.aghanim.com/s2s`
- URL: `https://api.aghanim.com/s2s/v1/store_promotions/{store_promotion_id}`
- Auth: HTTP bearer

## Path parameters

- `store_promotion_id` string, required

## Response `200`

Successful Response

- StorePromotionRead
  - `name` string: The name of the promotion
  - `start_at` integer, nullable: The start date of the promotion in seconds when the promotion starts to be applied
  - `end_at` integer, nullable: The end date of the promotion in seconds when the promotion ends to be applied
  - `discount_percent` integer: The discount percent of the promotion
  - `bonus_percent` integer: The bonus percent of the promotion for a stackable items
  - `max_purchase_count` integer: The maximum purchase count of the promotion. If the user exceeds this count, the promotion will not be applied.
  - `max_purchase_count_per_user` integer: The maximum purchase count per user. If the user exceeds this count, the promotion will not be applied. This setting is mutually exclusive with 'max_purchase_count'
  - `reward_points_percent` number: The rewards points percent of the promotion
  - `reward_points_fixed` integer: The fixed rewards points amount
  - `loyalty_points_percent` integer: The loyalty points percent of the promotion
  - `loyalty_points_fixed` integer: The fixed loyalty points amount
  - `reward_settings` ItemRewardSettings
    - `available` VCRewardConfig[], required
      - `type` 'virtual_currency'
      - `name` string
      - `virtual_currency_id` string, required
      - `virtual_currency_sku` string
      - `reward_percent` number
      - `reward_fixed` integer
  - `store_ids` string[]: Store ids that the promotion is applied to
  - `item_ids` string[]: Item ids that the promotion is applied to
  - `category_ids` string[]: Category ids that the promotion is applied to
  - `exclude_items_for_reward_points` boolean: Turn off discount benefit for items that can be purchased with reward points
  - `bonus_item_percent` integer: The user will receive a quantity equivalent to the set percentage of the total USD (in cents) purchase.
  - `bonus_item_id` string: The item ID that the user will receive a quantity equivalent to the set percentage of the total USD (in cents) purchase.
  - `bonus_item_quantity` integer: The fixed quantity of the bonus item
  - `bonus_items_settings` ItemBonusSettings
    - `items` ItemBonus[], required
      - `id` string, required: The ID of the bonus item that will be given to the user when they purchase this item.
      - `sku` string
      - `quantity_fixed` integer, nullable: The fixed quantity of the bonus item
      - `quantity_percent` integer, nullable: The user will receive a quantity equivalent to the set percentage of the price_after_discount_usd (in cents) of the purchased item.
    - `start_at` integer
    - `end_at` integer
    - `mode` 'replace' | 'add': How bonus items combine with the bonus items the store item already has. - `replace`: the bonus items replace the store item's bonus items - `add`: the bonus items are given in addition to the store item's bonus items
  - `item_background_image_url` string, uri, nullable: Background image URL to override item background during the promotion
  - `item_featured_card_background_image_url` string, uri, nullable: Featured card background image URL to override item featured card background during the promotion
  - `active` boolean: Allows to enable or disable the promotion
  - `archived_at` integer: The date when the promotion is archived in seconds
  - `requirements_expression` Expression
    - `tokens` Token[]
      - `type` 'attribute' | 'custom_attribute' | 'event_attribute' | 'custom_event_attribute' | 'operator' | 'number' | 'date' | 'string' | 'boolean' | 'list' | 'variable' | 'function' | 'virtual_currency', required
      - `value` unknown
    - `name` string
    - `variables` Expression[]
  - `payment_limits` PromotionPaymentLimits
    - `requires_payment_methods` string[]
    - `requires_payment_method_save` boolean
  - `bonus_badge` string: Custom text for store items bonus badge during the promotion
  - `custom_badge` string: Custom text to override store items custom badge during the promotion
  - `apply_to_free_items` boolean: Whether the promotion should be applied to free items
  - `offers` StorePromotionOffers
    - `offers` StorePromotionOffer[], required
      - `type` 'sequential' | 'rolling' | 'range' | 'pick_one' | 'piggy_bank', required
      - `id` string, required
  - `id` string, required
  - `created_at` integer, required
  - `current_purchase_count` integer, required
  - `user_id` string
  - `campaign_id` string
  - `user_campaign_id` string

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-05** `0ef278347679`: 2 info
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status
- **2026-09-29** `9f8df83795d3`: 1 info
  - added the optional property `bonus_items_settings/mode` to the response with the `200` status
- **2026-09-23** `1816e2044c07`: 1 warning, 1 info
  - added the new `function` enum value to the `requirements_expression/tokens/items/type` response property for the response status `200`
  - added the optional property `requirements_expression/name` to the response with the `200` status
- **2026-09-18** `fb9750c99d0a`: 1 warning
  - for the `path` request parameter `store_promotion_id`, the maxLength was set to `32`

[Operation history](https://skmtc.dev/aghanim/apis/aghanim-server-to-server-api/changes/v1/store_promotions/:store_promotion_id/get.md)

---

[API](https://skmtc.dev/aghanim/apis/aghanim-server-to-server-api.md) - [All operations](https://skmtc.dev/aghanim/apis/aghanim-server-to-server-api/llms.txt) - [OpenAPI document](https://skmtc.dev/aghanim/apis/aghanim-server-to-server-api/revisions/b084a5d2cd02?raw)