PriceRule

Caution

As of August 7th, 2017 Shopify will display the price_rule.title value in the Shopify discount admin page. Please take this change into consideration if you have an app that creates or modifies price rules.

You can use the PriceRule resource to dynamically create discounts using conditions. Merchants can then distribute discounts to their customers using discount codes. Using the PriceRule resource you can flexibly create discounts that specify a discount percent, a fixed amount off, or free shipping; you use entitlements, prerequisites, and other properties to dynamically build these discounts.

Create a price rule

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

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

  • A PriceRule that gives the buyer $10 off if their order total exceeds $40
  • A PriceRule that gives the buyer 15% off a chosen set of product collections
  • A PriceRule that gives free shipping on orders over $100.00 and that can be used up to 20 times by Canadian buyers only

See the POST method for detailed PriceRule resource creation examples.

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

created_at
"created_at": "2017-03-13T16:09:54-04:00"

Date and time when the price rule was created. The API returns this value in ISO 8601 format.

id
"id": 9808080986

Unique numeric identifier for the price rule.

title
"title": "SUMMERSALE10OFF"

Title of the price rule.

Caution

It is recommended to use the same value for title as the associated discount code since only the title is searchable in the Shopify admin. For example: price_rule.title = ABC123 and discount_code.code = ABC123

target_type
"target_type": "line_item"

Target type 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.

target_selection
"target_selection": "entitled"

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.

allocation_method
"allocation_method": "each"

Allocation method of the price rule. Valid values:

  • each: The discount will be applied to each of the entitled items. For example, for a price rule that take $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.

Currently, if target_type is shipping_line, then only each is accepted.

value_type
"value_type": "entitled"

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.

value
"value": -35

Value of the price rule. If target_type is shipping_line, then only -100 is accepted. When discounting a resource the value must be a negative number.

once_per_customer
"once_per_customer": true

Indicates if the generated discount code will only be valid for single customer use. This is tracked using customer id. Valid values: true or false.

usage_limit
"usage_limit": 10

Maximum number of times the price rule can be used, per discount code.

customer_selection
"customer_selection": "prerequisite"

The customer selection for the price rule. Valid values:

  • all: Discount code valid for all customers.
  • prerequisite: Customer must belong to one of the specified prerequisite customer saved searches in prerequisite_saved_search_ids.

prerequisite_saved_search_ids
"prerequisite_saved_search_ids": ["112345Z2345","43535363636"]

List of prerequisite_customer_saved_search_ids. For the price rule to be applicable, the customer must be in the group of customers matching the customer saved searches.

prerequisite_subtotal_range
"prerequisite_subtotal_range": ["greater_than_or_equal_to": "40.0"]

Value that establishes the floor for prerequisite_subtotal_range. The subtotal of the entitled cart items must be greater than or equal to this value for the discount to apply.

prerequisite_shipping_price_range
"prerequisite_shipping_price_range": ["less_than_or_equal_to": "10.0"]

Value that establishes the ceiling for prerequisite_shipping_price_range. The shipping price must be less than or equal to this value for the discount to apply.

entitled_product_ids
"entitled_product_ids": ["7897397755","42382368242"]

List of product ids that will be applicable for the discount. The entitled_product_ids can be used only with target_type set to line_item and target_selection set to entitled. Can be used in combination with entitled_variant_ids.

entitled_variant_ids
"entitled_variant_ids": ["6798798798","5675765905"]

List of variant ids that will be applicable for the discount. The entitled_variant_ids can be used only with target_type set to line_item and target_selection set to entitled. Can be used in combination with entitled_product_ids.

entitled_collection_ids
"entitled_collection_ids": ["4564654869","8979761006"]

List of collection ids that will be applicable for the discount. The entitled_collection_ids can be used only with target_type set to line_item and target_selection set to entitled. Cannot be used in combination with entitled_product_ids or entitled_variant_ids.

entitled_country_ids
" entitled_country_ids": ["7897987023","3569053679"]

List of shipping country ids that will be applicable for the discount. The entitled_country_ids can be used only with target_type set to shipping_line and target_selection set to entitled.

starts_at
"starts_at": "2017-01-19T17:59:10Z"

Date and time when the price rule starts. The API returns this value in ISO 8601 format.

ends_at
"ends_at": "2017-04-19T17:59:10Z"

Date and time when the price rule ends. Must be after starts_at. The API returns this value in ISO 8601 format.

Endpoints

POST /admin/price_rules.json
Create a price rule

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/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": 996341490,
    "value_type": "percentage",
    "value": "-100.0",
    "customer_selection": "all",
    "target_type": "shipping_line",
    "target_selection": "all",
    "allocation_method": "each",
    "once_per_customer": false,
    "usage_limit": 20,
    "starts_at": "2017-01-19T12:59:10-05:00",
    "ends_at": null,
    "created_at": "2017-09-12T16:23:14-04:00",
    "updated_at": "2017-09-12T16:23:14-04:00",
    "entitled_product_ids": [
    ],
    "entitled_variant_ids": [
    ],
    "entitled_collection_ids": [
    ],
    "entitled_country_ids": [
    ],
    "prerequisite_saved_search_ids": [
    ],
    "prerequisite_subtotal_range": {
      "greater_than_or_equal_to": "50.0"
    },
    "prerequisite_shipping_price_range": null,
    "title": "FREESHIPPING"
  }
}

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

POST /admin/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": 996341491,
    "value_type": "fixed_amount",
    "value": "-5.0",
    "customer_selection": "prerequisite",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2017-01-19T12:59:10-05:00",
    "ends_at": null,
    "created_at": "2017-09-12T16:23:14-04:00",
    "updated_at": "2017-09-12T16:23:14-04:00",
    "entitled_product_ids": [
    ],
    "entitled_variant_ids": [
    ],
    "entitled_collection_ids": [
    ],
    "entitled_country_ids": [
    ],
    "prerequisite_saved_search_ids": [
      789629109
    ],
    "prerequisite_subtotal_range": null,
    "prerequisite_shipping_price_range": null,
    "title": "5OFFCUSTOMERGROUP"
  }
}

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

POST /admin/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": 996341492,
    "value_type": "percentage",
    "value": "-15.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "entitled",
    "allocation_method": "across",
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2017-01-19T12:59:10-05:00",
    "ends_at": null,
    "created_at": "2017-09-12T16:23:15-04:00",
    "updated_at": "2017-09-12T16:23:15-04:00",
    "entitled_product_ids": [
    ],
    "entitled_variant_ids": [
    ],
    "entitled_collection_ids": [
      841564295
    ],
    "entitled_country_ids": [
    ],
    "prerequisite_saved_search_ids": [
    ],
    "prerequisite_subtotal_range": null,
    "prerequisite_shipping_price_range": null,
    "title": "15OFFCOLLECTION"
  }
}

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

POST /admin/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": 996341493,
    "value_type": "fixed_amount",
    "value": "-10.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2017-01-19T12:59:10-05:00",
    "ends_at": null,
    "created_at": "2017-09-12T16:23:15-04:00",
    "updated_at": "2017-09-12T16:23:15-04:00",
    "entitled_product_ids": [
    ],
    "entitled_variant_ids": [
    ],
    "entitled_collection_ids": [
    ],
    "entitled_country_ids": [
    ],
    "prerequisite_saved_search_ids": [
    ],
    "prerequisite_subtotal_range": null,
    "prerequisite_shipping_price_range": null,
    "title": "SUMMERSALE10OFF"
  }
}
PUT /admin/price_rules/507328175.json
Change a price rule’s attributes

Update the title for a price rule

PUT /admin/price_rules/#{id}.json
{
  "price_rule": {
    "id": 507328175,
    "value_type": "fixed_amount",
    "value": "-10.0",
    "customer_selection": "all",
    "target_type": "line_item",
    "target_selection": "all",
    "allocation_method": "across",
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2017-09-06T16:23:01-04:00",
    "ends_at": "2017-09-18T16:23:01-04:00",
    "created_at": "2017-09-12T16:23:01-04:00",
    "updated_at": "2017-09-12T16:23:01-04:00",
    "entitled_product_ids": [
    ],
    "entitled_variant_ids": [
    ],
    "entitled_collection_ids": [
    ],
    "entitled_country_ids": [
    ],
    "prerequisite_saved_search_ids": [
    ],
    "prerequisite_subtotal_range": null,
    "prerequisite_shipping_price_range": null,
    "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",
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2017-09-06T16:23:01-04:00",
    "ends_at": "2017-09-18T16:23:01-04:00",
    "created_at": "2017-09-12T16:23:01-04:00",
    "updated_at": "2017-09-12T16:23:14-04:00",
    "entitled_product_ids": [
    ],
    "entitled_variant_ids": [
    ],
    "entitled_collection_ids": [
    ],
    "entitled_country_ids": [
    ],
    "prerequisite_saved_search_ids": [
    ],
    "prerequisite_subtotal_range": null,
    "prerequisite_shipping_price_range": null,
    "title": "WINTER SALE"
  }
}
GET /admin/price_rules.json
Retrieve a list of price rules
limit

Amount of results

(default: 50) (maximum: 250)
page

Page to show

(default: 1)
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

List all price rules

GET /admin/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",
      "once_per_customer": false,
      "usage_limit": null,
      "starts_at": "2017-09-06T16:23:01-04:00",
      "ends_at": "2017-09-18T16:23:01-04:00",
      "created_at": "2017-09-12T16:23:01-04:00",
      "updated_at": "2017-09-12T16:23:01-04:00",
      "entitled_product_ids": [
      ],
      "entitled_variant_ids": [
      ],
      "entitled_collection_ids": [
      ],
      "entitled_country_ids": [
      ],
      "prerequisite_saved_search_ids": [
      ],
      "prerequisite_subtotal_range": null,
      "prerequisite_shipping_price_range": null,
      "title": "SUMMERSALE10OFF"
    }
  ]
}
GET /admin/price_rules/507328175.json
Retrieve a single price rule

Retrieve a single price rule

GET /admin/price_rules/#{id}.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",
    "once_per_customer": false,
    "usage_limit": null,
    "starts_at": "2017-09-06T16:23:01-04:00",
    "ends_at": "2017-09-18T16:23:01-04:00",
    "created_at": "2017-09-12T16:23:01-04:00",
    "updated_at": "2017-09-12T16:23:01-04:00",
    "entitled_product_ids": [
    ],
    "entitled_variant_ids": [
    ],
    "entitled_collection_ids": [
    ],
    "entitled_country_ids": [
    ],
    "prerequisite_saved_search_ids": [
    ],
    "prerequisite_subtotal_range": null,
    "prerequisite_shipping_price_range": null,
    "title": "SUMMERSALE10OFF"
  }
}
DELETE /admin/price_rules/507328175.json
Delete a price rule

Permanently delete a price rule

DELETE /admin/price_rules/#{id}.json
View Response
HTTP/1.1 204 No Content