Get discount by code

GET 
/openapi/2026-01/discounts/by-code/:discount_code

Gets a discount by discount code.

Request

Path Parameters

discount_code stringrequired

Discount code used for lookup, read from URL path

Responses

200

OK

application/json

Schema

Schema

codestring

error code

messagestring

error message

data object
discount object
Discount detail payload returned by code lookup
discount_info object
Core discount information
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
categorystring
Discount category, top-level discount type:
• buy_one_get_one: Buy one get one
• buy_x_get_y: Buy X get Y
• bundle: Bundle discount
• rebate: Rebate discount
• m_n_discount: M-for-N discount
• flash_sale: Flash sale
• code: Discount code
• coupon_old: Legacy coupon
• plugin_old: Legacy plugin
• rebate_old: Legacy rebate
• cycle_subscribe_old: Legacy cycle subscription
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 application method identifier:
• automatic: Applied automatically
• discount_code: Applied by discount code
discount_codestring
Primary discount code
discount_codesstring[]
All discount codes under this discount
starts_datestring
Start datetime string in center/store format
ends_datestring
End datetime string in center/store format
starts_atint32
Start timestamp
ends_atint32
End timestamp
created_atstring
Creation datetime string
updated_atstring
Last update datetime string
is_old_discountboolean
Whether this discount is old discount
progressstring
Current progress status:
• ongoing: Ongoing
• not_started: Not started
• finished: Finished
• paused: Paused
enable_all_customerboolean
Whether all customers are enabled
is_show_adminstring
Backoffice visibility marker
time_usedint32
Number of times this discount has been used
entitled_customer object
Customer scope of the discount
customer_idsstring[]
Explicit customer IDs that can use the discount
customer_segment_idsstring[]
Customer segment IDs that can use the discount
entitled_product object
Product scope of the discount
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
obtain_product object
Product scope that receives the obtained benefit. Only present for automatic discounts
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
discount_rule object
Rule settings for limit 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
discount_layer object
Layered discount settings
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_combine object
Combined-discount settings
use_with_otherboolean
Whether this discount can be combined with other promotions
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
]

Example

{
  "code": "string",
  "message": "string",
  "data": {
    "discount": {
      "discount_info": {
        "id": "string",
        "discount_name": "string",
        "display_name": "string",
        "discount_target": "string",
        "category": "string",
        "discount_type": "string",
        "discount_method": "string",
        "discount_code": "string",
        "discount_codes": [
          "string"
        ],
        "starts_date": "string",
        "ends_date": "string",
        "starts_at": 0,
        "ends_at": 0,
        "created_at": "string",
        "updated_at": "string",
        "is_old_discount": true,
        "progress": "string",
        "enable_all_customer": true,
        "is_show_admin": "string",
        "time_used": 0
      },
      "entitled_customer": {
        "customer_ids": [
          "string"
        ],
        "customer_segment_ids": [
          "string"
        ]
      },
      "entitled_product": {
        "product_ids": [
          "string"
        ],
        "variant_ids": [
          "string"
        ],
        "collection_ids": [
          "string"
        ],
        "sort": {
          "by": "string",
          "direction": "string",
          "before": "string"
        },
        "selection": "string",
        "sku_extends": {}
      },
      "obtain_product": {
        "product_ids": [
          "string"
        ],
        "variant_ids": [
          "string"
        ],
        "collection_ids": [
          "string"
        ],
        "sort": {
          "by": "string",
          "direction": "string",
          "before": "string"
        },
        "selection": "string",
        "sku_extends": {}
      },
      "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
      },
      "discount_layer": {
        "condition_type": "string",
        "obtain_type": "string",
        "layers": [
          {
            "condition_value": "string",
            "obtain_value": "string",
            "obtain_count": 0
          }
        ]
      },
      "discount_combine": {
        "use_with_other": true
      },
      "entitled_area": {
        "areas": [
          {
            "country_code": "string",
            "province_codes": [
              "string"
            ]
          }
        ]
      }
    }
  }
}