PriceRule

Version 2019-10

You can use the PriceRule resource to create discounts using conditions. You can then associate the conditions with a discount code by using the DiscountCode resource. Merchants can distribute the discount codes to their customers.

Using the PriceRule resource, you can create discounts that specify a discount as a percentage, a fixed amount, or free shipping. You use entitlements and prerequisites to dynamically build these discounts.

To learn about how to associate a price rule with a discount code, see the DiscountCode resource.

Create a price rule

You can create price rules with entitlements and prerequisites. Entitlements describe the designated resources that a discount applies to, such as specific products, variants, or collections. Prerequisites describe the requirements that must be met in order for the discount to apply to the entitled resources. For example, you might want a discount to apply only to a certain shipping price range, or a certain subtotal range.

You can use entitlements, prereqisites, and other conditions to create discounts, such as the following examples:

  • $10 off the buyer's order if the total exceeds $40
  • 15% off certain collections
  • free shipping on orders over $100.00 for Canadian buyers, redeemable up to 20 times

For examples of how to create price rules, see the POST method.

What you can do with PriceRule

The Shopify API lets you do the following with the PriceRule resource. More detailed versions of these general actions may be available:

PriceRule properties

allocation_method 
"allocation_method": "each"

The allocation method of the price rule. Valid values:

  • each: The discount is applied to each of the entitled items. For example, for a price rule that takes $15 off, each entitled line item in a checkout will be discounted by $15.
  • across: The calculated discount amount will be applied across the entitled items. For example, for a price rule that takes $15 off, the discount will be applied across all the entitled items.

When the value of target_type is shipping_line, then this value must be each.
created_at
read-only 
"created_at": "2017-03-13T16:09:54-04:00"

The date and time (ISO 8601 format) when the price rule was created.
updated_at
read-only 
"updated_at": "2017-03-14T16:09:54-04:00"

The date and time (ISO 8601 format) when the price rule was updated.
customer_selection 
"customer_selection": "prerequisite"

The customer selection for the price rule. Valid values:

  • all: The price rule is valid for all customers.
  • prerequisite: The customer must either belong to one of the customer saved searches specified by prerequisite_saved_search_ids, or be one of the customers specified by prerequisite_customer_ids.
ends_at 
"ends_at": "2017-04-19T17:59:10Z"

The date and time (ISO 8601 format) when the price rule ends. Must be after starts_at.
entitled_collection_ids 
"entitled_collection_ids": [
  4564654869,
  8979761006
]

A list of IDs of collections whose products will be eligible to the discount. It can be used only with target_type set to line_item and target_selection set to entitled. It can't be used in combination with entitled_product_ids or entitled_variant_ids.
entitled_country_ids 
" entitled_country_ids": [
  7897987023,
  3569053679
]

A list of IDs of shipping countries that will be entitled to the discount. It can be used only with target_type set to shipping_line and target_selection set to entitled.
entitled_product_ids 
"entitled_product_ids": [
  7897397755,
  42382368242
]

A list of IDs of products that will be entitled to the discount. It can be used only with target_type set to line_item and target_selection set to entitled.

If a product variant is included in entitled_variant_ids, then entitled_product_ids can't include the ID of the product associated with that variant.
entitled_variant_ids 
"entitled_variant_ids": [
  6798798798,
  5675765905
]

A list of IDs of product variants that will be entitled to the discount. It can be used only with target_type set to line_item and target_selection set to entitled.

If a product is included in entitled_product_ids, then entitled_variant_ids can't include the ID of any variants associated with that product.
id
read-only 
"id": 9808080986

The ID for the price rule.
once_per_customer 
"once_per_customer": true

Whether the generated discount code will be valid only for a single use per customer. This is tracked using customer ID.
prerequisite_customer_ids 
"prerequisite_customer_ids": [
  384028349005,
  3492039843
]

A list of customer IDs. For the price rule to be applicable, the customer must match one of the specified customers.

If prerequisite_customer_ids is populated, then prerequisite_saved_search_ids must be empty.
prerequisite_quantity_range 
"prerequisite_quantity_range": {
  "greater_than_or_equal_to": 2
}

The minimum number of items for the price rule to be applicable. It has the following property:

  • greater_than_or_equal_to: The quantity of an entitled cart item must be greater than or equal to this value.
prerequisite_saved_search_ids 
"prerequisite_saved_search_ids": [
  1123452345,
  43535363636
]

A list of customer saved search IDs. For the price rule to be applicable, the customer must be in the group of customers matching a customer saved search.

If prerequisite_saved_search_ids is populated, then prerequisite_customer_ids must be empty.
prerequisite_shipping_price_range 
"prerequisite_shipping_price_range": {
  "less_than_or_equal_to": "10.0"
}

The maximum shipping price for the price rule to be applicable. It has the following property:

  • less_than_or_equal_to: The shipping price must be less than or equal to this value.
prerequisite_subtotal_range 
"prerequisite_subtotal_range": {
  "greater_than_or_equal_to": "40.0"
}

The minimum subtotal for the price rule to be applicable. It has the following property:

  • greater_than_or_equal_to: The subtotal of the entitled cart items must be greater than or equal to this value for the discount to apply.
starts_at 
"starts_at": "2017-01-19T17:59:10Z"

The date and time (ISO 8601 format) when the price rule starts.

target_selection 
"target_selection": "entitled"

The target selection method of the price rule. Valid values:

  • all: The price rule applies the discount to all line items in the checkout.
  • entitled: The price rule applies the discount to selected entitlements only.
target_type 
"target_type": "line_item"

The target type that the price rule applies to. Valid values:

  • line_item: The price rule applies to the cart's line items.
  • shipping_line: The price rule applies to the cart's shipping lines.
title 
"title": "SUMMERSALE10OFF"

The title of the price rule. This is used by the Shopify admin search to retrieve discounts. It is also displayed on the Discounts page of the Shopify admin for bulk discounts.

For non-bulk discounts, the discount code is displayed on the admin.

For a consistent search experience, use the same value for title as the code property of the associated discount code.
usage_limit 
"usage_limit": 10

The maximum number of times the price rule can be used, per discount code.
prerequisite_product_ids 
"prerequisite_product_ids": [
  7897397755,
  42382368242
]

List of product ids that will be a prerequisites for a Buy X Get Y type discount. The prerequisite_product_ids can be used only with:

  • target_type set to line_item,
  • target_selection set to entitled,
  • allocation_method set to each and
  • prerequisite_to_entitlement_quantity_ratio defined.

Caution

If a product variant is included in prerequisite_variant_ids, then prerequisite_product_ids can't include the ID of the product associated with that variant.
prerequisite_variant_ids 
"prerequisite_variant_ids": [
  6798798798,
  5675765905
]

List of variant ids that will be a prerequisites for a Buy X Get Y type discount. The entitled_variant_ids can be used only with:

  • target_type set to line_item,
  • target_selection set to entitled,
  • allocation_method set to each and
  • prerequisite_to_entitlement_quantity_ratio defined.

Caution

If a product is included in prerequisite_product_ids, then prerequisite_variant_ids can't include the ID of any variants associated with that product.
prerequisite_collection_ids 
"prerequisite_collection_ids": [
  4564654869,
  8979761006
]

List of collection ids that will be a prerequisites for a Buy X Get Y discount. The entitled_collection_ids can be used only with:

  • target_type set to line_item,
  • target_selection set to entitled,
  • allocation_method set to each and
  • prerequisite_to_entitlement_quantity_ratio defined.
Cannot be used in combination with prerequisite_product_ids or prerequisite_variant_ids.
value 
"value": -35

The value of the price rule. If if the value of target_type is shipping_line, then only -100 is accepted. The value must be negative.
value_type 
"value_type": "fixed_amount"

The value type of the price rule. Valid values:

  • fixed_amount: Applies a discount of value as a unit of the store's currency. For example, if value is -30 and the store's currency is USD, then $30 USD is deducted when the discount is applied.
  • percentage: Applies a percentage discount of value. For example, if value is -30, then 30% will be deducted when the discount is applied.

If target_type is shipping_line, then only percentage is accepted.
prerequisite_to_entitlement_quantity_ratio 
"prerequisite_to_entitlement_quantity_ratio": {
  "prerequisite_quantity": 2,
  "entitled_quantity": 1
}

Buy/Get ratio for a Buy X Get Y discount. prerequisite_quantity defines the necessary 'buy' quantity and entitled_quantity the offered 'get' quantity.

The prerequisite_to_entitlement_quantity_ratio can be used only with:

  • value_type set to percentage,
  • target_type set to line_item,
  • target_selection set to entitled,
  • allocation_method set to each,
  • prerequisite_product_ids or prerequisite_variant_ids or prerequisite_collection_ids defined and
  • entitled_product_ids or entitled_variant_ids or entitled_collection_ids defined.

Caution

Cannot be used in combination with prerequisite_subtotal_range, prerequisite_quantity_range or prerequisite_shipping_price_range.
allocation_limit 
"allocation_limit": 3

The number of times the discount can be allocated on the cart - if eligible. For example a Buy 1 hat Get 1 hat for free discount can be applied 3 times on a cart having more than 6 hats, where maximum of 3 hats get discounted - if the allocation_limit is 3. Empty (null) allocation_limit means unlimited number of allocations.

Caution

allocation_limit is only working with Buy X Get Y discount. The default value on creation will be null (unlimited).

Endpoints

POST /admin/api/2019-10/price_rules.json
Creates a price rule

Create a price rule that gives a select group of customers $5 off their order

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "5OFFCUSTOMERGROUP",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "value_type": "fixed_amount",
    "value": "-5.0",
    "customer_selection": "prerequisite",
    "prerequisite_saved_search_ids": [
      789629109
    ],
    "starts_at": "2017-01-19T17:59:10Z"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341483,
    "value_type": "fixed_amount",
    "value": "-5.0",
    "customer_selection": "prerequisite",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2017-01-19T12:59:10-05:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:31:39-04:00",
    "updated_at": "2020-09-11T11:31:39-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [
      789629109
    ],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "5OFFCUSTOMERGROUP",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341483"
  }
}

Create a Buy X Get Y price rule that gives one free ipod touch if customer buys 2 ipods 

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "Buy2iPodsGetiPodTouchForFree",
    "value_type": "percentage",
    "value": "-100.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "entitled",
    "allocation_method": "each",
    "starts_at": "2018-03-22T00:00:00-00:00",
    "prerequisite_collection_ids": [
      841564295
    ],
    "entitled_product_ids": [
      921728736
    ],
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": 2,
      "entitled_quantity": 1
    },
    "allocation_limit": 3
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341484,
    "value_type": "percentage",
    "value": "-100.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "entitled",
    "allocation_method": "each",
    "allocation_limit": 3,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2018-03-21T20:00:00-04:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:31:47-04:00",
    "updated_at": "2020-09-11T11:31:47-04:00",
    "entitled_product_ids": [
      921728736
    ],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [
      841564295
    ],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": 2,
      "entitled_quantity": 1
    },
    "title": "Buy2iPodsGetiPodTouchForFree",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341484"
  }
}

Create a price rule that gives the buyer $10.00 off an order

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "SUMMERSALE10OFF",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "value_type": "fixed_amount",
    "value": "-10.0",
    "customer_selection": "all",
    "starts_at": "2017-01-19T17:59:10Z"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341485,
    "value_type": "fixed_amount",
    "value": "-10.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2017-01-19T12:59:10-05:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:31:57-04:00",
    "updated_at": "2020-09-11T11:31:57-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "SUMMERSALE10OFF",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341485"
  }
}

Create a price rule that gives the buyer 15% off a specific collection

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "15OFFCOLLECTION",
    "target_type": "line_item",
    "target_selection": "entitled",
    "allocation_method": "across",
    "value_type": "percentage",
    "value": "-15.0",
    "customer_selection": "all",
    "entitled_collection_ids": [
      841564295
    ],
    "starts_at": "2017-01-19T17:59:10Z"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341486,
    "value_type": "percentage",
    "value": "-15.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "entitled",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2017-01-19T12:59:10-05:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:31:59-04:00",
    "updated_at": "2020-09-11T11:31:59-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [
      841564295
    ],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "15OFFCOLLECTION",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341486"
  }
}

Create a price rule that gives the buyer free shipping on orders over $50.00 that can be used up to 20 times

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "FREESHIPPING",
    "target_type": "shipping_line",
    "target_selection": "all",
    "allocation_method": "each",
    "value_type": "percentage",
    "value": "-100.0",
    "usage_limit": 20,
    "customer_selection": "all",
    "prerequisite_subtotal_range": {
      "greater_than_or_equal_to": "50.0"
    },
    "starts_at": "2017-01-19T17:59:10Z"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341487,
    "value_type": "percentage",
    "value": "-100.0",
    "customer_selection": "all",
    "target_type": "shipping_line",
    "target_selection": "all",
    "allocation_method": "each",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": 20,
    "starts_at": "2017-01-19T12:59:10-05:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:32:02-04:00",
    "updated_at": "2020-09-11T11:32:02-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": {
      "greater_than_or_equal_to": "50.0"
    },
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "FREESHIPPING",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341487"
  }
}
PUT /admin/api/2019-10/price_rules/{price_rule_id}.json
Updates an existing a price rule

Update the title of a price rule

PUT /admin/api/2020-07/price_rules/507328175.json
{
  "price_rule": {
    "id": 507328175,
    "title": "WINTER SALE"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "price_rule": {
    "id": 507328175,
    "value_type": "fixed_amount",
    "value": "-10.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2020-09-05T11:31:00-04:00",
    "ends_at": "2020-09-17T11:31:00-04:00",
    "created_at": "2020-09-11T11:31:00-04:00",
    "updated_at": "2020-09-11T11:31:49-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "WINTER SALE",
    "admin_graphql_api_id": "gid://shopify/PriceRule/507328175"
  }
}
GET /admin/api/2019-10/price_rules.json
Retrieves a list of price rules. Note: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

The maximum number of results to retrieve.

(default: 50, maximum: 250)
since_id

Restrict results to after the specified ID.
created_at_min

Show price rules created after date (format 2017-03-25T16:15:47-04:00).
created_at_max

Show price rules created before date (format 2017-03-25T16:15:47-04:00).
updated_at_min

Show price rules last updated after date (format 2017-03-25T16:15:47-04:00).
updated_at_max

Show price rules last updated before date (format 2017-03-25T16:15:47-04:00).
starts_at_min

Show price rules starting after date (format 2017-03-25T16:15:47-04:00).
starts_at_max

Show price rules starting before date (format 2017-03-25T16:15:47-04:00).
ends_at_min

Show price rules ending after date (format 2017-03-25T16:15:47-04:00).
ends_at_max

Show price rules ending before date (format 2017-03-25T16:15:47-04:00).
times_used

Show price rules with times used.

Retrieve all price rules

GET /admin/api/2020-07/price_rules.json
View Response 
HTTP/1.1 200 OK
{
  "price_rules": [
    {
      "id": 507328175,
      "value_type": "fixed_amount",
      "value": "-10.0",
      "customer_selection": "all",
      "target_type": "line_item",
      "target_selection": "all",
      "allocation_method": "across",
      "allocation_limit": null,
      "once_per_customer": false,
      "usage_limit": null,
      "starts_at": "2020-09-05T11:31:00-04:00",
      "ends_at": "2020-09-17T11:31:00-04:00",
      "created_at": "2020-09-11T11:31:00-04:00",
      "updated_at": "2020-09-11T11:31:00-04:00",
      "entitled_product_ids": [],
      "entitled_variant_ids": [],
      "entitled_collection_ids": [],
      "entitled_country_ids": [],
      "prerequisite_product_ids": [],
      "prerequisite_variant_ids": [],
      "prerequisite_collection_ids": [],
      "prerequisite_saved_search_ids": [],
      "prerequisite_customer_ids": [],
      "prerequisite_subtotal_range": null,
      "prerequisite_quantity_range": null,
      "prerequisite_shipping_price_range": null,
      "prerequisite_to_entitlement_quantity_ratio": {
        "prerequisite_quantity": null,
        "entitled_quantity": null
      },
      "title": "SUMMERSALE10OFF",
      "admin_graphql_api_id": "gid://shopify/PriceRule/507328175"
    },
    {
      "id": 106886544,
      "value_type": "fixed_amount",
      "value": "-10.0",
      "customer_selection": "all",
      "target_type": "line_item",
      "target_selection": "all",
      "allocation_method": "across",
      "allocation_limit": null,
      "once_per_customer": false,
      "usage_limit": null,
      "starts_at": "2020-09-09T11:31:00-04:00",
      "ends_at": "2020-09-13T11:31:00-04:00",
      "created_at": "2020-09-11T11:31:00-04:00",
      "updated_at": "2020-09-11T11:31:00-04:00",
      "entitled_product_ids": [],
      "entitled_variant_ids": [],
      "entitled_collection_ids": [],
      "entitled_country_ids": [],
      "prerequisite_product_ids": [],
      "prerequisite_variant_ids": [],
      "prerequisite_collection_ids": [],
      "prerequisite_saved_search_ids": [],
      "prerequisite_customer_ids": [],
      "prerequisite_subtotal_range": null,
      "prerequisite_quantity_range": null,
      "prerequisite_shipping_price_range": null,
      "prerequisite_to_entitlement_quantity_ratio": {
        "prerequisite_quantity": null,
        "entitled_quantity": null
      },
      "title": "TENOFF",
      "admin_graphql_api_id": "gid://shopify/PriceRule/106886544"
    }
  ]
}
GET /admin/api/2019-10/price_rules/{price_rule_id}.json
Retrieves a single price rule

Retrieve a single price rule by its ID

GET /admin/api/2020-07/price_rules/507328175.json
View Response 
HTTP/1.1 200 OK
{
  "price_rule": {
    "id": 507328175,
    "value_type": "fixed_amount",
    "value": "-10.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2020-09-05T11:31:00-04:00",
    "ends_at": "2020-09-17T11:31:00-04:00",
    "created_at": "2020-09-11T11:31:00-04:00",
    "updated_at": "2020-09-11T11:31:00-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "SUMMERSALE10OFF",
    "admin_graphql_api_id": "gid://shopify/PriceRule/507328175"
  }
}
GET /admin/api/2019-10/price_rules/count.json
Retrieves a count of all price rules.

Retrieve a count of all price rules

GET /admin/api/2020-07/price_rules/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 2
}
DELETE /admin/api/2019-10/price_rules/{price_rule_id}.json
Deletes a price rule

Delete a price rule

DELETE /admin/api/2020-07/price_rules/507328175.json
View Response 
HTTP/1.1 204 No Content
Version 2020-01

You can use the PriceRule resource to create discounts using conditions. You can then associate the conditions with a discount code by using the DiscountCode resource. Merchants can distribute the discount codes to their customers.

Using the PriceRule resource, you can create discounts that specify a discount as a percentage, a fixed amount, or free shipping. You use entitlements and prerequisites to dynamically build these discounts.

To learn about how to associate a price rule with a discount code, see the DiscountCode resource.

Create a price rule

You can create price rules with entitlements and prerequisites. Entitlements describe the designated resources that a discount applies to, such as specific products, variants, or collections. Prerequisites describe the requirements that must be met in order for the discount to apply to the entitled resources. For example, you might want a discount to apply only to a certain shipping price range, or a certain subtotal range.

You can use entitlements, prereqisites, and other conditions to create discounts, such as the following examples:

  • $10 off the buyer's order if the total exceeds $40
  • 15% off certain collections
  • free shipping on orders over $100.00 for Canadian buyers, redeemable up to 20 times

For examples of how to create price rules, see the POST method.

What you can do with PriceRule

The Shopify API lets you do the following with the PriceRule resource. More detailed versions of these general actions may be available:

PriceRule properties

allocation_method 
"allocation_method": "each"

The allocation method of the price rule. Valid values:

  • each: The discount is applied to each of the entitled items. For example, for a price rule that takes $15 off, each entitled line item in a checkout will be discounted by $15.
  • across: The calculated discount amount will be applied across the entitled items. For example, for a price rule that takes $15 off, the discount will be applied across all the entitled items.

When the value of target_type is shipping_line, then this value must be each.
created_at
read-only 
"created_at": "2017-03-13T16:09:54-04:00"

The date and time (ISO 8601 format) when the price rule was created.
updated_at
read-only 
"updated_at": "2017-03-14T16:09:54-04:00"

The date and time (ISO 8601 format) when the price rule was updated.
customer_selection 
"customer_selection": "prerequisite"

The customer selection for the price rule. Valid values:

  • all: The price rule is valid for all customers.
  • prerequisite: The customer must either belong to one of the customer saved searches specified by prerequisite_saved_search_ids, or be one of the customers specified by prerequisite_customer_ids.
ends_at 
"ends_at": "2017-04-19T17:59:10Z"

The date and time (ISO 8601 format) when the price rule ends. Must be after starts_at.
entitled_collection_ids 
"entitled_collection_ids": [
  4564654869,
  8979761006
]

A list of IDs of collections whose products will be eligible to the discount. It can be used only with target_type set to line_item and target_selection set to entitled. It can't be used in combination with entitled_product_ids or entitled_variant_ids.
entitled_country_ids 
" entitled_country_ids": [
  7897987023,
  3569053679
]

A list of IDs of shipping countries that will be entitled to the discount. It can be used only with target_type set to shipping_line and target_selection set to entitled.
entitled_product_ids 
"entitled_product_ids": [
  7897397755,
  42382368242
]

A list of IDs of products that will be entitled to the discount. It can be used only with target_type set to line_item and target_selection set to entitled.

If a product variant is included in entitled_variant_ids, then entitled_product_ids can't include the ID of the product associated with that variant.
entitled_variant_ids 
"entitled_variant_ids": [
  6798798798,
  5675765905
]

A list of IDs of product variants that will be entitled to the discount. It can be used only with target_type set to line_item and target_selection set to entitled.

If a product is included in entitled_product_ids, then entitled_variant_ids can't include the ID of any variants associated with that product.
id
read-only 
"id": 9808080986

The ID for the price rule.
once_per_customer 
"once_per_customer": true

Whether the generated discount code will be valid only for a single use per customer. This is tracked using customer ID.
prerequisite_customer_ids 
"prerequisite_customer_ids": [
  384028349005,
  3492039843
]

A list of customer IDs. For the price rule to be applicable, the customer must match one of the specified customers.

If prerequisite_customer_ids is populated, then prerequisite_saved_search_ids must be empty.
prerequisite_quantity_range 
"prerequisite_quantity_range": {
  "greater_than_or_equal_to": 2
}

The minimum number of items for the price rule to be applicable. It has the following property:

  • greater_than_or_equal_to: The quantity of an entitled cart item must be greater than or equal to this value.
prerequisite_saved_search_ids 
"prerequisite_saved_search_ids": [
  1123452345,
  43535363636
]

A list of customer saved search IDs. For the price rule to be applicable, the customer must be in the group of customers matching a customer saved search.

If prerequisite_saved_search_ids is populated, then prerequisite_customer_ids must be empty.
prerequisite_shipping_price_range 
"prerequisite_shipping_price_range": {
  "less_than_or_equal_to": "10.0"
}

The maximum shipping price for the price rule to be applicable. It has the following property:

  • less_than_or_equal_to: The shipping price must be less than or equal to this value.
prerequisite_subtotal_range 
"prerequisite_subtotal_range": {
  "greater_than_or_equal_to": "40.0"
}

The minimum subtotal for the price rule to be applicable. It has the following property:

  • greater_than_or_equal_to: The subtotal of the entitled cart items must be greater than or equal to this value for the discount to apply.
starts_at 
"starts_at": "2017-01-19T17:59:10Z"

The date and time (ISO 8601 format) when the price rule starts.

target_selection 
"target_selection": "entitled"

The target selection method of the price rule. Valid values:

  • all: The price rule applies the discount to all line items in the checkout.
  • entitled: The price rule applies the discount to selected entitlements only.
target_type 
"target_type": "line_item"

The target type that the price rule applies to. Valid values:

  • line_item: The price rule applies to the cart's line items.
  • shipping_line: The price rule applies to the cart's shipping lines.
title 
"title": "SUMMERSALE10OFF"

The title of the price rule. This is used by the Shopify admin search to retrieve discounts. It is also displayed on the Discounts page of the Shopify admin for bulk discounts.

For non-bulk discounts, the discount code is displayed on the admin.

For a consistent search experience, use the same value for title as the code property of the associated discount code.
usage_limit 
"usage_limit": 10

The maximum number of times the price rule can be used, per discount code.
prerequisite_product_ids 
"prerequisite_product_ids": [
  7897397755,
  42382368242
]

List of product ids that will be a prerequisites for a Buy X Get Y type discount. The prerequisite_product_ids can be used only with:

  • target_type set to line_item,
  • target_selection set to entitled,
  • allocation_method set to each and
  • prerequisite_to_entitlement_quantity_ratio defined.

Caution

If a product variant is included in prerequisite_variant_ids, then prerequisite_product_ids can't include the ID of the product associated with that variant.
prerequisite_variant_ids 
"prerequisite_variant_ids": [
  6798798798,
  5675765905
]

List of variant ids that will be a prerequisites for a Buy X Get Y type discount. The entitled_variant_ids can be used only with:

  • target_type set to line_item,
  • target_selection set to entitled,
  • allocation_method set to each and
  • prerequisite_to_entitlement_quantity_ratio defined.

Caution

If a product is included in prerequisite_product_ids, then prerequisite_variant_ids can't include the ID of any variants associated with that product.
prerequisite_collection_ids 
"prerequisite_collection_ids": [
  4564654869,
  8979761006
]

List of collection ids that will be a prerequisites for a Buy X Get Y discount. The entitled_collection_ids can be used only with:

  • target_type set to line_item,
  • target_selection set to entitled,
  • allocation_method set to each and
  • prerequisite_to_entitlement_quantity_ratio defined.
Cannot be used in combination with prerequisite_product_ids or prerequisite_variant_ids.
value 
"value": -35

The value of the price rule. If if the value of target_type is shipping_line, then only -100 is accepted. The value must be negative.
value_type 
"value_type": "fixed_amount"

The value type of the price rule. Valid values:

  • fixed_amount: Applies a discount of value as a unit of the store's currency. For example, if value is -30 and the store's currency is USD, then $30 USD is deducted when the discount is applied.
  • percentage: Applies a percentage discount of value. For example, if value is -30, then 30% will be deducted when the discount is applied.

If target_type is shipping_line, then only percentage is accepted.
prerequisite_to_entitlement_quantity_ratio 
"prerequisite_to_entitlement_quantity_ratio": {
  "prerequisite_quantity": 2,
  "entitled_quantity": 1
}

Buy/Get ratio for a Buy X Get Y discount. prerequisite_quantity defines the necessary 'buy' quantity and entitled_quantity the offered 'get' quantity.

The prerequisite_to_entitlement_quantity_ratio can be used only with:

  • value_type set to percentage,
  • target_type set to line_item,
  • target_selection set to entitled,
  • allocation_method set to each,
  • prerequisite_product_ids or prerequisite_variant_ids or prerequisite_collection_ids defined and
  • entitled_product_ids or entitled_variant_ids or entitled_collection_ids defined.

Caution

Cannot be used in combination with prerequisite_subtotal_range, prerequisite_quantity_range or prerequisite_shipping_price_range.
allocation_limit 
"allocation_limit": 3

The number of times the discount can be allocated on the cart - if eligible. For example a Buy 1 hat Get 1 hat for free discount can be applied 3 times on a cart having more than 6 hats, where maximum of 3 hats get discounted - if the allocation_limit is 3. Empty (null) allocation_limit means unlimited number of allocations.

Caution

allocation_limit is only working with Buy X Get Y discount. The default value on creation will be null (unlimited).

Endpoints

POST /admin/api/2020-01/price_rules.json
Creates a price rule

Create a price rule that gives a select group of customers $5 off their order

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "5OFFCUSTOMERGROUP",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "value_type": "fixed_amount",
    "value": "-5.0",
    "customer_selection": "prerequisite",
    "prerequisite_saved_search_ids": [
      789629109
    ],
    "starts_at": "2017-01-19T17:59:10Z"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341483,
    "value_type": "fixed_amount",
    "value": "-5.0",
    "customer_selection": "prerequisite",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2017-01-19T12:59:10-05:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:31:39-04:00",
    "updated_at": "2020-09-11T11:31:39-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [
      789629109
    ],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "5OFFCUSTOMERGROUP",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341483"
  }
}

Create a Buy X Get Y price rule that gives one free ipod touch if customer buys 2 ipods 

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "Buy2iPodsGetiPodTouchForFree",
    "value_type": "percentage",
    "value": "-100.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "entitled",
    "allocation_method": "each",
    "starts_at": "2018-03-22T00:00:00-00:00",
    "prerequisite_collection_ids": [
      841564295
    ],
    "entitled_product_ids": [
      921728736
    ],
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": 2,
      "entitled_quantity": 1
    },
    "allocation_limit": 3
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341484,
    "value_type": "percentage",
    "value": "-100.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "entitled",
    "allocation_method": "each",
    "allocation_limit": 3,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2018-03-21T20:00:00-04:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:31:47-04:00",
    "updated_at": "2020-09-11T11:31:47-04:00",
    "entitled_product_ids": [
      921728736
    ],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [
      841564295
    ],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": 2,
      "entitled_quantity": 1
    },
    "title": "Buy2iPodsGetiPodTouchForFree",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341484"
  }
}

Create a price rule that gives the buyer $10.00 off an order

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "SUMMERSALE10OFF",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "value_type": "fixed_amount",
    "value": "-10.0",
    "customer_selection": "all",
    "starts_at": "2017-01-19T17:59:10Z"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341485,
    "value_type": "fixed_amount",
    "value": "-10.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2017-01-19T12:59:10-05:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:31:57-04:00",
    "updated_at": "2020-09-11T11:31:57-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "SUMMERSALE10OFF",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341485"
  }
}

Create a price rule that gives the buyer 15% off a specific collection

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "15OFFCOLLECTION",
    "target_type": "line_item",
    "target_selection": "entitled",
    "allocation_method": "across",
    "value_type": "percentage",
    "value": "-15.0",
    "customer_selection": "all",
    "entitled_collection_ids": [
      841564295
    ],
    "starts_at": "2017-01-19T17:59:10Z"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341486,
    "value_type": "percentage",
    "value": "-15.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "entitled",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2017-01-19T12:59:10-05:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:31:59-04:00",
    "updated_at": "2020-09-11T11:31:59-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [
      841564295
    ],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "15OFFCOLLECTION",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341486"
  }
}

Create a price rule that gives the buyer free shipping on orders over $50.00 that can be used up to 20 times

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "FREESHIPPING",
    "target_type": "shipping_line",
    "target_selection": "all",
    "allocation_method": "each",
    "value_type": "percentage",
    "value": "-100.0",
    "usage_limit": 20,
    "customer_selection": "all",
    "prerequisite_subtotal_range": {
      "greater_than_or_equal_to": "50.0"
    },
    "starts_at": "2017-01-19T17:59:10Z"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341487,
    "value_type": "percentage",
    "value": "-100.0",
    "customer_selection": "all",
    "target_type": "shipping_line",
    "target_selection": "all",
    "allocation_method": "each",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": 20,
    "starts_at": "2017-01-19T12:59:10-05:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:32:02-04:00",
    "updated_at": "2020-09-11T11:32:02-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": {
      "greater_than_or_equal_to": "50.0"
    },
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "FREESHIPPING",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341487"
  }
}
PUT /admin/api/2020-01/price_rules/{price_rule_id}.json
Updates an existing a price rule

Update the title of a price rule

PUT /admin/api/2020-07/price_rules/507328175.json
{
  "price_rule": {
    "id": 507328175,
    "title": "WINTER SALE"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "price_rule": {
    "id": 507328175,
    "value_type": "fixed_amount",
    "value": "-10.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2020-09-05T11:31:00-04:00",
    "ends_at": "2020-09-17T11:31:00-04:00",
    "created_at": "2020-09-11T11:31:00-04:00",
    "updated_at": "2020-09-11T11:31:49-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "WINTER SALE",
    "admin_graphql_api_id": "gid://shopify/PriceRule/507328175"
  }
}
GET /admin/api/2020-01/price_rules.json
Retrieves a list of price rules. Note: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

The maximum number of results to retrieve.

(default: 50, maximum: 250)
since_id

Restrict results to after the specified ID.
created_at_min

Show price rules created after date (format 2017-03-25T16:15:47-04:00).
created_at_max

Show price rules created before date (format 2017-03-25T16:15:47-04:00).
updated_at_min

Show price rules last updated after date (format 2017-03-25T16:15:47-04:00).
updated_at_max

Show price rules last updated before date (format 2017-03-25T16:15:47-04:00).
starts_at_min

Show price rules starting after date (format 2017-03-25T16:15:47-04:00).
starts_at_max

Show price rules starting before date (format 2017-03-25T16:15:47-04:00).
ends_at_min

Show price rules ending after date (format 2017-03-25T16:15:47-04:00).
ends_at_max

Show price rules ending before date (format 2017-03-25T16:15:47-04:00).
times_used

Show price rules with times used.

Retrieve all price rules

GET /admin/api/2020-07/price_rules.json
View Response 
HTTP/1.1 200 OK
{
  "price_rules": [
    {
      "id": 507328175,
      "value_type": "fixed_amount",
      "value": "-10.0",
      "customer_selection": "all",
      "target_type": "line_item",
      "target_selection": "all",
      "allocation_method": "across",
      "allocation_limit": null,
      "once_per_customer": false,
      "usage_limit": null,
      "starts_at": "2020-09-05T11:31:00-04:00",
      "ends_at": "2020-09-17T11:31:00-04:00",
      "created_at": "2020-09-11T11:31:00-04:00",
      "updated_at": "2020-09-11T11:31:00-04:00",
      "entitled_product_ids": [],
      "entitled_variant_ids": [],
      "entitled_collection_ids": [],
      "entitled_country_ids": [],
      "prerequisite_product_ids": [],
      "prerequisite_variant_ids": [],
      "prerequisite_collection_ids": [],
      "prerequisite_saved_search_ids": [],
      "prerequisite_customer_ids": [],
      "prerequisite_subtotal_range": null,
      "prerequisite_quantity_range": null,
      "prerequisite_shipping_price_range": null,
      "prerequisite_to_entitlement_quantity_ratio": {
        "prerequisite_quantity": null,
        "entitled_quantity": null
      },
      "title": "SUMMERSALE10OFF",
      "admin_graphql_api_id": "gid://shopify/PriceRule/507328175"
    },
    {
      "id": 106886544,
      "value_type": "fixed_amount",
      "value": "-10.0",
      "customer_selection": "all",
      "target_type": "line_item",
      "target_selection": "all",
      "allocation_method": "across",
      "allocation_limit": null,
      "once_per_customer": false,
      "usage_limit": null,
      "starts_at": "2020-09-09T11:31:00-04:00",
      "ends_at": "2020-09-13T11:31:00-04:00",
      "created_at": "2020-09-11T11:31:00-04:00",
      "updated_at": "2020-09-11T11:31:00-04:00",
      "entitled_product_ids": [],
      "entitled_variant_ids": [],
      "entitled_collection_ids": [],
      "entitled_country_ids": [],
      "prerequisite_product_ids": [],
      "prerequisite_variant_ids": [],
      "prerequisite_collection_ids": [],
      "prerequisite_saved_search_ids": [],
      "prerequisite_customer_ids": [],
      "prerequisite_subtotal_range": null,
      "prerequisite_quantity_range": null,
      "prerequisite_shipping_price_range": null,
      "prerequisite_to_entitlement_quantity_ratio": {
        "prerequisite_quantity": null,
        "entitled_quantity": null
      },
      "title": "TENOFF",
      "admin_graphql_api_id": "gid://shopify/PriceRule/106886544"
    }
  ]
}
GET /admin/api/2020-01/price_rules/{price_rule_id}.json
Retrieves a single price rule

Retrieve a single price rule by its ID

GET /admin/api/2020-07/price_rules/507328175.json
View Response 
HTTP/1.1 200 OK
{
  "price_rule": {
    "id": 507328175,
    "value_type": "fixed_amount",
    "value": "-10.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2020-09-05T11:31:00-04:00",
    "ends_at": "2020-09-17T11:31:00-04:00",
    "created_at": "2020-09-11T11:31:00-04:00",
    "updated_at": "2020-09-11T11:31:00-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "SUMMERSALE10OFF",
    "admin_graphql_api_id": "gid://shopify/PriceRule/507328175"
  }
}
GET /admin/api/2020-01/price_rules/count.json
Retrieves a count of all price rules.

Retrieve a count of all price rules

GET /admin/api/2020-07/price_rules/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 2
}
DELETE /admin/api/2020-01/price_rules/{price_rule_id}.json
Deletes a price rule

Delete a price rule

DELETE /admin/api/2020-07/price_rules/507328175.json
View Response 
HTTP/1.1 204 No Content
Version 2020-04

You can use the PriceRule resource to create discounts using conditions. You can then associate the conditions with a discount code by using the DiscountCode resource. Merchants can distribute the discount codes to their customers.

Using the PriceRule resource, you can create discounts that specify a discount as a percentage, a fixed amount, or free shipping. You use entitlements and prerequisites to dynamically build these discounts.

To learn about how to associate a price rule with a discount code, see the DiscountCode resource.

Create a price rule

You can create price rules with entitlements and prerequisites. Entitlements describe the designated resources that a discount applies to, such as specific products, variants, or collections. Prerequisites describe the requirements that must be met in order for the discount to apply to the entitled resources. For example, you might want a discount to apply only to a certain shipping price range, or a certain subtotal range.

You can use entitlements, prereqisites, and other conditions to create discounts, such as the following examples:

  • $10 off the buyer's order if the total exceeds $40
  • 15% off certain collections
  • free shipping on orders over $100.00 for Canadian buyers, redeemable up to 20 times

For examples of how to create price rules, see the POST method.

What you can do with PriceRule

The Shopify API lets you do the following with the PriceRule resource. More detailed versions of these general actions may be available:

PriceRule properties

allocation_method 
"allocation_method": "each"

The allocation method of the price rule. Valid values:

  • each: The discount is applied to each of the entitled items. For example, for a price rule that takes $15 off, each entitled line item in a checkout will be discounted by $15.
  • across: The calculated discount amount will be applied across the entitled items. For example, for a price rule that takes $15 off, the discount will be applied across all the entitled items.

When the value of target_type is shipping_line, then this value must be each.
created_at
read-only 
"created_at": "2017-03-13T16:09:54-04:00"

The date and time (ISO 8601 format) when the price rule was created.
updated_at
read-only 
"updated_at": "2017-03-14T16:09:54-04:00"

The date and time (ISO 8601 format) when the price rule was updated.
customer_selection 
"customer_selection": "prerequisite"

The customer selection for the price rule. Valid values:

  • all: The price rule is valid for all customers.
  • prerequisite: The customer must either belong to one of the customer saved searches specified by prerequisite_saved_search_ids, or be one of the customers specified by prerequisite_customer_ids.
ends_at 
"ends_at": "2017-04-19T17:59:10Z"

The date and time (ISO 8601 format) when the price rule ends. Must be after starts_at.
entitled_collection_ids 
"entitled_collection_ids": [
  4564654869,
  8979761006
]

A list of IDs of collections whose products will be eligible to the discount. It can be used only with target_type set to line_item and target_selection set to entitled. It can't be used in combination with entitled_product_ids or entitled_variant_ids.
entitled_country_ids 
" entitled_country_ids": [
  7897987023,
  3569053679
]

A list of IDs of shipping countries that will be entitled to the discount. It can be used only with target_type set to shipping_line and target_selection set to entitled.
entitled_product_ids 
"entitled_product_ids": [
  7897397755,
  42382368242
]

A list of IDs of products that will be entitled to the discount. It can be used only with target_type set to line_item and target_selection set to entitled.

If a product variant is included in entitled_variant_ids, then entitled_product_ids can't include the ID of the product associated with that variant.
entitled_variant_ids 
"entitled_variant_ids": [
  6798798798,
  5675765905
]

A list of IDs of product variants that will be entitled to the discount. It can be used only with target_type set to line_item and target_selection set to entitled.

If a product is included in entitled_product_ids, then entitled_variant_ids can't include the ID of any variants associated with that product.
id
read-only 
"id": 9808080986

The ID for the price rule.
once_per_customer 
"once_per_customer": true

Whether the generated discount code will be valid only for a single use per customer. This is tracked using customer ID.
prerequisite_customer_ids 
"prerequisite_customer_ids": [
  384028349005,
  3492039843
]

A list of customer IDs. For the price rule to be applicable, the customer must match one of the specified customers.

If prerequisite_customer_ids is populated, then prerequisite_saved_search_ids must be empty.
prerequisite_quantity_range 
"prerequisite_quantity_range": {
  "greater_than_or_equal_to": 2
}

The minimum number of items for the price rule to be applicable. It has the following property:

  • greater_than_or_equal_to: The quantity of an entitled cart item must be greater than or equal to this value.
prerequisite_saved_search_ids 
"prerequisite_saved_search_ids": [
  1123452345,
  43535363636
]

A list of customer saved search IDs. For the price rule to be applicable, the customer must be in the group of customers matching a customer saved search.

If prerequisite_saved_search_ids is populated, then prerequisite_customer_ids must be empty.
prerequisite_shipping_price_range 
"prerequisite_shipping_price_range": {
  "less_than_or_equal_to": "10.0"
}

The maximum shipping price for the price rule to be applicable. It has the following property:

  • less_than_or_equal_to: The shipping price must be less than or equal to this value.
prerequisite_subtotal_range 
"prerequisite_subtotal_range": {
  "greater_than_or_equal_to": "40.0"
}

The minimum subtotal for the price rule to be applicable. It has the following property:

  • greater_than_or_equal_to: The subtotal of the entitled cart items must be greater than or equal to this value for the discount to apply.
starts_at 
"starts_at": "2017-01-19T17:59:10Z"

The date and time (ISO 8601 format) when the price rule starts.

target_selection 
"target_selection": "entitled"

The target selection method of the price rule. Valid values:

  • all: The price rule applies the discount to all line items in the checkout.
  • entitled: The price rule applies the discount to selected entitlements only.
target_type 
"target_type": "line_item"

The target type that the price rule applies to. Valid values:

  • line_item: The price rule applies to the cart's line items.
  • shipping_line: The price rule applies to the cart's shipping lines.
title 
"title": "SUMMERSALE10OFF"

The title of the price rule. This is used by the Shopify admin search to retrieve discounts. It is also displayed on the Discounts page of the Shopify admin for bulk discounts.

For non-bulk discounts, the discount code is displayed on the admin.

For a consistent search experience, use the same value for title as the code property of the associated discount code.
usage_limit 
"usage_limit": 10

The maximum number of times the price rule can be used, per discount code.
prerequisite_product_ids 
"prerequisite_product_ids": [
  7897397755,
  42382368242
]

List of product ids that will be a prerequisites for a Buy X Get Y type discount. The prerequisite_product_ids can be used only with:

  • target_type set to line_item,
  • target_selection set to entitled,
  • allocation_method set to each and
  • prerequisite_to_entitlement_quantity_ratio defined.

Caution

If a product variant is included in prerequisite_variant_ids, then prerequisite_product_ids can't include the ID of the product associated with that variant.
prerequisite_variant_ids 
"prerequisite_variant_ids": [
  6798798798,
  5675765905
]

List of variant ids that will be a prerequisites for a Buy X Get Y type discount. The entitled_variant_ids can be used only with:

  • target_type set to line_item,
  • target_selection set to entitled,
  • allocation_method set to each and
  • prerequisite_to_entitlement_quantity_ratio defined.

Caution

If a product is included in prerequisite_product_ids, then prerequisite_variant_ids can't include the ID of any variants associated with that product.
prerequisite_collection_ids 
"prerequisite_collection_ids": [
  4564654869,
  8979761006
]

List of collection ids that will be a prerequisites for a Buy X Get Y discount. The entitled_collection_ids can be used only with:

  • target_type set to line_item,
  • target_selection set to entitled,
  • allocation_method set to each and
  • prerequisite_to_entitlement_quantity_ratio defined.
Cannot be used in combination with prerequisite_product_ids or prerequisite_variant_ids.
value 
"value": -35

The value of the price rule. If if the value of target_type is shipping_line, then only -100 is accepted. The value must be negative.
value_type 
"value_type": "fixed_amount"

The value type of the price rule. Valid values:

  • fixed_amount: Applies a discount of value as a unit of the store's currency. For example, if value is -30 and the store's currency is USD, then $30 USD is deducted when the discount is applied.
  • percentage: Applies a percentage discount of value. For example, if value is -30, then 30% will be deducted when the discount is applied.

If target_type is shipping_line, then only percentage is accepted.
prerequisite_to_entitlement_quantity_ratio 
"prerequisite_to_entitlement_quantity_ratio": {
  "prerequisite_quantity": 2,
  "entitled_quantity": 1
}

Buy/Get ratio for a Buy X Get Y discount. prerequisite_quantity defines the necessary 'buy' quantity and entitled_quantity the offered 'get' quantity.

The prerequisite_to_entitlement_quantity_ratio can be used only with:

  • value_type set to percentage,
  • target_type set to line_item,
  • target_selection set to entitled,
  • allocation_method set to each,
  • prerequisite_product_ids or prerequisite_variant_ids or prerequisite_collection_ids defined and
  • entitled_product_ids or entitled_variant_ids or entitled_collection_ids defined.

Caution

Cannot be used in combination with prerequisite_subtotal_range, prerequisite_quantity_range or prerequisite_shipping_price_range.
allocation_limit 
"allocation_limit": 3

The number of times the discount can be allocated on the cart - if eligible. For example a Buy 1 hat Get 1 hat for free discount can be applied 3 times on a cart having more than 6 hats, where maximum of 3 hats get discounted - if the allocation_limit is 3. Empty (null) allocation_limit means unlimited number of allocations.

Caution

allocation_limit is only working with Buy X Get Y discount. The default value on creation will be null (unlimited).

Endpoints

POST /admin/api/2020-04/price_rules.json
Creates a price rule

Create a price rule that gives a select group of customers $5 off their order

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "5OFFCUSTOMERGROUP",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "value_type": "fixed_amount",
    "value": "-5.0",
    "customer_selection": "prerequisite",
    "prerequisite_saved_search_ids": [
      789629109
    ],
    "starts_at": "2017-01-19T17:59:10Z"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341483,
    "value_type": "fixed_amount",
    "value": "-5.0",
    "customer_selection": "prerequisite",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2017-01-19T12:59:10-05:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:31:39-04:00",
    "updated_at": "2020-09-11T11:31:39-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [
      789629109
    ],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "5OFFCUSTOMERGROUP",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341483"
  }
}

Create a Buy X Get Y price rule that gives one free ipod touch if customer buys 2 ipods 

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "Buy2iPodsGetiPodTouchForFree",
    "value_type": "percentage",
    "value": "-100.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "entitled",
    "allocation_method": "each",
    "starts_at": "2018-03-22T00:00:00-00:00",
    "prerequisite_collection_ids": [
      841564295
    ],
    "entitled_product_ids": [
      921728736
    ],
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": 2,
      "entitled_quantity": 1
    },
    "allocation_limit": 3
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341484,
    "value_type": "percentage",
    "value": "-100.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "entitled",
    "allocation_method": "each",
    "allocation_limit": 3,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2018-03-21T20:00:00-04:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:31:47-04:00",
    "updated_at": "2020-09-11T11:31:47-04:00",
    "entitled_product_ids": [
      921728736
    ],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [
      841564295
    ],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": 2,
      "entitled_quantity": 1
    },
    "title": "Buy2iPodsGetiPodTouchForFree",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341484"
  }
}

Create a price rule that gives the buyer $10.00 off an order

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "SUMMERSALE10OFF",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "value_type": "fixed_amount",
    "value": "-10.0",
    "customer_selection": "all",
    "starts_at": "2017-01-19T17:59:10Z"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341485,
    "value_type": "fixed_amount",
    "value": "-10.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2017-01-19T12:59:10-05:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:31:57-04:00",
    "updated_at": "2020-09-11T11:31:57-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "SUMMERSALE10OFF",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341485"
  }
}

Create a price rule that gives the buyer 15% off a specific collection

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "15OFFCOLLECTION",
    "target_type": "line_item",
    "target_selection": "entitled",
    "allocation_method": "across",
    "value_type": "percentage",
    "value": "-15.0",
    "customer_selection": "all",
    "entitled_collection_ids": [
      841564295
    ],
    "starts_at": "2017-01-19T17:59:10Z"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341486,
    "value_type": "percentage",
    "value": "-15.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "entitled",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2017-01-19T12:59:10-05:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:31:59-04:00",
    "updated_at": "2020-09-11T11:31:59-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [
      841564295
    ],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "15OFFCOLLECTION",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341486"
  }
}

Create a price rule that gives the buyer free shipping on orders over $50.00 that can be used up to 20 times

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "FREESHIPPING",
    "target_type": "shipping_line",
    "target_selection": "all",
    "allocation_method": "each",
    "value_type": "percentage",
    "value": "-100.0",
    "usage_limit": 20,
    "customer_selection": "all",
    "prerequisite_subtotal_range": {
      "greater_than_or_equal_to": "50.0"
    },
    "starts_at": "2017-01-19T17:59:10Z"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341487,
    "value_type": "percentage",
    "value": "-100.0",
    "customer_selection": "all",
    "target_type": "shipping_line",
    "target_selection": "all",
    "allocation_method": "each",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": 20,
    "starts_at": "2017-01-19T12:59:10-05:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:32:02-04:00",
    "updated_at": "2020-09-11T11:32:02-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": {
      "greater_than_or_equal_to": "50.0"
    },
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "FREESHIPPING",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341487"
  }
}
PUT /admin/api/2020-04/price_rules/{price_rule_id}.json
Updates an existing a price rule

Update the title of a price rule

PUT /admin/api/2020-07/price_rules/507328175.json
{
  "price_rule": {
    "id": 507328175,
    "title": "WINTER SALE"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "price_rule": {
    "id": 507328175,
    "value_type": "fixed_amount",
    "value": "-10.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2020-09-05T11:31:00-04:00",
    "ends_at": "2020-09-17T11:31:00-04:00",
    "created_at": "2020-09-11T11:31:00-04:00",
    "updated_at": "2020-09-11T11:31:49-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "WINTER SALE",
    "admin_graphql_api_id": "gid://shopify/PriceRule/507328175"
  }
}
GET /admin/api/2020-04/price_rules.json
Retrieves a list of price rules. Note: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

The maximum number of results to retrieve.

(default: 50, maximum: 250)
since_id

Restrict results to after the specified ID.
created_at_min

Show price rules created after date (format 2017-03-25T16:15:47-04:00).
created_at_max

Show price rules created before date (format 2017-03-25T16:15:47-04:00).
updated_at_min

Show price rules last updated after date (format 2017-03-25T16:15:47-04:00).
updated_at_max

Show price rules last updated before date (format 2017-03-25T16:15:47-04:00).
starts_at_min

Show price rules starting after date (format 2017-03-25T16:15:47-04:00).
starts_at_max

Show price rules starting before date (format 2017-03-25T16:15:47-04:00).
ends_at_min

Show price rules ending after date (format 2017-03-25T16:15:47-04:00).
ends_at_max

Show price rules ending before date (format 2017-03-25T16:15:47-04:00).
times_used

Show price rules with times used.

Retrieve all price rules

GET /admin/api/2020-07/price_rules.json
View Response 
HTTP/1.1 200 OK
{
  "price_rules": [
    {
      "id": 507328175,
      "value_type": "fixed_amount",
      "value": "-10.0",
      "customer_selection": "all",
      "target_type": "line_item",
      "target_selection": "all",
      "allocation_method": "across",
      "allocation_limit": null,
      "once_per_customer": false,
      "usage_limit": null,
      "starts_at": "2020-09-05T11:31:00-04:00",
      "ends_at": "2020-09-17T11:31:00-04:00",
      "created_at": "2020-09-11T11:31:00-04:00",
      "updated_at": "2020-09-11T11:31:00-04:00",
      "entitled_product_ids": [],
      "entitled_variant_ids": [],
      "entitled_collection_ids": [],
      "entitled_country_ids": [],
      "prerequisite_product_ids": [],
      "prerequisite_variant_ids": [],
      "prerequisite_collection_ids": [],
      "prerequisite_saved_search_ids": [],
      "prerequisite_customer_ids": [],
      "prerequisite_subtotal_range": null,
      "prerequisite_quantity_range": null,
      "prerequisite_shipping_price_range": null,
      "prerequisite_to_entitlement_quantity_ratio": {
        "prerequisite_quantity": null,
        "entitled_quantity": null
      },
      "title": "SUMMERSALE10OFF",
      "admin_graphql_api_id": "gid://shopify/PriceRule/507328175"
    },
    {
      "id": 106886544,
      "value_type": "fixed_amount",
      "value": "-10.0",
      "customer_selection": "all",
      "target_type": "line_item",
      "target_selection": "all",
      "allocation_method": "across",
      "allocation_limit": null,
      "once_per_customer": false,
      "usage_limit": null,
      "starts_at": "2020-09-09T11:31:00-04:00",
      "ends_at": "2020-09-13T11:31:00-04:00",
      "created_at": "2020-09-11T11:31:00-04:00",
      "updated_at": "2020-09-11T11:31:00-04:00",
      "entitled_product_ids": [],
      "entitled_variant_ids": [],
      "entitled_collection_ids": [],
      "entitled_country_ids": [],
      "prerequisite_product_ids": [],
      "prerequisite_variant_ids": [],
      "prerequisite_collection_ids": [],
      "prerequisite_saved_search_ids": [],
      "prerequisite_customer_ids": [],
      "prerequisite_subtotal_range": null,
      "prerequisite_quantity_range": null,
      "prerequisite_shipping_price_range": null,
      "prerequisite_to_entitlement_quantity_ratio": {
        "prerequisite_quantity": null,
        "entitled_quantity": null
      },
      "title": "TENOFF",
      "admin_graphql_api_id": "gid://shopify/PriceRule/106886544"
    }
  ]
}
GET /admin/api/2020-04/price_rules/{price_rule_id}.json
Retrieves a single price rule

Retrieve a single price rule by its ID

GET /admin/api/2020-07/price_rules/507328175.json
View Response 
HTTP/1.1 200 OK
{
  "price_rule": {
    "id": 507328175,
    "value_type": "fixed_amount",
    "value": "-10.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2020-09-05T11:31:00-04:00",
    "ends_at": "2020-09-17T11:31:00-04:00",
    "created_at": "2020-09-11T11:31:00-04:00",
    "updated_at": "2020-09-11T11:31:00-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "SUMMERSALE10OFF",
    "admin_graphql_api_id": "gid://shopify/PriceRule/507328175"
  }
}
GET /admin/api/2020-04/price_rules/count.json
Retrieves a count of all price rules.

Retrieve a count of all price rules

GET /admin/api/2020-07/price_rules/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 2
}
DELETE /admin/api/2020-04/price_rules/{price_rule_id}.json
Deletes a price rule

Delete a price rule

DELETE /admin/api/2020-07/price_rules/507328175.json
View Response 
HTTP/1.1 204 No Content
Version 2020-07 (Latest)

You can use the PriceRule resource to create discounts using conditions. You can then associate the conditions with a discount code by using the DiscountCode resource. Merchants can distribute the discount codes to their customers.

Using the PriceRule resource, you can create discounts that specify a discount as a percentage, a fixed amount, or free shipping. You use entitlements and prerequisites to dynamically build these discounts.

To learn about how to associate a price rule with a discount code, see the DiscountCode resource.

Create a price rule

You can create price rules with entitlements and prerequisites. Entitlements describe the designated resources that a discount applies to, such as specific products, variants, or collections. Prerequisites describe the requirements that must be met in order for the discount to apply to the entitled resources. For example, you might want a discount to apply only to a certain shipping price range, or a certain subtotal range.

You can use entitlements, prereqisites, and other conditions to create discounts, such as the following examples:

  • $10 off the buyer's order if the total exceeds $40
  • 15% off certain collections
  • free shipping on orders over $100.00 for Canadian buyers, redeemable up to 20 times

For examples of how to create price rules, see the POST method.

What you can do with PriceRule

The Shopify API lets you do the following with the PriceRule resource. More detailed versions of these general actions may be available:

PriceRule properties

allocation_method 
"allocation_method": "each"

The allocation method of the price rule. Valid values:

  • each: The discount is applied to each of the entitled items. For example, for a price rule that takes $15 off, each entitled line item in a checkout will be discounted by $15.
  • across: The calculated discount amount will be applied across the entitled items. For example, for a price rule that takes $15 off, the discount will be applied across all the entitled items.

When the value of target_type is shipping_line, then this value must be each.
created_at
read-only 
"created_at": "2017-03-13T16:09:54-04:00"

The date and time (ISO 8601 format) when the price rule was created.
updated_at
read-only 
"updated_at": "2017-03-14T16:09:54-04:00"

The date and time (ISO 8601 format) when the price rule was updated.
customer_selection 
"customer_selection": "prerequisite"

The customer selection for the price rule. Valid values:

  • all: The price rule is valid for all customers.
  • prerequisite: The customer must either belong to one of the customer saved searches specified by prerequisite_saved_search_ids, or be one of the customers specified by prerequisite_customer_ids.
ends_at 
"ends_at": "2017-04-19T17:59:10Z"

The date and time (ISO 8601 format) when the price rule ends. Must be after starts_at.
entitled_collection_ids 
"entitled_collection_ids": [
  4564654869,
  8979761006
]

A list of IDs of collections whose products will be eligible to the discount. It can be used only with target_type set to line_item and target_selection set to entitled. It can't be used in combination with entitled_product_ids or entitled_variant_ids.
entitled_country_ids 
" entitled_country_ids": [
  7897987023,
  3569053679
]

A list of IDs of shipping countries that will be entitled to the discount. It can be used only with target_type set to shipping_line and target_selection set to entitled.
entitled_product_ids 
"entitled_product_ids": [
  7897397755,
  42382368242
]

A list of IDs of products that will be entitled to the discount. It can be used only with target_type set to line_item and target_selection set to entitled.

If a product variant is included in entitled_variant_ids, then entitled_product_ids can't include the ID of the product associated with that variant.
entitled_variant_ids 
"entitled_variant_ids": [
  6798798798,
  5675765905
]

A list of IDs of product variants that will be entitled to the discount. It can be used only with target_type set to line_item and target_selection set to entitled.

If a product is included in entitled_product_ids, then entitled_variant_ids can't include the ID of any variants associated with that product.
id
read-only 
"id": 9808080986

The ID for the price rule.
once_per_customer 
"once_per_customer": true

Whether the generated discount code will be valid only for a single use per customer. This is tracked using customer ID.
prerequisite_customer_ids 
"prerequisite_customer_ids": [
  384028349005,
  3492039843
]

A list of customer IDs. For the price rule to be applicable, the customer must match one of the specified customers.

If prerequisite_customer_ids is populated, then prerequisite_saved_search_ids must be empty.
prerequisite_quantity_range 
"prerequisite_quantity_range": {
  "greater_than_or_equal_to": 2
}

The minimum number of items for the price rule to be applicable. It has the following property:

  • greater_than_or_equal_to: The quantity of an entitled cart item must be greater than or equal to this value.
prerequisite_saved_search_ids 
"prerequisite_saved_search_ids": [
  1123452345,
  43535363636
]

A list of customer saved search IDs. For the price rule to be applicable, the customer must be in the group of customers matching a customer saved search.

If prerequisite_saved_search_ids is populated, then prerequisite_customer_ids must be empty.
prerequisite_shipping_price_range 
"prerequisite_shipping_price_range": {
  "less_than_or_equal_to": "10.0"
}

The maximum shipping price for the price rule to be applicable. It has the following property:

  • less_than_or_equal_to: The shipping price must be less than or equal to this value.
prerequisite_subtotal_range 
"prerequisite_subtotal_range": {
  "greater_than_or_equal_to": "40.0"
}

The minimum subtotal for the price rule to be applicable. It has the following property:

  • greater_than_or_equal_to: The subtotal of the entitled cart items must be greater than or equal to this value for the discount to apply.
starts_at 
"starts_at": "2017-01-19T17:59:10Z"

The date and time (ISO 8601 format) when the price rule starts.

target_selection 
"target_selection": "entitled"

The target selection method of the price rule. Valid values:

  • all: The price rule applies the discount to all line items in the checkout.
  • entitled: The price rule applies the discount to selected entitlements only.
target_type 
"target_type": "line_item"

The target type that the price rule applies to. Valid values:

  • line_item: The price rule applies to the cart's line items.
  • shipping_line: The price rule applies to the cart's shipping lines.
title 
"title": "SUMMERSALE10OFF"

The title of the price rule. This is used by the Shopify admin search to retrieve discounts. It is also displayed on the Discounts page of the Shopify admin for bulk discounts.

For non-bulk discounts, the discount code is displayed on the admin.

For a consistent search experience, use the same value for title as the code property of the associated discount code.
usage_limit 
"usage_limit": 10

The maximum number of times the price rule can be used, per discount code.
prerequisite_product_ids 
"prerequisite_product_ids": [
  7897397755,
  42382368242
]

List of product ids that will be a prerequisites for a Buy X Get Y type discount. The prerequisite_product_ids can be used only with:

  • target_type set to line_item,
  • target_selection set to entitled,
  • allocation_method set to each and
  • prerequisite_to_entitlement_quantity_ratio defined.

Caution

If a product variant is included in prerequisite_variant_ids, then prerequisite_product_ids can't include the ID of the product associated with that variant.
prerequisite_variant_ids 
"prerequisite_variant_ids": [
  6798798798,
  5675765905
]

List of variant ids that will be a prerequisites for a Buy X Get Y type discount. The entitled_variant_ids can be used only with:

  • target_type set to line_item,
  • target_selection set to entitled,
  • allocation_method set to each and
  • prerequisite_to_entitlement_quantity_ratio defined.

Caution

If a product is included in prerequisite_product_ids, then prerequisite_variant_ids can't include the ID of any variants associated with that product.
prerequisite_collection_ids 
"prerequisite_collection_ids": [
  4564654869,
  8979761006
]

List of collection ids that will be a prerequisites for a Buy X Get Y discount. The entitled_collection_ids can be used only with:

  • target_type set to line_item,
  • target_selection set to entitled,
  • allocation_method set to each and
  • prerequisite_to_entitlement_quantity_ratio defined.
Cannot be used in combination with prerequisite_product_ids or prerequisite_variant_ids.
value 
"value": -35

The value of the price rule. If if the value of target_type is shipping_line, then only -100 is accepted. The value must be negative.
value_type 
"value_type": "fixed_amount"

The value type of the price rule. Valid values:

  • fixed_amount: Applies a discount of value as a unit of the store's currency. For example, if value is -30 and the store's currency is USD, then $30 USD is deducted when the discount is applied.
  • percentage: Applies a percentage discount of value. For example, if value is -30, then 30% will be deducted when the discount is applied.

If target_type is shipping_line, then only percentage is accepted.
prerequisite_to_entitlement_quantity_ratio 
"prerequisite_to_entitlement_quantity_ratio": {
  "prerequisite_quantity": 2,
  "entitled_quantity": 1
}

Buy/Get ratio for a Buy X Get Y discount. prerequisite_quantity defines the necessary 'buy' quantity and entitled_quantity the offered 'get' quantity.

The prerequisite_to_entitlement_quantity_ratio can be used only with:

  • value_type set to percentage,
  • target_type set to line_item,
  • target_selection set to entitled,
  • allocation_method set to each,
  • prerequisite_product_ids or prerequisite_variant_ids or prerequisite_collection_ids defined and
  • entitled_product_ids or entitled_variant_ids or entitled_collection_ids defined.

Caution

Cannot be used in combination with prerequisite_subtotal_range, prerequisite_quantity_range or prerequisite_shipping_price_range.
allocation_limit 
"allocation_limit": 3

The number of times the discount can be allocated on the cart - if eligible. For example a Buy 1 hat Get 1 hat for free discount can be applied 3 times on a cart having more than 6 hats, where maximum of 3 hats get discounted - if the allocation_limit is 3. Empty (null) allocation_limit means unlimited number of allocations.

Caution

allocation_limit is only working with Buy X Get Y discount. The default value on creation will be null (unlimited).

Endpoints

POST /admin/api/2020-07/price_rules.json
Creates a price rule

Create a price rule that gives a select group of customers $5 off their order

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "5OFFCUSTOMERGROUP",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "value_type": "fixed_amount",
    "value": "-5.0",
    "customer_selection": "prerequisite",
    "prerequisite_saved_search_ids": [
      789629109
    ],
    "starts_at": "2017-01-19T17:59:10Z"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341483,
    "value_type": "fixed_amount",
    "value": "-5.0",
    "customer_selection": "prerequisite",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2017-01-19T12:59:10-05:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:31:39-04:00",
    "updated_at": "2020-09-11T11:31:39-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [
      789629109
    ],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "5OFFCUSTOMERGROUP",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341483"
  }
}

Create a Buy X Get Y price rule that gives one free ipod touch if customer buys 2 ipods 

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "Buy2iPodsGetiPodTouchForFree",
    "value_type": "percentage",
    "value": "-100.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "entitled",
    "allocation_method": "each",
    "starts_at": "2018-03-22T00:00:00-00:00",
    "prerequisite_collection_ids": [
      841564295
    ],
    "entitled_product_ids": [
      921728736
    ],
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": 2,
      "entitled_quantity": 1
    },
    "allocation_limit": 3
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341484,
    "value_type": "percentage",
    "value": "-100.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "entitled",
    "allocation_method": "each",
    "allocation_limit": 3,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2018-03-21T20:00:00-04:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:31:47-04:00",
    "updated_at": "2020-09-11T11:31:47-04:00",
    "entitled_product_ids": [
      921728736
    ],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [
      841564295
    ],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": 2,
      "entitled_quantity": 1
    },
    "title": "Buy2iPodsGetiPodTouchForFree",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341484"
  }
}

Create a price rule that gives the buyer $10.00 off an order

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "SUMMERSALE10OFF",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "value_type": "fixed_amount",
    "value": "-10.0",
    "customer_selection": "all",
    "starts_at": "2017-01-19T17:59:10Z"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341485,
    "value_type": "fixed_amount",
    "value": "-10.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2017-01-19T12:59:10-05:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:31:57-04:00",
    "updated_at": "2020-09-11T11:31:57-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "SUMMERSALE10OFF",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341485"
  }
}

Create a price rule that gives the buyer 15% off a specific collection

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "15OFFCOLLECTION",
    "target_type": "line_item",
    "target_selection": "entitled",
    "allocation_method": "across",
    "value_type": "percentage",
    "value": "-15.0",
    "customer_selection": "all",
    "entitled_collection_ids": [
      841564295
    ],
    "starts_at": "2017-01-19T17:59:10Z"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341486,
    "value_type": "percentage",
    "value": "-15.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "entitled",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2017-01-19T12:59:10-05:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:31:59-04:00",
    "updated_at": "2020-09-11T11:31:59-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [
      841564295
    ],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "15OFFCOLLECTION",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341486"
  }
}

Create a price rule that gives the buyer free shipping on orders over $50.00 that can be used up to 20 times

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "FREESHIPPING",
    "target_type": "shipping_line",
    "target_selection": "all",
    "allocation_method": "each",
    "value_type": "percentage",
    "value": "-100.0",
    "usage_limit": 20,
    "customer_selection": "all",
    "prerequisite_subtotal_range": {
      "greater_than_or_equal_to": "50.0"
    },
    "starts_at": "2017-01-19T17:59:10Z"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341487,
    "value_type": "percentage",
    "value": "-100.0",
    "customer_selection": "all",
    "target_type": "shipping_line",
    "target_selection": "all",
    "allocation_method": "each",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": 20,
    "starts_at": "2017-01-19T12:59:10-05:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:32:02-04:00",
    "updated_at": "2020-09-11T11:32:02-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": {
      "greater_than_or_equal_to": "50.0"
    },
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "FREESHIPPING",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341487"
  }
}
PUT /admin/api/2020-07/price_rules/{price_rule_id}.json
Updates an existing a price rule

Update the title of a price rule

PUT /admin/api/2020-07/price_rules/507328175.json
{
  "price_rule": {
    "id": 507328175,
    "title": "WINTER SALE"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "price_rule": {
    "id": 507328175,
    "value_type": "fixed_amount",
    "value": "-10.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2020-09-05T11:31:00-04:00",
    "ends_at": "2020-09-17T11:31:00-04:00",
    "created_at": "2020-09-11T11:31:00-04:00",
    "updated_at": "2020-09-11T11:31:49-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "WINTER SALE",
    "admin_graphql_api_id": "gid://shopify/PriceRule/507328175"
  }
}
GET /admin/api/2020-07/price_rules.json
Retrieves a list of price rules. Note: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

The maximum number of results to retrieve.

(default: 50, maximum: 250)
since_id

Restrict results to after the specified ID.
created_at_min

Show price rules created after date (format 2017-03-25T16:15:47-04:00).
created_at_max

Show price rules created before date (format 2017-03-25T16:15:47-04:00).
updated_at_min

Show price rules last updated after date (format 2017-03-25T16:15:47-04:00).
updated_at_max

Show price rules last updated before date (format 2017-03-25T16:15:47-04:00).
starts_at_min

Show price rules starting after date (format 2017-03-25T16:15:47-04:00).
starts_at_max

Show price rules starting before date (format 2017-03-25T16:15:47-04:00).
ends_at_min

Show price rules ending after date (format 2017-03-25T16:15:47-04:00).
ends_at_max

Show price rules ending before date (format 2017-03-25T16:15:47-04:00).
times_used

Show price rules with times used.

Retrieve all price rules

GET /admin/api/2020-07/price_rules.json
View Response 
HTTP/1.1 200 OK
{
  "price_rules": [
    {
      "id": 507328175,
      "value_type": "fixed_amount",
      "value": "-10.0",
      "customer_selection": "all",
      "target_type": "line_item",
      "target_selection": "all",
      "allocation_method": "across",
      "allocation_limit": null,
      "once_per_customer": false,
      "usage_limit": null,
      "starts_at": "2020-09-05T11:31:00-04:00",
      "ends_at": "2020-09-17T11:31:00-04:00",
      "created_at": "2020-09-11T11:31:00-04:00",
      "updated_at": "2020-09-11T11:31:00-04:00",
      "entitled_product_ids": [],
      "entitled_variant_ids": [],
      "entitled_collection_ids": [],
      "entitled_country_ids": [],
      "prerequisite_product_ids": [],
      "prerequisite_variant_ids": [],
      "prerequisite_collection_ids": [],
      "prerequisite_saved_search_ids": [],
      "prerequisite_customer_ids": [],
      "prerequisite_subtotal_range": null,
      "prerequisite_quantity_range": null,
      "prerequisite_shipping_price_range": null,
      "prerequisite_to_entitlement_quantity_ratio": {
        "prerequisite_quantity": null,
        "entitled_quantity": null
      },
      "title": "SUMMERSALE10OFF",
      "admin_graphql_api_id": "gid://shopify/PriceRule/507328175"
    },
    {
      "id": 106886544,
      "value_type": "fixed_amount",
      "value": "-10.0",
      "customer_selection": "all",
      "target_type": "line_item",
      "target_selection": "all",
      "allocation_method": "across",
      "allocation_limit": null,
      "once_per_customer": false,
      "usage_limit": null,
      "starts_at": "2020-09-09T11:31:00-04:00",
      "ends_at": "2020-09-13T11:31:00-04:00",
      "created_at": "2020-09-11T11:31:00-04:00",
      "updated_at": "2020-09-11T11:31:00-04:00",
      "entitled_product_ids": [],
      "entitled_variant_ids": [],
      "entitled_collection_ids": [],
      "entitled_country_ids": [],
      "prerequisite_product_ids": [],
      "prerequisite_variant_ids": [],
      "prerequisite_collection_ids": [],
      "prerequisite_saved_search_ids": [],
      "prerequisite_customer_ids": [],
      "prerequisite_subtotal_range": null,
      "prerequisite_quantity_range": null,
      "prerequisite_shipping_price_range": null,
      "prerequisite_to_entitlement_quantity_ratio": {
        "prerequisite_quantity": null,
        "entitled_quantity": null
      },
      "title": "TENOFF",
      "admin_graphql_api_id": "gid://shopify/PriceRule/106886544"
    }
  ]
}
GET /admin/api/2020-07/price_rules/{price_rule_id}.json
Retrieves a single price rule

Retrieve a single price rule by its ID

GET /admin/api/2020-07/price_rules/507328175.json
View Response 
HTTP/1.1 200 OK
{
  "price_rule": {
    "id": 507328175,
    "value_type": "fixed_amount",
    "value": "-10.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2020-09-05T11:31:00-04:00",
    "ends_at": "2020-09-17T11:31:00-04:00",
    "created_at": "2020-09-11T11:31:00-04:00",
    "updated_at": "2020-09-11T11:31:00-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "SUMMERSALE10OFF",
    "admin_graphql_api_id": "gid://shopify/PriceRule/507328175"
  }
}
GET /admin/api/2020-07/price_rules/count.json
Retrieves a count of all price rules.

Retrieve a count of all price rules

GET /admin/api/2020-07/price_rules/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 2
}
DELETE /admin/api/2020-07/price_rules/{price_rule_id}.json
Deletes a price rule

Delete a price rule

DELETE /admin/api/2020-07/price_rules/507328175.json
View Response 
HTTP/1.1 204 No Content
Version 2020-10 (Release candidate)

You can use the PriceRule resource to create discounts using conditions. You can then associate the conditions with a discount code by using the DiscountCode resource. Merchants can distribute the discount codes to their customers.

Using the PriceRule resource, you can create discounts that specify a discount as a percentage, a fixed amount, or free shipping. You use entitlements and prerequisites to dynamically build these discounts.

To learn about how to associate a price rule with a discount code, see the DiscountCode resource.

Create a price rule

You can create price rules with entitlements and prerequisites. Entitlements describe the designated resources that a discount applies to, such as specific products, variants, or collections. Prerequisites describe the requirements that must be met in order for the discount to apply to the entitled resources. For example, you might want a discount to apply only to a certain shipping price range, or a certain subtotal range.

You can use entitlements, prereqisites, and other conditions to create discounts, such as the following examples:

  • $10 off the buyer's order if the total exceeds $40
  • 15% off certain collections
  • free shipping on orders over $100.00 for Canadian buyers, redeemable up to 20 times

For examples of how to create price rules, see the POST method.

What you can do with PriceRule

The Shopify API lets you do the following with the PriceRule resource. More detailed versions of these general actions may be available:

PriceRule properties

allocation_method 
"allocation_method": "each"

The allocation method of the price rule. Valid values:

  • each: The discount is applied to each of the entitled items. For example, for a price rule that takes $15 off, each entitled line item in a checkout will be discounted by $15.
  • across: The calculated discount amount will be applied across the entitled items. For example, for a price rule that takes $15 off, the discount will be applied across all the entitled items.

When the value of target_type is shipping_line, then this value must be each.
created_at
read-only 
"created_at": "2017-03-13T16:09:54-04:00"

The date and time (ISO 8601 format) when the price rule was created.
updated_at
read-only 
"updated_at": "2017-03-14T16:09:54-04:00"

The date and time (ISO 8601 format) when the price rule was updated.
customer_selection 
"customer_selection": "prerequisite"

The customer selection for the price rule. Valid values:

  • all: The price rule is valid for all customers.
  • prerequisite: The customer must either belong to one of the customer saved searches specified by prerequisite_saved_search_ids, or be one of the customers specified by prerequisite_customer_ids.
ends_at 
"ends_at": "2017-04-19T17:59:10Z"

The date and time (ISO 8601 format) when the price rule ends. Must be after starts_at.
entitled_collection_ids 
"entitled_collection_ids": [
  4564654869,
  8979761006
]

A list of IDs of collections whose products will be eligible to the discount. It can be used only with target_type set to line_item and target_selection set to entitled. It can't be used in combination with entitled_product_ids or entitled_variant_ids.
entitled_country_ids 
" entitled_country_ids": [
  7897987023,
  3569053679
]

A list of IDs of shipping countries that will be entitled to the discount. It can be used only with target_type set to shipping_line and target_selection set to entitled.
entitled_product_ids 
"entitled_product_ids": [
  7897397755,
  42382368242
]

A list of IDs of products that will be entitled to the discount. It can be used only with target_type set to line_item and target_selection set to entitled.

If a product variant is included in entitled_variant_ids, then entitled_product_ids can't include the ID of the product associated with that variant.
entitled_variant_ids 
"entitled_variant_ids": [
  6798798798,
  5675765905
]

A list of IDs of product variants that will be entitled to the discount. It can be used only with target_type set to line_item and target_selection set to entitled.

If a product is included in entitled_product_ids, then entitled_variant_ids can't include the ID of any variants associated with that product.
id
read-only 
"id": 9808080986

The ID for the price rule.
once_per_customer 
"once_per_customer": true

Whether the generated discount code will be valid only for a single use per customer. This is tracked using customer ID.
prerequisite_customer_ids 
"prerequisite_customer_ids": [
  384028349005,
  3492039843
]

A list of customer IDs. For the price rule to be applicable, the customer must match one of the specified customers.

If prerequisite_customer_ids is populated, then prerequisite_saved_search_ids must be empty.
prerequisite_quantity_range 
"prerequisite_quantity_range": {
  "greater_than_or_equal_to": 2
}

The minimum number of items for the price rule to be applicable. It has the following property:

  • greater_than_or_equal_to: The quantity of an entitled cart item must be greater than or equal to this value.
prerequisite_saved_search_ids 
"prerequisite_saved_search_ids": [
  1123452345,
  43535363636
]

A list of customer saved search IDs. For the price rule to be applicable, the customer must be in the group of customers matching a customer saved search.

If prerequisite_saved_search_ids is populated, then prerequisite_customer_ids must be empty.
prerequisite_shipping_price_range 
"prerequisite_shipping_price_range": {
  "less_than_or_equal_to": "10.0"
}

The maximum shipping price for the price rule to be applicable. It has the following property:

  • less_than_or_equal_to: The shipping price must be less than or equal to this value.
prerequisite_subtotal_range 
"prerequisite_subtotal_range": {
  "greater_than_or_equal_to": "40.0"
}

The minimum subtotal for the price rule to be applicable. It has the following property:

  • greater_than_or_equal_to: The subtotal of the entitled cart items must be greater than or equal to this value for the discount to apply.
prerequisite_to_entitlement_purchase 
"prerequisite_to_entitlement_purchase": {
  "prerequisite_amount": "80.00"
}

The prerequisite purchase for a Buy X Get Y discount. It has the following property:

  • prerequisite_amount: The minimum purchase amount required to be entitled to the discount.
starts_at 
"starts_at": "2017-01-19T17:59:10Z"

The date and time (ISO 8601 format) when the price rule starts.

target_selection 
"target_selection": "entitled"

The target selection method of the price rule. Valid values:

  • all: The price rule applies the discount to all line items in the checkout.
  • entitled: The price rule applies the discount to selected entitlements only.
target_type 
"target_type": "line_item"

The target type that the price rule applies to. Valid values:

  • line_item: The price rule applies to the cart's line items.
  • shipping_line: The price rule applies to the cart's shipping lines.
title 
"title": "SUMMERSALE10OFF"

The title of the price rule. This is used by the Shopify admin search to retrieve discounts. It is also displayed on the Discounts page of the Shopify admin for bulk discounts.

For non-bulk discounts, the discount code is displayed on the admin.

For a consistent search experience, use the same value for title as the code property of the associated discount code.
usage_limit 
"usage_limit": 10

The maximum number of times the price rule can be used, per discount code.
prerequisite_product_ids 
"prerequisite_product_ids": [
  7897397755,
  42382368242
]

List of product ids that will be a prerequisites for a Buy X Get Y type discount. The prerequisite_product_ids can be used only with:

  • target_type set to line_item,
  • target_selection set to entitled,
  • allocation_method set to each and
  • prerequisite_to_entitlement_quantity_ratio defined.

Caution

If a product variant is included in prerequisite_variant_ids, then prerequisite_product_ids can't include the ID of the product associated with that variant.
prerequisite_variant_ids 
"prerequisite_variant_ids": [
  6798798798,
  5675765905
]

List of variant ids that will be a prerequisites for a Buy X Get Y type discount. The entitled_variant_ids can be used only with:

  • target_type set to line_item,
  • target_selection set to entitled,
  • allocation_method set to each and
  • prerequisite_to_entitlement_quantity_ratio defined.

Caution

If a product is included in prerequisite_product_ids, then prerequisite_variant_ids can't include the ID of any variants associated with that product.
prerequisite_collection_ids 
"prerequisite_collection_ids": [
  4564654869,
  8979761006
]

List of collection ids that will be a prerequisites for a Buy X Get Y discount. The entitled_collection_ids can be used only with:

  • target_type set to line_item,
  • target_selection set to entitled,
  • allocation_method set to each and
  • prerequisite_to_entitlement_quantity_ratio defined.
Cannot be used in combination with prerequisite_product_ids or prerequisite_variant_ids.
value 
"value": -35

The value of the price rule. If if the value of target_type is shipping_line, then only -100 is accepted. The value must be negative.
value_type 
"value_type": "fixed_amount"

The value type of the price rule. Valid values:

  • fixed_amount: Applies a discount of value as a unit of the store's currency. For example, if value is -30 and the store's currency is USD, then $30 USD is deducted when the discount is applied.
  • percentage: Applies a percentage discount of value. For example, if value is -30, then 30% will be deducted when the discount is applied.

If target_type is shipping_line, then only percentage is accepted.
prerequisite_to_entitlement_quantity_ratio 
"prerequisite_to_entitlement_quantity_ratio": {
  "prerequisite_quantity": 2,
  "entitled_quantity": 1
}

Buy/Get ratio for a Buy X Get Y discount. prerequisite_quantity defines the necessary 'buy' quantity and entitled_quantity the offered 'get' quantity.

The prerequisite_to_entitlement_quantity_ratio can be used only with:

  • value_type set to percentage,
  • target_type set to line_item,
  • target_selection set to entitled,
  • allocation_method set to each,
  • prerequisite_product_ids or prerequisite_variant_ids or prerequisite_collection_ids defined and
  • entitled_product_ids or entitled_variant_ids or entitled_collection_ids defined.

Caution

Cannot be used in combination with prerequisite_subtotal_range, prerequisite_quantity_range or prerequisite_shipping_price_range.
allocation_limit 
"allocation_limit": 3

The number of times the discount can be allocated on the cart - if eligible. For example a Buy 1 hat Get 1 hat for free discount can be applied 3 times on a cart having more than 6 hats, where maximum of 3 hats get discounted - if the allocation_limit is 3. Empty (null) allocation_limit means unlimited number of allocations.

Caution

allocation_limit is only working with Buy X Get Y discount. The default value on creation will be null (unlimited).

Endpoints

POST /admin/api/2020-10/price_rules.json
Creates a price rule

Create a price rule that gives a select group of customers $5 off their order

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "5OFFCUSTOMERGROUP",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "value_type": "fixed_amount",
    "value": "-5.0",
    "customer_selection": "prerequisite",
    "prerequisite_saved_search_ids": [
      789629109
    ],
    "starts_at": "2017-01-19T17:59:10Z"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341483,
    "value_type": "fixed_amount",
    "value": "-5.0",
    "customer_selection": "prerequisite",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2017-01-19T12:59:10-05:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:31:39-04:00",
    "updated_at": "2020-09-11T11:31:39-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [
      789629109
    ],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "5OFFCUSTOMERGROUP",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341483"
  }
}

Create a Buy X Get Y price rule that gives one free ipod touch if customer buys 2 ipods 

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "Buy2iPodsGetiPodTouchForFree",
    "value_type": "percentage",
    "value": "-100.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "entitled",
    "allocation_method": "each",
    "starts_at": "2018-03-22T00:00:00-00:00",
    "prerequisite_collection_ids": [
      841564295
    ],
    "entitled_product_ids": [
      921728736
    ],
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": 2,
      "entitled_quantity": 1
    },
    "allocation_limit": 3
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341484,
    "value_type": "percentage",
    "value": "-100.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "entitled",
    "allocation_method": "each",
    "allocation_limit": 3,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2018-03-21T20:00:00-04:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:31:47-04:00",
    "updated_at": "2020-09-11T11:31:47-04:00",
    "entitled_product_ids": [
      921728736
    ],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [
      841564295
    ],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": 2,
      "entitled_quantity": 1
    },
    "title": "Buy2iPodsGetiPodTouchForFree",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341484"
  }
}

Create a price rule that gives the buyer $10.00 off an order

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "SUMMERSALE10OFF",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "value_type": "fixed_amount",
    "value": "-10.0",
    "customer_selection": "all",
    "starts_at": "2017-01-19T17:59:10Z"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341485,
    "value_type": "fixed_amount",
    "value": "-10.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2017-01-19T12:59:10-05:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:31:57-04:00",
    "updated_at": "2020-09-11T11:31:57-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "SUMMERSALE10OFF",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341485"
  }
}

Create a price rule that gives the buyer 15% off a specific collection

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "15OFFCOLLECTION",
    "target_type": "line_item",
    "target_selection": "entitled",
    "allocation_method": "across",
    "value_type": "percentage",
    "value": "-15.0",
    "customer_selection": "all",
    "entitled_collection_ids": [
      841564295
    ],
    "starts_at": "2017-01-19T17:59:10Z"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341486,
    "value_type": "percentage",
    "value": "-15.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "entitled",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2017-01-19T12:59:10-05:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:31:59-04:00",
    "updated_at": "2020-09-11T11:31:59-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [
      841564295
    ],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "15OFFCOLLECTION",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341486"
  }
}

Create a price rule that gives the buyer free shipping on orders over $50.00 that can be used up to 20 times

POST /admin/api/2020-07/price_rules.json
{
  "price_rule": {
    "title": "FREESHIPPING",
    "target_type": "shipping_line",
    "target_selection": "all",
    "allocation_method": "each",
    "value_type": "percentage",
    "value": "-100.0",
    "usage_limit": 20,
    "customer_selection": "all",
    "prerequisite_subtotal_range": {
      "greater_than_or_equal_to": "50.0"
    },
    "starts_at": "2017-01-19T17:59:10Z"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "price_rule": {
    "id": 996341487,
    "value_type": "percentage",
    "value": "-100.0",
    "customer_selection": "all",
    "target_type": "shipping_line",
    "target_selection": "all",
    "allocation_method": "each",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": 20,
    "starts_at": "2017-01-19T12:59:10-05:00",
    "ends_at": null,
    "created_at": "2020-09-11T11:32:02-04:00",
    "updated_at": "2020-09-11T11:32:02-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": {
      "greater_than_or_equal_to": "50.0"
    },
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "FREESHIPPING",
    "admin_graphql_api_id": "gid://shopify/PriceRule/996341487"
  }
}
PUT /admin/api/2020-10/price_rules/{price_rule_id}.json
Updates an existing a price rule

Update the title of a price rule

PUT /admin/api/2020-07/price_rules/507328175.json
{
  "price_rule": {
    "id": 507328175,
    "title": "WINTER SALE"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "price_rule": {
    "id": 507328175,
    "value_type": "fixed_amount",
    "value": "-10.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2020-09-05T11:31:00-04:00",
    "ends_at": "2020-09-17T11:31:00-04:00",
    "created_at": "2020-09-11T11:31:00-04:00",
    "updated_at": "2020-09-11T11:31:49-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "WINTER SALE",
    "admin_graphql_api_id": "gid://shopify/PriceRule/507328175"
  }
}
GET /admin/api/2020-10/price_rules.json
Retrieves a list of price rules. Note: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

The maximum number of results to retrieve.

(default: 50, maximum: 250)
since_id

Restrict results to after the specified ID.
created_at_min

Show price rules created after date (format 2017-03-25T16:15:47-04:00).
created_at_max

Show price rules created before date (format 2017-03-25T16:15:47-04:00).
updated_at_min

Show price rules last updated after date (format 2017-03-25T16:15:47-04:00).
updated_at_max

Show price rules last updated before date (format 2017-03-25T16:15:47-04:00).
starts_at_min

Show price rules starting after date (format 2017-03-25T16:15:47-04:00).
starts_at_max

Show price rules starting before date (format 2017-03-25T16:15:47-04:00).
ends_at_min

Show price rules ending after date (format 2017-03-25T16:15:47-04:00).
ends_at_max

Show price rules ending before date (format 2017-03-25T16:15:47-04:00).
times_used

Show price rules with times used.

Retrieve all price rules

GET /admin/api/2020-07/price_rules.json
View Response 
HTTP/1.1 200 OK
{
  "price_rules": [
    {
      "id": 507328175,
      "value_type": "fixed_amount",
      "value": "-10.0",
      "customer_selection": "all",
      "target_type": "line_item",
      "target_selection": "all",
      "allocation_method": "across",
      "allocation_limit": null,
      "once_per_customer": false,
      "usage_limit": null,
      "starts_at": "2020-09-05T11:31:00-04:00",
      "ends_at": "2020-09-17T11:31:00-04:00",
      "created_at": "2020-09-11T11:31:00-04:00",
      "updated_at": "2020-09-11T11:31:00-04:00",
      "entitled_product_ids": [],
      "entitled_variant_ids": [],
      "entitled_collection_ids": [],
      "entitled_country_ids": [],
      "prerequisite_product_ids": [],
      "prerequisite_variant_ids": [],
      "prerequisite_collection_ids": [],
      "prerequisite_saved_search_ids": [],
      "prerequisite_customer_ids": [],
      "prerequisite_subtotal_range": null,
      "prerequisite_quantity_range": null,
      "prerequisite_shipping_price_range": null,
      "prerequisite_to_entitlement_quantity_ratio": {
        "prerequisite_quantity": null,
        "entitled_quantity": null
      },
      "title": "SUMMERSALE10OFF",
      "admin_graphql_api_id": "gid://shopify/PriceRule/507328175"
    },
    {
      "id": 106886544,
      "value_type": "fixed_amount",
      "value": "-10.0",
      "customer_selection": "all",
      "target_type": "line_item",
      "target_selection": "all",
      "allocation_method": "across",
      "allocation_limit": null,
      "once_per_customer": false,
      "usage_limit": null,
      "starts_at": "2020-09-09T11:31:00-04:00",
      "ends_at": "2020-09-13T11:31:00-04:00",
      "created_at": "2020-09-11T11:31:00-04:00",
      "updated_at": "2020-09-11T11:31:00-04:00",
      "entitled_product_ids": [],
      "entitled_variant_ids": [],
      "entitled_collection_ids": [],
      "entitled_country_ids": [],
      "prerequisite_product_ids": [],
      "prerequisite_variant_ids": [],
      "prerequisite_collection_ids": [],
      "prerequisite_saved_search_ids": [],
      "prerequisite_customer_ids": [],
      "prerequisite_subtotal_range": null,
      "prerequisite_quantity_range": null,
      "prerequisite_shipping_price_range": null,
      "prerequisite_to_entitlement_quantity_ratio": {
        "prerequisite_quantity": null,
        "entitled_quantity": null
      },
      "title": "TENOFF",
      "admin_graphql_api_id": "gid://shopify/PriceRule/106886544"
    }
  ]
}
GET /admin/api/2020-10/price_rules/{price_rule_id}.json
Retrieves a single price rule

Retrieve a single price rule by its ID

GET /admin/api/2020-07/price_rules/507328175.json
View Response 
HTTP/1.1 200 OK
{
  "price_rule": {
    "id": 507328175,
    "value_type": "fixed_amount",
    "value": "-10.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "allocation_limit": null,
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2020-09-05T11:31:00-04:00",
    "ends_at": "2020-09-17T11:31:00-04:00",
    "created_at": "2020-09-11T11:31:00-04:00",
    "updated_at": "2020-09-11T11:31:00-04:00",
    "entitled_product_ids": [],
    "entitled_variant_ids": [],
    "entitled_collection_ids": [],
    "entitled_country_ids": [],
    "prerequisite_product_ids": [],
    "prerequisite_variant_ids": [],
    "prerequisite_collection_ids": [],
    "prerequisite_saved_search_ids": [],
    "prerequisite_customer_ids": [],
    "prerequisite_subtotal_range": null,
    "prerequisite_quantity_range": null,
    "prerequisite_shipping_price_range": null,
    "prerequisite_to_entitlement_quantity_ratio": {
      "prerequisite_quantity": null,
      "entitled_quantity": null
    },
    "title": "SUMMERSALE10OFF",
    "admin_graphql_api_id": "gid://shopify/PriceRule/507328175"
  }
}
GET /admin/api/2020-10/price_rules/count.json
Retrieves a count of all price rules.

Retrieve a count of all price rules

GET /admin/api/2020-07/price_rules/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 2
}
DELETE /admin/api/2020-10/price_rules/{price_rule_id}.json
Deletes a price rule

Delete a price rule

DELETE /admin/api/2020-07/price_rules/507328175.json
View Response 
HTTP/1.1 204 No Content