Update the price rule of a code discount
PUT https://{handle}.myshopline.com/admin/openapi/v20260301/sales/price_rules/:price_rule_id.json
handle : The store's unique identifier, which is the prefix of the store's domain name. For example, if a store's domain name is open001.myshopline.com , the store handle is open001 .Update the price rule of a code discount.
Supported code discount types include:
- Fixed amount discount
- Percentage discount
- Buy X get Y discount
- Free shipping discount
Path Parameters
- price_rule_id string requiredThe unique identifier for the price rule.
Request Headers
- Content-Type string requiredThe field must be set to the fixed value
application/json; charset=utf-8. - Authorization string requiredThe access token for the API resource. Refer to App authorization to obtain the access token, and then pass the obtained token in the Bearer format.Example:
Bearer eyJhbGciOiJIUzUxMiJ9.eyJhcHBLZXkiOiJmMjM3OWQyMTYyOGMzM2QxMWRiMWZkYjY5N2EzZjdjMjZlNGMwYTA5Iiwic2VsbGVySWQiOiIyMDAwMjM0ODgwIiwic3RvcmVJZCI6IjE2NzIzNjk3Mjk2MDYiLCJ2ZXJzaW9uIjoiVjIiLCJkb21haW4iOiJodHRwczovL3NsLW9wZW4tc2cubXlzaG9wbGluZS5jb20iLCJ0aW1lc3RhbXAiOjE2NzUzMTk0OTI0MzksImlzcyI6Inlzb3VsIiwiZXhwIjoxNzY5OTI3NDkyfQ.UwQzomM2veGCUaOZ0paUxq5dpc7DXuhHYFvsQ_uIAKduzWcb_j2E4q_36El83sp145D4cKbpcE5KCeeIz-JNQw
Request Body
price_ruleobject
The price rule of a code discount.allocation_limit integerThe maximum number of times the discount can be applied per order. Only applicable to Buy X Get Y discounts. If this parameter is not provided, there is no limit per order. For example, for a Buy 1 item Get 1 item discount, if this parameter is set to3and the cart contains more than six items, the discount applies up to three times.
Value range: 0-99,999,999allocation_method stringThe allocation method of the price rule. Valid values are:-
each: The discount is applied to each entitled item. For example, if the discount is $20 off, each entitled item will receive $20 off. -
across: The discount is spread across all entitled items. For example, if the discount is $20 off, the discount will be applied across all the entitled items, totaling $20 off.
Iftarget_typeis set toshipping_line, thenallocation_methodmust beeach.ends_at stringThe date and time when the price rule ends. If this parameter is not provided, the price rule has no end time.
Format:ISO 8601.Example:2021-08-31T02:20:26+08:00entitled_collection_ids arrayA list of IDs of product collections entitled to the discount. If the discount is Buy X Get Y, these are the collection IDs for product Y.
Whentarget_selectionisentitled, exactly one ofentitled_product_ids,entitled_collection_ids, orentitled_variant_idsmust be specified. Whentarget_selectionisall,entitled_product_ids,entitled_collection_ids, andentitled_variant_idsmust all be empty, indicating that the discount applies to all products.
Maximum size: 500entitled_country_ids arrayA list of country or region IDs eligible for the discount. Only applicable to free shipping discount. If If this parameter is not provided, there's no limit.
Maximum size: 500entitled_product_ids arrayA list of product IDs entitled to the discount. If the discount is Buy X Get Y, these are the product IDs for product Y.
Whentarget_selectionis set toentitled, exactly one ofentitled_product_ids,entitled_collection_ids, orentitled_variant_idsmust be provided. Whentarget_selectionisall,entitled_product_ids,entitled_collection_ids, andentitled_variant_idsmust all be empty, indicating that the discount applies to all products.
Maximum size: 500entitled_variant_idsobject[]
A list of product variant IDs entitled to the discount. If the discount is Buy X Get Y, these are the variant IDs for product Y.
Whentarget_selectionis set toentitled, exactly one ofentitled_product_ids,entitled_collection_ids, orentitled_variant_idsmust be specified. Whentarget_selectionisall,entitled_product_ids,entitled_collection_ids, andentitled_variant_idsmust all be empty, indicating that the discount applies to all products.
Maximum size: 500product_id stringProduct ID.variant_id stringProduct variant ID.id stringThe unique identifier for the price rule.joint_discount booleanWhether the price rule combines with all automatic discounts.true: The price rule combines with all automatic discounts.false: The price rule does not combine with any automatic discounts.
Default value:falsejoint_discount_order booleanWhether the price rule combines with order automatic discounts.true: The price rule combines with order automatic discounts.false: The price rule does not combine with order automatic discounts.
Default value: take the value ofjoint_discountjoint_discount_product booleanWhether the price rule combines with product automatic discounts.true: The price rule combines with product automatic discounts.false: The price rule does not combine with product automatic discounts.
Default value: take the value ofjoint_discountjoint_discount_shipping booleanWhether the price rule combines with shipping automatic discounts.true: The price rule combines with shipping automatic discounts.false: The price rule does not combine with shipping automatic discounts.
Default value: take the value ofjoint_discountoverlay_discount_code booleanWhether the price rule combines with all discount codes.true: The price rule combines with all discount codes.false: The price rule does not combine with any discount codes.
Default value:falseoverlay_discount_code_order booleanWhether the price rule combines with order discount codes.true: The price rule combines with order discount codes.false: The price rule does not combine with order discount codes.
Default value: take the value ofoverlay_discount_codeoverlay_discount_code_product booleanWhether the price rule combines with product discount codes.true: The price rule combines with product discount codes.false: The price rule does not combine with product discount codes.
Default value: take the value ofoverlay_discount_codeoverlay_discount_code_shipping booleanWhether the price rule combines with shipping discount codes.true: The price rule combines with shipping discount codes.false: The price rule does not combine with shipping discount codes.
Default value: take the value ofoverlay_discount_codeprerequisite_collection_ids arrayIf the discount is Buy X Get Y, this field specifies the collection ID list for product X. Exactly one ofprerequisite_variant_ids,prerequisite_collection_idsorprerequisite_product_idsmust be specified.
Maximum size: 500prerequisite_customer_ids arrayA list of IDs of customers eligible for the discount. Cannot be used together withprerequisite_saved_search_ids. If bothprerequisite_saved_search_idsandprerequisite_customer_idsare not provided, the price rule applies to all customers.
Maximum size: 500prerequisite_product_ids arrayIf the discount is Buy X Get Y, this field specifies the product ID list for product X. Exactly one ofprerequisite_variant_ids,prerequisite_collection_idsorprerequisite_product_idsmust be specified.
Maximum size: 500prerequisite_quantity_rangeobject
The minimum quantity of items for the price rule to be applicable. Exactly one ofprerequisite_quantity_rangeorprerequisite_subtotal_rangemust be specified.greater_than_or_equal_to integerThe minimum quantity of items required. If this parameter is not provided, no minimum quantity is required.
Value range: 1-999prerequisite_saved_search_ids arrayA list of IDs of customer segments that can use the discount. Cannot be used together withprerequisite_customer_ids. If bothprerequisite_saved_search_idsandprerequisite_customer_idsare not provided, the price rule applies to all customers.
Maximum size: 500prerequisite_shipping_price_rangeobject
If the discount is for free shipping, this field defines the maximum shipping amount eligible for the discount. Can only be used whentarget_typeisshipping_line.less_than_or_equal_to stringThe maximum shipping price that qualifies for the discount. The precision of the amount matches the store currency setting, and the system will automatically remove any digits beyond this precision. If If this parameter is not provided, there's no limit.
Value range: 1-99,999,999,999prerequisite_subtotal_rangeobject
The minimum subtotal requirement to apply the discount. Exactly one ofprerequisite_quantity_rangeorprerequisite_subtotal_rangemust be specified.greater_than_or_equal_to stringThe minimum subtotal value. If this parameter is not provided, no minimum subtotal is required. The precision of the amount matches the store currency setting, and the system will automatically remove any digits beyond this precision.
Value range: 1-99,999,999,999prerequisite_to_entitlement_purchaseobject
For Buy X Get Y discounts, defines the minimum total amount of product X required to apply the discount. Exactly one ofprerequisite_amountorprerequisite_quantityinprerequisite_to_entitlement_quantity_ratiomust be specified.prerequisite_amount stringThe minimum amount of product X required. If this parameter is not provided, there's no minimum amount limit. The precision of the amount matches the store currency setting, and the system will automatically remove any digits beyond this precision.
Value range: 1-99,999,999,999prerequisite_to_entitlement_quantity_ratioobject
Defines the Buy X Get Y ratio for the discount, including the minimum quantity of product X required to apply the discount and the number of product Y being discounted.entitled_quantity integerThe number of product Y being discounted when the requirement is met.
Value range: 1-999prerequisite_quantity integerThe minimum required quantity of product X. Exactly one ofprerequisite_amountinprerequisite_to_entitlement_purchaseorprerequisite_quantitymust be specified.
Value range: 1-999prerequisite_variant_idsobject[]
If the discount is Buy X Get Y, this field specifies the variant ID list for product X. Exactly one ofprerequisite_variant_ids,prerequisite_collection_idsorprerequisite_product_idsmust be specified.
Maximum size: 500product_id stringProduct ID.variant_id stringProduct variant ID.recurring_cycle_limit integerNumber of subscription billing cycles the discount applies to. Only-1and positive integers are supported.
This field is applicable only to the following types of discounts: order discount codes, product discount codes, and free shipping discount codes. For example: If set to3, the discount will apply to the first three billing cycles of the subscription. If set to1, the discount will only apply to the initial subscription order. If set to-1, the discount will apply to all recurring payments in the subscription.Example:-1sales_channels arrayThe sale channels eligible for the discount. If this parameter is not provided, the discount applies to all sales channels. If specifies certain channels, the discount is only valid on those channels.Example:["web"]starts_at string requiredThe date and time when the price rule starts.
Format: ISO 8601.Example:2021-08-31T02:20:26+08:00target_selection stringThe product scope to which the price rule applies. Valid values are:all: Applies to all productsentitled: Applies to selected products only
Iftarget_selectionis set toentitled, exactly one ofentitled_product_ids,entitled_collection_ids, orentitled_variant_idsmust have a value. Whentarget_typeisshipping_line,target_selectionmust be set toall.Example:alltarget_type stringThe target type that the price rule applies to. Valid values:line_item: The price rule applies to the line items.shipping_line: The price rule applies to the shipping line.
To update a free shipping discount code, specifyshipping_line. To update other types of discounts, specifyline_item.title string requiredThe title of the price rule, used for display to the buyer.
Maximum length: 100Example:20$ OFF for new customersusage_limit integerThe maximum number of times that the discount codes can be used. If this parameter is not provided, it indicates unlimited usage.
Value range: 1-99,999,999usage_per_customer integerThe maximum number of times each customer can use each discount code under this price rule. If this parameter is not provided, it indicates unlimited usage.
Value range: 1-99,999,999value string requiredThe value of the price rule.- If the value of
value_typeispercentage, then thevalueindicates the percentage value of the discount. Must be a positive number(0-100). - If the value of
value_typeisfixed_amount, then thevalueindicates the amount value of the discount. Must be a negative number ranging from -99,999,999,999 to 0. The precision of the amount matches the store currency setting, and the system will automatically remove any digits beyond this precision.
Example: For a 10% discount, setvalueto10. For a discount amount of 20, setvalueto-20.Example:-20value_type string requiredDefines how the discount is applied. Valid values are:percentage:Percentage-based discountfixed_amount:Fixed-amount discount
Must bepercentageiftarget_typeisshipping_lineor for Buy X Get Y discounts.Example:fixed_amount
Status Codes
- 200
- 401
- 429
For the complete list of codes and messages, see Http status code.
Response Headers
traceId
A globally unique identifier for the request. It is used to track the request flow throughout the system, allowing for easy location and debugging when issues arise.
Response Body
price_ruleobject
The price rule of a discount code.allocation_limit integerThe maximum number of times the discount can be applied in a single order. Only applicable to Buy X Get Y discounts. For example, if the value of this parameter is3, A Buy 1 hat Get 1 discount can be applied up to 3 times if more than 6 hats are in the cart. Ifnull, there's no limit per order.allocation_method stringThe allocation method of the price rule. Valid values are:each: The discount is applied to each entitled item. For example, if the discount is $20 off, each entitled item will receive $20 off.across: The discount is spread across all entitled items. For example, if the discount is $20 off, the discount will be applied across all the entitled items, totaling $20 off.
create_at stringThe date and time when the price rule was created.
Format: ISO 8601.Example:2021-08-31T02:20:26+08:00ends_at stringThe date and time when the price rule ends. Ifnull, the price rule has no end time.
Format:ISO 8601.Example:2021-08-31T02:20:26+08:00entitled_collection_ids arrayA list of IDs of product collections entitled to the discount. If the discount is Buy X Get Y, this refers to the collections for product Y.
Maximum size: 500entitled_country_ids arrayA list of IDs of shipping countries or regions that will be entitled to the discount.
Maximum size: 500entitled_product_ids arrayA list of IDs of products that will be entitled to the discount. When the discount is Buy X Get Y, it indicates the list of the entitled products of product Y.
Maximum size: 500entitled_variant_idsobject[]
A list of product variant IDs entitled to the discount. If the discount is Buy X Get Y, these are the variant IDs for product Y.
Maximum size: 500product_id stringProduct ID.variant_id stringProduct variant ID.id stringThe unique identifier for the price rule.joint_discount booleanWhether the price rule combines with all automatic discounts.true: The price rule combines with all automatic discounts.false: The price rule does not combine with any automatic discounts.
joint_discount_order booleanWhether the price rule combines with order automatic discounts.true: The price rule combines with order automatic discounts.false: The price rule does not combine with any order automatic discounts.
joint_discount_product booleanWhether the price rule combines with product automatic discounts.true: The price rule combines with product automatic discounts.false: The price rule does not combine with any product automatic discounts.
joint_discount_shipping booleanWhether the price rule combines with shipping automatic discounts.true: The price rule combines with shipping automatic discounts.false: The price rule does not combine with any shipping automatic discounts.
overlay_discount_code booleanWhether the price rule combines with all discount codes.true: The price rule combines with all discount codes.false: The price rule does not combine with any discount codes.
overlay_discount_code_order booleanWhether the price rule combines with order discount codes.true: The price rule combines with order discount codes.false: The price rule does not combine with order discount codes.
overlay_discount_code_product booleanWhether the price rule combines with product discount codes.true: The price rule combines with product discount codes.false: The price rule does not combine with product discount codes.
overlay_discount_code_shipping booleanWhether the price rule combines with shipping discount codes.true: The price rule combines with shipping discount codes.false: The price rule does not combine with shipping discount codes.
prerequisite_collection_ids arrayIf the discount is Buy X Get Y, this field specifies the collection ID list for product X.
Maximum size: 500prerequisite_customer_ids arrayA list of IDs of customers that can use the discount.
Maximum size: 500prerequisite_product_ids arrayIf the discount is Buy X Get Y, this field specifies the product ID list for product X.
Maximum size: 500prerequisite_quantity_rangeobject
The minimum quantity of items for the price rule to be applicable.greater_than_or_equal_to integerThe minimum required quantity.prerequisite_saved_search_ids arrayA list of IDs of customer segments that can use the discount.
Maximum size: 500prerequisite_shipping_price_rangeobject
If the discount is for free shipping, this field defines the maximum shipping amount eligible for the discount.less_than_or_equal_to stringThe maximum shipping price that qualifies for the discount.prerequisite_subtotal_rangeobject
The minimum subtotal that's required for the discount to be applied.greater_than_or_equal_to stringThe minimum required subtotal.prerequisite_to_entitlement_purchaseobject
For Buy X Get Y discounts, defines the minimum total amount of product X required to apply the discount.prerequisite_amount stringThe minimum required subtotal of X products.prerequisite_to_entitlement_quantity_ratioobject
Defines the Buy X Get Y ratio for the discount, including the minimum quantity of product X required to apply the discount and the number of product Y being discounted.entitled_quantity integerThe number of product Y being discounted.prerequisite_quantity integerThe minimum required quantity of product X.prerequisite_variant_idsobject[]
If the discount is Buy X Get Y, this field specifies the variant ID list for product X.
Maximum size: 500product_id stringProduct ID.variant_id stringProduct variant ID.recurring_cycle_limit integerNumber of subscription billing cycles the discount applies to.
This field is applicable only to the following types of discounts: order discount codes, product discount codes, and free shipping discount codes. For example: If the value of this parameter is3, the discount will apply to the first three billing cycles of the subscription. If the value of this parameter is1, the discount will only apply to the initial subscription order. If the value of this parameter is-1, the discount will apply to all recurring payments in the subscription.Example:-1sales_channels arrayThe sales channels eligible for the discount. Whensales_channelsisall, the discount applies to all sales channels. Ifsales_channelsspecifies certain channels, the discount is only valid on those channels.Example:["web"]starts_at stringThe date and time when the price rule starts.
Format: ISO 8601.target_selection stringThe target selection method of the price rule. Valid values are:all: Applies to all productsentitled: Applies to selected products only
target_type stringThe target type that the price rule applies to. Valid values:line_item: The price rule applies to the line items.shipping_line: The price rule applies to shipping line.
target_user_feature_valuesobject[]
The customers to whom the current price rule applies, including applicable customer range and customer lists.target_value stringEligible customers for the price rule.- When
valueisall,target_valueisnull. - When
valueisSpecific Customer Groups,target_valuereturns customer group IDs. - When
valueisSpecific Customer,target_valuereturns customer IDs. - When
valueisprerequisite,target_valuereturns membership tier IDs.
value stringThe customer range to which the current price rule applies.all: allSpecific Customer Groups: specific customer segmentsSpecific Customers: specific customersprerequisite: specific membership tiers
title stringThe title of the price rule, used for display to the buyer.update_at stringThe date and time when the price rule was updated.
Format: ISO 8601.Example:2021-08-31T02:20:26+08:00usage_limit integerThe maximum number of times that the discount codes can be used. Ifnull, it indicates unlimited usage.usage_per_customer integerThe maximum number of times each customer can use each discount code under this price rule. Ifnull, it indicates unlimited usage per customer.value stringThe value of the price rule. Ifvalue_typeispercentage, thenvalueindicates the percentage value of the discount. Ifvalue_typeisfixed_amount, thenvalueindicates the amount value of the discount.value_type stringThe discount's effect. Valid values are:percentage:A discount that gives customers a percentage off.fixed_amount:A discount that gives customers a fixed amount off.
API Explorer
Debugger
Examples
Was this article helpful to you?