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

# Get Promotions

`GET /promotions`

To get detailed information of couple promotions sorted by time<br>利用時間範圍選取與排序獲取數筆優惠活動

## Query parameters

- `updated_after` string
- `updated_before` string
- `created_after` string
- `created_before` string
- `start_after` string
- `start_before` string
- `end_after` string
- `end_before` string
- `customer_id` string
- `scope` 'valid' | 'invalid'
- `promotion_ids` string[]
- `page` integer
- `per_page` integer

## Response `200`

OK

- object
  - `items` Promotion[]
    - `id` string — Promotion ID<br>優惠活動ID
    - `discount_percentage` number — Discount percentage<br>折扣百分比<br>-<br>*Applicable when discount_type is percentage<br>當discount_type為percentage時適用
    - `discount_amount` object — Discount amount<br>折扣固定金額<br>-<br>*Applicable when discount_type is gift<br>當discount_type為amount時適用
      - `cents` integer
      - `currency_symbol` string
      - `currency_iso` string
      - `label` string
      - `dollars` number
    - `discountable_quantity` integer — Quantity<br>獲得數量<br>-<br>*When discount_type is gift, this field refers to quantity of gift<br>當discount_type為gift時，此為贈品數量<br><br>*When discount_type is addon, this field refers to quality of add-on<br>當discount_type為addon時，此為可加購數量
    - `discounted_point` integer — Amount of point to redeem gift<br>點數兌換<br>-<br>*Applicable when discount_type is member_point_redeem_gift<br>當discount_type為member_point_redeem_gift時適用
    - `discounted_price` object — Discounted price<br>優惠價格<br>-<br>*Applicable when discount_type is bundle_pricing/ bundle_group/addon<br>當discount_type為bundle_pricing/ bundle_group/addon時適用
      - `cents` integer
      - `currency_symbol` string
      - `currency_iso` string
      - `label` string
      - `dollars` number
    - `discountable_product_ids` string[] — Ids of Discounted product<br>指定商品ids
    - `conditions` object[]
      - `id` string — Promotion Condition ID<br>優惠活動條件ID
      - `min_item_count` integer — 滿件數量
      - `min_price` Money
        - `cents` integer
        - `currency_symbol` string
        - `currency_iso` string
        - `label` string
        - `dollars` number
      - `type` 'red' | 'green' — A組(紅標)或B組(綠標)<br>-<br> Applicable when discount_type is bundle_group
      - `whitelisted_product_ids` string[] — 指定商品條件id
      - `whitelisted_category_ids` string[] — 指定分類條件id
      - `blacklisted_product_ids` string[] — 指定排除商品條件id
      - `subscription_period` integer — subscription period<br>定期購指定期數
    - `created_at` string — Created Time<br>建立時間
    - `updated_at` string — Updated Time<br>更新時間
    - `title_translations` object — Title translations <br> 標題翻譯
      - `en` string — Merchant defined English name<br>店家定義英文名稱
      - `zh-hant` string — Merchant defined Traditional Chinese name<br>店家定義繁體中文名稱
      - `zh-cn` string — Merchant defined Simplified Chinese name<br>店家定義簡體中文名稱
      - `vi` string — Merchant defined Vietnamese name<br>店家定義越南文名稱
      - `ms` string — Merchant defined Malaysian name<br>店家定義馬來西亞文名稱
      - `ja` string — Merchant defined Japanese name<br>店家定義日文名稱
      - `th` string — Merchant defined Thai name<br>店家定義泰文名稱
      - `id` string — Merchant defined Indian name<br>店家定義印度文名稱
      - `de` string — Merchant defined Deutsch name<br>店家定義德文名稱
      - `fr` string — Merchant defined France name<br>店家定義法文名稱
    - `discountable_category_ids` string[] — Ids of Discounted category<br>指定商品分類ids
    - `discount_on` 'order' | 'item' | 'category' — Promotion target<br>優惠套用對象<br>-<br>order = Entire shop 全店<br>item = Specific item 指定商品<br>category = Specific category 指定分類
    - `discount_type` 'percentage' | 'amount' | 'gift' | 'addon' | 'free_shipping' | 'bundle_pricing' | 'bundle_group' | 'member_point_redeem_gift' | 'subscription_gift' — Discount type<br>折扣類型<br>-<br>percentage: 折扣%<br>amount: 固定金額<br>gift: 贈品<br>addon: 加購品<br>free_shipping: 免運<br>bundle_pricing: 任選優惠<br>bundle_group: A+B組合優惠（紅配綠）<br>member_point_redeem_gift: 點數兌換贈品<br>subscription_gift
    - `is_accumulated` boolean — Is bundle pricing or bundle pricing accumulated?<br>任選優惠/A+B組合優惠是否累計
    - `first_purchase_only` boolean — For first purchase only<br>創建自動套用—每位會員限用優惠一次的任選優惠
    - `first_purchase_all_platform` boolean — For first purchase all platform<br>全通路首購
    - `codes` string[] — Coupon Code<br>促銷代碼
    - `show_coupon` boolean
    - `membership_tier_id` string
    - `requires_membership` boolean — Does it require membership?<br>設定目標群組<br>-<br>false: 所有顧客<br>true: 會員
    - `whitelisted_membership_tier_ids` string[] — Specific Membership Tiers<br>適用會員等級
    - `whitelisted_tag_contents` string[]
    - `user_max_use_count` integer — Limit per member<br>每會員最多使用次數<br>-<br>null = Unlimited 不限使用次數
    - `max_use_count` integer — How many times can this promotion be used?<br>活動限使用次數<br>-<br>null = Unlimited 不限使用次數
    - `use_count` integer — Usage of this layer of promotion<br>本階層活動已使用次數
    - `sum_use_count` integer — Total usage of promotion<br>活動已使用次數
    - `whitelisted_delivery_option_ids` string[] — Delivery options that applicable to the promotion<br>活動適用送貨方式
    - `whitelisted_payment_ids` string[] — Payment options that applicable to the promotion<br>活動適用付款方式
    - `start_at` string — Promotion start time<br>活動開始時間
    - `end_at` string — Promotion end time<br>活動結束時間<br>-<br>null = no end date 永不過期
    - `status` 'active' | 'draft' | 'hidden' — Promotion status<br>活動狀態<br>-<br>active: 上架<br>draft: 下架<br>hidden: 會員默認優惠/主商品加購品<br>removed: 刪除
    - `usable` boolean — Is promotion active<br>優惠是否進行中<br>-<br>true: published and not expired上架且沒有過期<br>false: unpublished or published and expired上架已過期 或是 下架
    - `for_affiliate_campaign` boolean — Is applicable to affiliate campaign<br>是否適用於推薦活動
    - `is_contain_campaign` boolean — Is binded to affiliate campaign<br>是否已綁定推薦活動
    - `seo_enabled` boolean — Generate promotion page and SEO sitemap or not
    - `seo_keywords` string — SEO keywords<br>SEO 關鍵字
    - `seo_description_translations` object — Description of SEO<br>SEO優化描述
      - `en` string — Merchant defined English name<br>店家定義英文名稱
      - `zh-hant` string — Merchant defined Traditional Chinese name<br>店家定義繁體中文名稱
      - `zh-cn` string — Merchant defined Simplified Chinese name<br>店家定義簡體中文名稱
      - `vi` string — Merchant defined Vietnamese name<br>店家定義越南文名稱
      - `ms` string — Merchant defined Malaysian name<br>店家定義馬來西亞文名稱
      - `ja` string — Merchant defined Japanese name<br>店家定義日文名稱
      - `th` string — Merchant defined Thai name<br>店家定義泰文名稱
      - `id` string — Merchant defined Indian name<br>店家定義印度文名稱
      - `de` string — Merchant defined Deutsch name<br>店家定義德文名稱
      - `fr` string — Merchant defined France name<br>店家定義法文名稱
    - `seo_title_translations` object — Title of SEO<br>SEO優化標題
      - `en` string — Merchant defined English name<br>店家定義英文名稱
      - `zh-hant` string — Merchant defined Traditional Chinese name<br>店家定義繁體中文名稱
      - `zh-cn` string — Merchant defined Simplified Chinese name<br>店家定義簡體中文名稱
      - `vi` string — Merchant defined Vietnamese name<br>店家定義越南文名稱
      - `ms` string — Merchant defined Malaysian name<br>店家定義馬來西亞文名稱
      - `ja` string — Merchant defined Japanese name<br>店家定義日文名稱
      - `th` string — Merchant defined Thai name<br>店家定義泰文名稱
      - `id` string — Merchant defined Indian name<br>店家定義印度文名稱
      - `de` string — Merchant defined Deutsch name<br>店家定義德文名稱
      - `fr` string — Merchant defined France name<br>店家定義法文名稱
    - `link` object — SEO Link<br>SEO 連結
      - `id` string
      - `status` string
      - `type` string
      - `name` string
      - `name_translations` Translatable
        - `en` string — Merchant defined English name<br>店家定義英文名稱
        - `zh-hant` string — Merchant defined Traditional Chinese name<br>店家定義繁體中文名稱
        - `zh-cn` string — Merchant defined Simplified Chinese name<br>店家定義簡體中文名稱
        - `vi` string — Merchant defined Vietnamese name<br>店家定義越南文名稱
        - `ms` string — Merchant defined Malaysian name<br>店家定義馬來西亞文名稱
        - `ja` string — Merchant defined Japanese name<br>店家定義日文名稱
        - `th` string — Merchant defined Thai name<br>店家定義泰文名稱
        - `id` string — Merchant defined Indian name<br>店家定義印度文名稱
        - `de` string — Merchant defined Deutsch name<br>店家定義德文名稱
        - `fr` string — Merchant defined France name<br>店家定義法文名稱
      - `value_id` string
      - `url_link` string
      - `key` string
      - `html_target` string
      - `section` string
      - `owner_id` string
      - `parent_id` string
      - `priority` number
      - `children_ids` string[]
      - `created_at` string — Created Time<br>建立時間
      - `updated_at` string — Updated Time<br>更新時間
      - `seo_image` object — SEO Image<br>SEO社群預覽圖
        - `id` string — Media ID
        - `url` string — Media URL
    - `available_platforms` string[] — 指定平台（目前僅接受 "ec", "retail", "app" 值）
    - `is_partial_free_shipping` boolean
    - `coupon_type` 'draw' | 'single' | 'multi'
    - `extended_promotion_id` string — Parent promotion id<br>母層活動id<br>-<br>*applicable when this is a child promotion
    - `extend_promotions` ExtendPromotion[] — 多階層優惠活動與條件
      - `id` string — Promotion ID<br>優惠活動ID
      - `discount_percentage` number — Discount percentage<br>折扣百分比<br>-<br>*Applicable when discount_type is percentage<br>當discount_type為percentage時適用
      - `discount_amount` object — Discount amount<br>折扣固定金額<br>-<br>*Applicable when discount_type is gift<br>當discount_type為amount時適用
        - `cents` integer
        - `currency_symbol` string
        - `currency_iso` string
        - `label` string
        - `dollars` number
      - `discountable_quantity` integer — Quantity<br>獲得數量<br>-<br>*When discount_type is gift, this field refers to quantity of gift<br>當discount_type為gift時，此為贈品數量<br><br>*When discount_type is addon, this field refers to quality of add-on<br>當discount_type為addon時，此為可加購數量
      - `discounted_point` integer — Amount of point to redeem gift<br>點數兌換<br>-<br>*Applicable when discount_type is member_point_redeem_gift<br>當discount_type為member_point_redeem_gift時適用
      - `discounted_price` object — Discounted price<br>優惠價格<br>-<br>*Applicable when discount_type is bundle_pricing/ bundle_group/addon<br>當discount_type為bundle_pricing/ bundle_group/addon時適用
        - `cents` integer
        - `currency_symbol` string
        - `currency_iso` string
        - `label` string
        - `dollars` number
      - `discountable_product_ids` string[] — Ids of Discounted product<br>指定商品ids
      - `conditions` object[]
        - `id` string — Promotion Condition ID<br>優惠活動條件ID
        - `min_item_count` integer — 滿件數量
        - `min_price` Money
          - `cents` integer
          - `currency_symbol` string
          - `currency_iso` string
          - `label` string
          - `dollars` number
        - `type` 'red' | 'green' — A組(紅標)或B組(綠標)<br>-<br> Applicable when discount_type is bundle_group
        - `whitelisted_product_ids` string[] — 指定商品條件id
        - `whitelisted_category_ids` string[] — 指定分類條件id
        - `blacklisted_product_ids` string[] — 指定排除商品條件id
        - `subscription_period` integer — subscription period<br>定期購指定期數
    - `drew_coupon_count` integer — How many times did this promotion been drew?<br>活動被領取次數
    - `whitelisted_membership_tiers` object[] — 指定會員資料
    - `summary` object — 優惠概況
    - `available_channel_ids` string[] — Ids of available channel<br>指定通路ids
    - `banner_medias` object — Promotion banner<br>活動橫圖
      - `id` string — Media ID
      - `alt_translations` object — Content to display on ALT attribute<br>在圖片ALT上展示的內容
        - `en` string — Merchant defined English name<br>店家定義英文名稱
        - `zh-hant` string — Merchant defined Traditional Chinese name<br>店家定義繁體中文名稱
        - `zh-cn` string — Merchant defined Simplified Chinese name<br>店家定義簡體中文名稱
        - `vi` string — Merchant defined Vietnamese name<br>店家定義越南文名稱
        - `ms` string — Merchant defined Malaysian name<br>店家定義馬來西亞文名稱
        - `ja` string — Merchant defined Japanese name<br>店家定義日文名稱
        - `th` string — Merchant defined Thai name<br>店家定義泰文名稱
        - `id` string — Merchant defined Indian name<br>店家定義印度文名稱
        - `de` string — Merchant defined Deutsch name<br>店家定義德文名稱
        - `fr` string — Merchant defined France name<br>店家定義法文名稱
      - `images` object — Object contains url of image in different dimensions<br>包含不同大小圖片的連絡
    - `term_translations` object — Promotion Term & Condition <br> 活動條款與細則
      - `en` string — Merchant defined English name<br>店家定義英文名稱
      - `zh-hant` string — Merchant defined Traditional Chinese name<br>店家定義繁體中文名稱
      - `zh-cn` string — Merchant defined Simplified Chinese name<br>店家定義簡體中文名稱
      - `vi` string — Merchant defined Vietnamese name<br>店家定義越南文名稱
      - `ms` string — Merchant defined Malaysian name<br>店家定義馬來西亞文名稱
      - `ja` string — Merchant defined Japanese name<br>店家定義日文名稱
      - `th` string — Merchant defined Thai name<br>店家定義泰文名稱
      - `id` string — Merchant defined Indian name<br>店家定義印度文名稱
      - `de` string — Merchant defined Deutsch name<br>店家定義德文名稱
      - `fr` string — Merchant defined France name<br>店家定義法文名稱
  - `pagination` Paginatable
    - `current_page` integer — The current page number<br>當前分頁
    - `per_page` integer — Number of result per page<br>每頁顯示 n 筆資料<br>(Default: 24)
    - `total_count` integer — Number of result in total<br>資料總量
    - `total_pages` integer — Number of pages in total<br>總頁數量

---

[API](https://skmtc.net/shoplineapp/apis/shopline-open-api.md) · [All operations](https://skmtc.net/shoplineapp/apis/shopline-open-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shoplineapp/shopline-open-api/revisions/1675ac12cde7/schema)