**Version: 202701**

# List discounts

**GET** `/openapi/2027-01/discounts`

Returns the discount list by query parameters.

## Request

**Query Parameters**

- `cursor` string

  Cursor for pagination, use the cursor from the response to retrieve the next page
- `page_size` int32

  A limit on the number of objects to be returned. Ranges from 1 to 250. Default is 10
- `page` int32

  Page number (1-based). Mutually exclusive with cursor
- `discount_name` string

  Fuzzy match keyword for discount name
- `discount_type` string[]

  Discount types used as filter values.

  *   rebate\_cta\_otr: Amount-threshold fixed reduction.
  *   rebate\_ctq\_otr: Quantity-threshold fixed reduction.
  *   rebate\_cta\_otp: Amount-threshold percentage discount.
  *   rebate\_ctq\_otp: Quantity-threshold percentage discount.
  *   m\_n\_discount: M-for-N discount.
  *   flashsale: Flash sale discount.
  *   code\_percent: Discount-code percentage discount.
  *   code\_fix\_price\_reduction: Discount-code fixed reduction.
  *   code\_bxgy: Discount-code buy X get Y.
  *   code\_free\_shipping: Discount-code free shipping. Example: ?discount\_type=rebate\_cta\_otr&discount\_type=rebate\_ctq\_otr
- `progress` string[]

  Discount progress states used as filter values.

  *   ongoing: Ongoing.
  *   not\_started: Not started.
  *   finished: Finished.
  *   paused: Paused. Example: ?progress=ongoing&progress=finished
- `starts_date` string

  Lower bound datetime for time-overlap filtering, format as "2006-01-02 15:04:05"
- `ends_date` string

  Upper bound datetime for time-overlap filtering, format as "2006-01-02 15:04:05"
- `discount_code` string

  Discount code
- `discount_methods` string[]

  Discount methods used as filter values.

  *   automatic: Applied automatically.
  *   discount\_code: Applied by discount code. Example: ?discount\_methods=automatic&discount\_methods=discount\_code
- `ids` string[]

  Explicit discount IDs used as filter values. Example: ?ids=1001&ids=1002
- `discount_targets` string[]

  Discount target categories used as filter values.

  *   product: Product discount.
  *   order: Order discount.
  *   shipping: Shipping discount. Example: ?discount\_targets=product&discount\_targets=order
- `source_ids` string[]

  Business source IDs used as filter values.

  *   1: Manual creation.
  *   2: Goaffpro Affiliate Marketing.
  *   3: Fintouch.
  *   4: MambaSMS SMS & Marketing.
  *   5: Stamped Loyalty & Referrals.
  *   6: Product recommendation.
  *   999: Other. Example: ?source\_ids=3001&source\_ids=3002
- `discount_combines` string[]

  Other discount categories that can be combined.

  *   product: Can combine with product discounts.
  *   order: Can combine with order discounts.
  *   shipping: Can combine with shipping discounts. Example: ?discount\_combines=product&discount\_combines=shipping

## Responses

**200**

OK

**application/json**

**Schema | Example**

**Schema**

- `code` string

  error code
- `message` string

  error message
- `data` object

  - `discounts` object[]

    Discount list in current page

    *   Array \[

    - `id` string

      Discount ID
    - `discount_name` string

      Merchant-facing discount name
    - `display_name` string

      Storefront display name
    - `discount_target` string

      Discount target category:

      *   `product`: Product discount
      *   `order`: Order discount
      *   `shipping`: Shipping discount
    - `discount_type` string

      Discount type identifier:

      *   `rebate_cta_otr`: Amount-threshold fixed reduction
      *   `rebate_ctq_otr`: Quantity-threshold fixed reduction
      *   `rebate_cta_otp`: Amount-threshold percentage discount
      *   `rebate_ctq_otp`: Quantity-threshold percentage discount
      *   `m_n_discount`: M-for-N discount
      *   `flashsale`: Flash sale discount
      *   `code_percent`: Discount-code percentage discount
      *   `code_fix_price_reduction`: Discount-code fixed reduction
      *   `code_bxgy`: Discount-code buy X get Y
      *   `code_free_shipping`: Discount-code free shipping
    - `discount_method` string

      Discount method identifier:

      *   `automatic`: Applied automatically
      *   `discount_code`: Applied by discount code
    - `discount_code` string

      Primary discount code
    - `progress` string

      Current progress status:

      *   `ongoing`: Ongoing
      *   `not_started`: Not started
      *   `finished`: Finished
      *   `paused`: Paused
    - `starts_at` int32

      Start timestamp
    - `ends_at` int32

      End timestamp
    - `created_at` string

      Creation datetime string
    - `updated_at` string

      Last update datetime string
    - `discount_layer` object

      Layered discount summary

      - `condition_type` string

        Condition type:

        *   `no_condition`: No condition required
        *   `purchase_quantity`: Requires purchase quantity
        *   `purchase_amount`: Requires purchase amount
      - `obtain_type` string

        Benefit type:

        *   `no_discount`: No discount
        *   `free_acquisition`: Free acquisition
        *   `percent`: Percentage discount
        *   `fixed_price_reduction`: Fixed amount reduction
        *   `fixed_price`: Fixed final price
        *   `fixed_quantity`: Fixed quantity granted
        *   `product_price_reduction`: Product-level price reduction
      - `layers` object[]

        Layered discount rules from lower to higher thresholds

        *   Array \[

        - `condition_value` string

          Condition threshold value for this layer
        - `obtain_value` string

          Discount value granted when the condition is met
        - `obtain_count` uint32

          Number of items granted as the discount benefit
        *   \]
    - `discount_rule` object

      Rule summary of limits and behavior

      - `limit_max_discount` int32

        Maximum total usage count of the discount; -1 means unlimited
      - `limit_user_discount` int32

        Maximum usage count per customer; -1 means unlimited
      - `limit_order_discount` int32

        Maximum usage count per order; -1 means unlimited
      - `limit_user_product_type` string

        Per-customer product limit strategy type:

        *   `no_limit`: No per-product purchase limit
        *   `customer_all_product`: Per customer per discount, accumulated across all eligible variants
        *   `customer_product`: Per customer per discount per product
        *   `customer_variant`: Per customer per discount per variant
      - `limit_user_product_discount` int32

        Max times a customer can purchase each eligible product under the discount
      - `stock` int32

        Discount stock when stock-based limiting is enabled
      - `follow_stock` string

        Whether the promotion stock follows the product stock:

        *   `product`: use product stock
        *   `discount`: set a custom promotion stock
      - `virtual_sales` int32

        Virtual sales value used for display or ranking
      - `price_rule` string

        Price base used for discount calculation:

        *   `price`: Use sale price
        *   `compare_at_price`: Use compare-at/original price
      - `extends` string

        Reserved extension payload
      - `product_discount_order` string

        Product ordering strategy used when applying discounts:

        *   `desc`: Apply by product price in descending order
        *   `asc`: Apply by product price in ascending order
      - `discount_combines` string[]

        Other discount categories that can be combined:

        *   `product`: Can combine with product discounts
        *   `order`: Can combine with order discounts
        *   `shipping`: Can combine with shipping discounts
      - `obtain_full` boolean

        Whether all required items must be fully met
      - `mn_discount_scope` string

        Scope strategy for multi-layer discount evaluation:

        *   `highest`: Apply the highest matched layer only
        *   `all`: Apply all matched layers
        *   `highest_all`: Apply all matched layers; quantities above the highest layer use the highest-layer benefit
      - `limit_code_max_discount` int32

        Maximum usage count per discount code; -1 means unlimited. Only applicable to non-automatic discounts
      - `limit_code_user_discount` int32

        Maximum usage count per customer per discount code. Only applicable to non-automatic discounts
      - `enable_product_extends` boolean

        Whether per-product extension discount settings are enabled
    - `entitled_product` object

      Product scope summary

      - `product_ids` string[]

        Product IDs included in the entitled scope
      - `variant_ids` string[]

        Variant IDs included in the entitled scope
      - `collection_ids` string[]

        Collection IDs included in the entitled scope
      - `sort` object

        Sorting settings for entitled products

        - `by` string

          The field used to sort selected products
        - `direction` string

          The sort direction
        - `before` string

          If non-empty, sort by time range for legacy flash sale compatibility. Unit: seconds
      - `selection` string

        Selection strategy identifier:

        *   `entitled`: Only entitled products are included
        *   `exclude`: Entitled products are excluded
        *   `all`: All products are included
      - `sku_extends` object

        Per-variant extended settings keyed by variant ID

        - `property name*` SkuExtendResp

          - `obtain_value` string

            Discount value for this variant. Currently only supports fixed price reduction; stored as a string
          - `min_purchase_qty` uint32

            Minimum purchase quantity for this variant
          - `seq` uint32

            Custom display sequence number for sorting
          - `virtual_sales` int32

            Virtual sales count configured for this variant
          - `follow_stock` string

            Whether the activity stock follows the product stock:

            *   `product`: Follow product stock
            *   `discount`: Use discount stock
          - `stock` int32

            Activity-level stock limit for this variant
          - `collection_id` string

            Collection ID if this variant was selected via a collection
    - `entitled_customer` object

      Customer scope summary

      - `customer_ids` string[]

        Explicit customer IDs that can use the discount
      - `customer_segment_ids` string[]

        Customer segment IDs that can use the discount
    - `obtain_product` object

      Obtain-product scope summary

      - `product_ids` string[]

        Product IDs included in the entitled scope
      - `variant_ids` string[]

        Variant IDs included in the entitled scope
      - `collection_ids` string[]

        Collection IDs included in the entitled scope
      - `sort` object

        Sorting settings for entitled products

        - `by` string

          The field used to sort selected products
        - `direction` string

          The sort direction
        - `before` string

          If non-empty, sort by time range for legacy flash sale compatibility. Unit: seconds
      - `selection` string

        Selection strategy identifier:

        *   `entitled`: Only entitled products are included
        *   `exclude`: Entitled products are excluded
        *   `all`: All products are included
      - `sku_extends` object

        Per-variant extended settings keyed by variant ID

        - `property name*` SkuExtendResp

          - `obtain_value` string

            Discount value for this variant. Currently only supports fixed price reduction; stored as a string
          - `min_purchase_qty` uint32

            Minimum purchase quantity for this variant
          - `seq` uint32

            Custom display sequence number for sorting
          - `virtual_sales` int32

            Virtual sales count configured for this variant
          - `follow_stock` string

            Whether the activity stock follows the product stock:

            *   `product`: Follow product stock
            *   `discount`: Use discount stock
          - `stock` int32

            Activity-level stock limit for this variant
          - `collection_id` string

            Collection ID if this variant was selected via a collection
    - `entitled_area` object

      Geographic areas where the discount can be applied. Only present for non-automatic discounts

      - `areas` object[]

        Geographic areas where the discount can be applied

        *   Array \[

        - `country_code` string

          ISO country code
        - `province_codes` string[]

          Province or region codes under the country
        *   \]
    - `source_name` string

      Source name
    - `starts_date` string

      Start datetime string
    - `ends_date` string

      End datetime string
    - `state` string

      Marketing campaign state:

      *   `valid`: Valid
      *   `deleted`: Deleted
      *   `canceled`: Canceled early
    *   \]
  - `cursor` string

    Cursor for pagination
  - `has_more` boolean

    Whether there are more records
  - `total_count` int32

    Total count of discounts

```json
{
  "code": "string",
  "message": "string",
  "data": {
    "discounts": [
      {
        "id": "string",
        "discount_name": "string",
        "display_name": "string",
        "discount_target": "string",
        "discount_type": "string",
        "discount_method": "string",
        "discount_code": "string",
        "progress": "string",
        "starts_at": 0,
        "ends_at": 0,
        "created_at": "string",
        "updated_at": "string",
        "discount_layer": {
          "condition_type": "string",
          "obtain_type": "string",
          "layers": [
            {
              "condition_value": "string",
              "obtain_value": "string",
              "obtain_count": 0
            }
          ]
        },
        "discount_rule": {
          "limit_max_discount": 0,
          "limit_user_discount": 0,
          "limit_order_discount": 0,
          "limit_user_product_type": "string",
          "limit_user_product_discount": 0,
          "stock": 0,
          "follow_stock": "string",
          "virtual_sales": 0,
          "price_rule": "string",
          "extends": "string",
          "product_discount_order": "string",
          "discount_combines": [
            "string"
          ],
          "obtain_full": true,
          "mn_discount_scope": "string",
          "limit_code_max_discount": 0,
          "limit_code_user_discount": 0,
          "enable_product_extends": true
        },
        "entitled_product": {
          "product_ids": [
            "string"
          ],
          "variant_ids": [
            "string"
          ],
          "collection_ids": [
            "string"
          ],
          "sort": {
            "by": "string",
            "direction": "string",
            "before": "string"
          },
          "selection": "string",
          "sku_extends": {}
        },
        "entitled_customer": {
          "customer_ids": [
            "string"
          ],
          "customer_segment_ids": [
            "string"
          ]
        },
        "obtain_product": {
          "product_ids": [
            "string"
          ],
          "variant_ids": [
            "string"
          ],
          "collection_ids": [
            "string"
          ],
          "sort": {
            "by": "string",
            "direction": "string",
            "before": "string"
          },
          "selection": "string",
          "sku_extends": {}
        },
        "entitled_area": {
          "areas": [
            {
              "country_code": "string",
              "province_codes": [
                "string"
              ]
            }
          ]
        },
        "source_name": "string",
        "starts_date": "string",
        "ends_date": "string",
        "state": "string"
      }
    ],
    "cursor": "string",
    "has_more": true,
    "total_count": 0
  }
}
```