List discounts

GET 
/openapi/2026-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

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

Schema

codestring

error code

messagestring

error message

data object

discounts object[]

Discount list in current page

Array [

idstring

Discount ID

discount_namestring

Merchant-facing discount name

display_namestring

Storefront display name

discount_targetstring

Discount target category:

• product: Product discount
• order: Order discount
• shipping: Shipping discount

discount_typestring

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_methodstring

Discount method identifier:

• automatic: Applied automatically
• discount_code: Applied by discount code

discount_codestring

Primary discount code

progressstring

Current progress status:

• ongoing: Ongoing
• not_started: Not started
• finished: Finished
• paused: Paused

starts_atint32

Start timestamp

ends_atint32

End timestamp

created_atstring

Creation datetime string

updated_atstring

Last update datetime string

discount_layer object

Layered discount summary

condition_typestring

Condition type:

• no_condition: No condition required
• purchase_quantity: Requires purchase quantity
• purchase_amount: Requires purchase amount

obtain_typestring

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_valuestring

Condition threshold value for this layer

obtain_valuestring

Discount value granted when the condition is met

obtain_countuint32

Number of items granted as the discount benefit

]

discount_rule object

Rule summary of limits and behavior

limit_max_discountint32

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

limit_user_discountint32

Maximum usage count per customer; -1 means unlimited

limit_order_discountint32

Maximum usage count per order; -1 means unlimited

limit_user_product_typestring

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_discountint32

Max times a customer can purchase each eligible product under the discount

stockint32

Discount stock when stock-based limiting is enabled

follow_stockstring

Whether the promotion stock follows the product stock:

• product: use product stock
• discount: set a custom promotion stock

virtual_salesint32

Virtual sales value used for display or ranking

price_rulestring

Price base used for discount calculation:

• price: Use sale price
• compare_at_price: Use compare-at/original price

extendsstring

Reserved extension payload

product_discount_orderstring

Product ordering strategy used when applying discounts:

• desc: Apply by product price in descending order
• asc: Apply by product price in ascending order

discount_combinesstring[]

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_fullboolean

Whether all required items must be fully met

mn_discount_scopestring

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_discountint32

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

limit_code_user_discountint32

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

enable_product_extendsboolean

Whether per-product extension discount settings are enabled

entitled_product object

Product scope summary

product_idsstring[]

Product IDs included in the entitled scope

variant_idsstring[]

Variant IDs included in the entitled scope

collection_idsstring[]

Collection IDs included in the entitled scope

sort object

Sorting settings for entitled products

bystring

The field used to sort selected products

directionstring

The sort direction

beforestring

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

selectionstring

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_valuestring

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

min_purchase_qtyuint32

Minimum purchase quantity for this variant

sequint32

Custom display sequence number for sorting

virtual_salesint32

Virtual sales count configured for this variant

follow_stockstring

Whether the activity stock follows the product stock:

• product: Follow product stock
• discount: Use discount stock

stockint32

Activity-level stock limit for this variant

collection_idstring

Collection ID if this variant was selected via a collection

entitled_customer object

Customer scope summary

customer_idsstring[]

Explicit customer IDs that can use the discount

customer_segment_idsstring[]

Customer segment IDs that can use the discount

obtain_product object

Obtain-product scope summary

product_idsstring[]

Product IDs included in the entitled scope

variant_idsstring[]

Variant IDs included in the entitled scope

collection_idsstring[]

Collection IDs included in the entitled scope

sort object

Sorting settings for entitled products

bystring

The field used to sort selected products

directionstring

The sort direction

beforestring

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

selectionstring

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_valuestring

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

min_purchase_qtyuint32

Minimum purchase quantity for this variant

sequint32

Custom display sequence number for sorting

virtual_salesint32

Virtual sales count configured for this variant

follow_stockstring

Whether the activity stock follows the product stock:

• product: Follow product stock
• discount: Use discount stock

stockint32

Activity-level stock limit for this variant

collection_idstring

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_codestring

ISO country code

province_codesstring[]

Province or region codes under the country

]

source_namestring

Source name

starts_datestring

Start datetime string

ends_datestring

End datetime string

statestring

Marketing campaign state:

• valid: Valid
• deleted: Deleted
• canceled: Canceled early

]

cursorstring

Cursor for pagination

has_moreboolean

Whether there are more records

total_countint32

Total count of discounts

Example

{
  "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
  }
}