Requires write_price_rules access scope.
For more info, refer to:
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 required
    The unique identifier for the price rule.
Request Headers
  • Content-Type string required
    The field must be set to the fixed value application/json; charset=utf-8.
  • Authorization string required
    The 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 integer
    The 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 to 3 and the cart contains more than six items, the discount applies up to three times.
    Value range: 0-99,999,999
  • allocation_method string
    The 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.
    If target_type is set to shipping_line, then allocation_method must be each.
  • ends_at string
    The 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:00
  • entitled_collection_ids array
    A 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.
    When target_selection is entitled, exactly one of entitled_product_ids, entitled_collection_ids, or entitled_variant_ids must be specified. When target_selection is all, entitled_product_ids, entitled_collection_ids, and entitled_variant_ids must all be empty, indicating that the discount applies to all products.
    Maximum size: 500
  • entitled_country_ids array
    A 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: 500
  • entitled_product_ids array
    A list of product IDs entitled to the discount. If the discount is Buy X Get Y, these are the product IDs for product Y.
    When target_selection is set to entitled, exactly one of entitled_product_ids, entitled_collection_ids, or entitled_variant_ids must be provided. When target_selection is all, entitled_product_ids, entitled_collection_ids, and entitled_variant_ids must all be empty, indicating that the discount applies to all products.
    Maximum size: 500
  • entitled_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.
    When target_selection is set to entitled, exactly one of entitled_product_ids, entitled_collection_ids, or entitled_variant_ids must be specified. When target_selection is all, entitled_product_ids, entitled_collection_ids, and entitled_variant_ids must all be empty, indicating that the discount applies to all products.
    Maximum size: 500
  • product_id string
    Product ID.
  • variant_id string
    Product variant ID.
  • id string
    The unique identifier for the price rule.
  • joint_discount boolean
    Whether 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: false
  • joint_discount_order boolean
    Whether 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 of joint_discount
  • joint_discount_product boolean
    Whether 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 of joint_discount
  • joint_discount_shipping boolean
    Whether 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 of joint_discount
  • overlay_discount_code boolean
    Whether 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: false
  • overlay_discount_code_order boolean
    Whether 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 of overlay_discount_code
  • overlay_discount_code_product boolean
    Whether 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 of overlay_discount_code
  • overlay_discount_code_shipping boolean
    Whether 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 of overlay_discount_code
  • prerequisite_collection_ids array
    If the discount is Buy X Get Y, this field specifies the collection ID list for product X. Exactly one of prerequisite_variant_ids, prerequisite_collection_ids or prerequisite_product_ids must be specified.
    Maximum size: 500
  • prerequisite_customer_ids array
    A list of IDs of customers eligible for the discount. Cannot be used together with prerequisite_saved_search_ids. If both prerequisite_saved_search_ids and prerequisite_customer_ids are not provided, the price rule applies to all customers.
    Maximum size: 500
  • prerequisite_product_ids array
    If the discount is Buy X Get Y, this field specifies the product ID list for product X. Exactly one of prerequisite_variant_ids, prerequisite_collection_ids or prerequisite_product_ids must be specified.
    Maximum size: 500
  • prerequisite_quantity_rangeobject
    The minimum quantity of items for the price rule to be applicable. Exactly one of prerequisite_quantity_range or prerequisite_subtotal_range must be specified.
  • greater_than_or_equal_to integer
    The minimum quantity of items required. If this parameter is not provided, no minimum quantity is required.
    Value range: 1-999
  • prerequisite_saved_search_ids array
    A list of IDs of customer segments that can use the discount. Cannot be used together with prerequisite_customer_ids. If both prerequisite_saved_search_ids and prerequisite_customer_ids are not provided, the price rule applies to all customers.
    Maximum size: 500
  • prerequisite_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 when target_type is shipping_line.
  • less_than_or_equal_to string
    The 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,999
  • prerequisite_subtotal_rangeobject
    The minimum subtotal requirement to apply the discount. Exactly one of prerequisite_quantity_range or prerequisite_subtotal_range must be specified.
  • greater_than_or_equal_to string
    The 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,999
  • prerequisite_to_entitlement_purchaseobject
    For Buy X Get Y discounts, defines the minimum total amount of product X required to apply the discount. Exactly one of prerequisite_amount or prerequisite_quantity in prerequisite_to_entitlement_quantity_ratio must be specified.
  • prerequisite_amount string
    The 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,999
  • 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 integer
    The number of product Y being discounted when the requirement is met.
    Value range: 1-999
  • prerequisite_quantity integer
    The minimum required quantity of product X. Exactly one of prerequisite_amount in prerequisite_to_entitlement_purchase or prerequisite_quantity must be specified.
    Value range: 1-999
  • prerequisite_variant_idsobject[]
    If the discount is Buy X Get Y, this field specifies the variant ID list for product X. Exactly one of prerequisite_variant_ids, prerequisite_collection_ids or prerequisite_product_ids must be specified.
    Maximum size: 500
  • product_id string
    Product ID.
  • variant_id string
    Product variant ID.
  • recurring_cycle_limit integer
    Number of subscription billing cycles the discount applies to. Only -1 and 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 to 3, the discount will apply to the first three billing cycles of the subscription. If set to 1, 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: -1
  • sales_channels array
    The 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 required
    The date and time when the price rule starts.
    Format: ISO 8601.
    Example: 2021-08-31T02:20:26+08:00
  • target_selection string
    The product scope to which the price rule applies. Valid values are:
    • all: Applies to all products
    • entitled: Applies to selected products only
    If target_selection is set to entitled, exactly one of entitled_product_ids, entitled_collection_ids, or entitled_variant_ids must have a value. When target_type is shipping_line, target_selection must be set to all.
    Example: all
  • target_type string
    The 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, specify shipping_line. To update other types of discounts, specify line_item.
  • title string required
    The title of the price rule, used for display to the buyer.
    Maximum length: 100
    Example: 20$ OFF for new customers
  • usage_limit integer
    The 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,999
  • usage_per_customer integer
    The 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,999
  • value string required
    The value of the price rule.
    • If the value of value_type is percentage, then the value indicates the percentage value of the discount. Must be a positive number(0-100).
    • If the value of value_type is fixed_amount, then the value indicates 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, set value to 10. For a discount amount of 20, set value to -20.
    Example: -20
  • value_type string required
    Defines how the discount is applied. Valid values are:
    • percentage:Percentage-based discount
    • fixed_amount:Fixed-amount discount
    Must be percentage if target_type is shipping_line or for Buy X Get Y discounts.
    Example: fixed_amount
Status Codes
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 integer
    The 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 is 3, A Buy 1 hat Get 1 discount can be applied up to 3 times if more than 6 hats are in the cart. If null, there's no limit per order.
  • allocation_method string
    The 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 string
    The date and time when the price rule was created.
    Format: ISO 8601.
    Example: 2021-08-31T02:20:26+08:00
  • ends_at string
    The date and time when the price rule ends. If null, the price rule has no end time.
    Format:ISO 8601.
    Example: 2021-08-31T02:20:26+08:00
  • entitled_collection_ids array
    A 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: 500
  • entitled_country_ids array
    A list of IDs of shipping countries or regions that will be entitled to the discount.
    Maximum size: 500
  • entitled_product_ids array
    A 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: 500
  • entitled_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: 500
  • product_id string
    Product ID.
  • variant_id string
    Product variant ID.
  • id string
    The unique identifier for the price rule.
  • joint_discount boolean
    Whether 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 boolean
    Whether 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 boolean
    Whether 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 boolean
    Whether 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 boolean
    Whether 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 boolean
    Whether 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 boolean
    Whether 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 boolean
    Whether 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 array
    If the discount is Buy X Get Y, this field specifies the collection ID list for product X.
    Maximum size: 500
  • prerequisite_customer_ids array
    A list of IDs of customers that can use the discount.
    Maximum size: 500
  • prerequisite_product_ids array
    If the discount is Buy X Get Y, this field specifies the product ID list for product X.
    Maximum size: 500
  • prerequisite_quantity_rangeobject
    The minimum quantity of items for the price rule to be applicable.
  • greater_than_or_equal_to integer
    The minimum required quantity.
  • prerequisite_saved_search_ids array
    A list of IDs of customer segments that can use the discount.
    Maximum size: 500
  • prerequisite_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 string
    The 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 string
    The 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 string
    The 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 integer
    The number of product Y being discounted.
  • prerequisite_quantity integer
    The 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: 500
  • product_id string
    Product ID.
  • variant_id string
    Product variant ID.
  • recurring_cycle_limit integer
    Number 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 is 3, the discount will apply to the first three billing cycles of the subscription. If the value of this parameter is 1, 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: -1
  • sales_channels array
    The sales channels eligible for the discount. When sales_channels is all, the discount applies to all sales channels. If sales_channels specifies certain channels, the discount is only valid on those channels.
    Example: ["web"]
  • starts_at string
    The date and time when the price rule starts.
    Format: ISO 8601.
  • target_selection string
    The target selection method of the price rule. Valid values are:
    • all: Applies to all products
    • entitled: Applies to selected products only
  • target_type string
    The 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 string
    Eligible customers for the price rule.
    • When value is all, target_value is null.
    • When value is Specific Customer Groups, target_value returns customer group IDs.
    • When value is Specific Customer, target_value returns customer IDs.
    • When value is prerequisite, target_value returns membership tier IDs.
  • value string
    The customer range to which the current price rule applies.
    • all: all
    • Specific Customer Groups: specific customer segments
    • Specific Customers: specific customers
    • prerequisite: specific membership tiers
  • title string
    The title of the price rule, used for display to the buyer.
  • update_at string
    The date and time when the price rule was updated.
    Format: ISO 8601.
    Example: 2021-08-31T02:20:26+08:00
  • usage_limit integer
    The maximum number of times that the discount codes can be used. If null, it indicates unlimited usage.
  • usage_per_customer integer
    The maximum number of times each customer can use each discount code under this price rule. If null, it indicates unlimited usage per customer.
  • value string
    The value of the price rule. If value_type is percentage, then value indicates the percentage value of the discount. If value_type is fixed_amount, then value indicates the amount value of the discount.
  • value_type string
    The 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
https://openapiceshidianpu.myshopline.com/admin/openapi/v20260301

ParamOptions

path required
header required

Body

required
{
  "price_rule": {
    "allocation_limit": null,
    "allocation_method": null,
    "ends_at": "2021-08-31T02:20:26+08:00",
    "entitled_collection_ids": null,
    "entitled_country_ids": null,
    "entitled_product_ids": null,
    "entitled_variant_ids": [
      {
        "product_id": null,
        "variant_id": null
      }
    ],
    "id": null,
    "joint_discount": null,
    "joint_discount_order": null,
    "joint_discount_product": null,
    "joint_discount_shipping": null,
    "overlay_discount_code": null,
    "overlay_discount_code_order": null,
    "overlay_discount_code_product": null,
    "overlay_discount_code_shipping": null,
    "prerequisite_collection_ids": null,
    "prerequisite_customer_ids": null,
    "prerequisite_product_ids": null,
    "prerequisite_quantity_range": {
      "greater_than_or_equal_to": null
    },
    "prerequisite_saved_search_ids": null,
    "prerequisite_shipping_price_range": {
      "less_than_or_equal_to": null
    },
    "prerequisite_subtotal_range": {
      "greater_than_or_equal_to": null
    },
    "prerequisite_to_entitlement_purchase": {
      "prerequisite_amount": null
    },
    "prerequisite_to_entitlement_quantity_ratio": {
      "entitled_quantity": null,
      "prerequisite_quantity": null
    },
    "prerequisite_variant_ids": [
      {
        "product_id": null,
        "variant_id": null
      }
    ],
    "recurring_cycle_limit": -1,
    "sales_channels": [
      "web"
    ],
    "starts_at": "2021-08-31T02:20:26+08:00",
    "target_selection": "all",
    "target_type": null,
    "title": "20$ OFF for new customers",
    "usage_limit": null,
    "usage_per_customer": null,
    "value": "-20",
    "value_type": "fixed_amount"
  }
}

Language

curl --request PUT \
--url https://openapiceshidianpu.myshopline.com/admin/openapi/v20260301/sales/price_rules/price_rule_id.json \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhcHBLZXkiOiJmMjM3OWQyMTYyOGMzM2QxMWRiMWZkYjY5N2EzZjdjMjZlNGMwYTA5Iiwic2VsbGVySWQiOiIyMDAwMjM0ODgwIiwic3RvcmVJZCI6IjE2NzIzNjk3Mjk2MDYiLCJ2ZXJzaW9uIjoiVjIiLCJkb21haW4iOiJodHRwczovL3NsLW9wZW4tc2cubXlzaG9wbGluZS5jb20iLCJ0aW1lc3RhbXAiOjE2NzUzMTk0OTI0MzksImlzcyI6Inlzb3VsIiwiZXhwIjoxNzY5OTI3NDkyfQ.UwQzomM2veGCUaOZ0paUxq5dpc7DXuhHYFvsQ_uIAKduzWcb_j2E4q_36El83sp145D4cKbpcE5KCeeIz-JNQw' \
--header 'Content-Type: application/json; charset=utf-8' \
--header 'accept: application/json'
Examples
Update the price rule of a code discount
Request
{
"price_rule": {
"allocation_limit": "2",
"allocation_method": "across",
"ends_at": "2023-07-10T11:00:00+08:00",
"entitled_country_ids": [
"\"HK\",\"TW\",\"SG\""
],
"entitled_variant_ids": [
{}
],
"id": "SL201SAS06061775335241819244",
"joint_discount": false,
"joint_discount_order": false,
"joint_discount_product": false,
"joint_discount_shipping": false,
"overlay_discount_code": false,
"overlay_discount_code_order": false,
"overlay_discount_code_product": false,
"overlay_discount_code_shipping": true,
"prerequisite_quantity_range": {
"greater_than_or_equal_to": "5"
},
"prerequisite_shipping_price_range": {},
"prerequisite_subtotal_range": {},
"prerequisite_to_entitlement_purchase": {},
"prerequisite_to_entitlement_quantity_ratio": {},
"prerequisite_variant_ids": [
{}
],
"starts_at": "2023-07-10T11:00:00+08:00",
"target_selection": "all",
"target_type": "line_item",
"title": "This is title of price rule",
"usage_limit": "2",
"usage_per_customer": "10",
"value": "20",
"value_type": "percentage"
}
}
Response
{
"price_rule": {
"allocation_method": "across",
"create_at": "2023-08-10T11:27:54+08:00",
"ends_at": "2023-07-10T11:00:00+08:00",
"entitled_country_ids": [],
"id": "SL201SAS06061775335241819244",
"joint_discount": false,
"joint_discount_order": false,
"joint_discount_product": false,
"joint_discount_shipping": false,
"overlay_discount_code": false,
"overlay_discount_code_order": false,
"overlay_discount_code_product": false,
"overlay_discount_code_shipping": true,
"prerequisite_quantity_range": {
"greater_than_or_equal_to": 5
},
"sales_channels": [
"all"
],
"starts_at": "2023-07-10T11:00:00+08:00",
"target_selection": "all",
"target_type": "line_item",
"title": "This is title of price rule",
"update_at": "2023-08-10T12:00:54+08:00",
"usage_limit": 2,
"usage_per_customer": 10,
"value": "20",
"value_type": "percentage"
}
}
Was this article helpful to you?