The REST Admin API is a legacy API as of October 1, 2024. All apps and integrations should be built with the GraphQL Admin API. For details and migration steps, visit our migration guide.

PriceRule

Choose a version:

Requires price_rules access scope.

Note

We recommend using the GraphQL Admin API to manage discounts. The Discount types available in the GraphQL Admin API are intended to replace the GraphQL Admin PriceRule object and REST Admin PriceRule and DiscountCode resources.

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.

Was this section helpful?

Anchor to section titled 'The PriceRule resource'

The PriceRule resource

Properties

allocation_method

deprecated

The allocation method of the price rule. Valid values:

created_at

read-only

deprecated

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

updated_at

read-only

deprecated

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

customer_selection

deprecated

The customer selection for the price rule. Valid values:

ends_at

deprecated

The date and time (ISO 8601 format) when the price rule ends. Must be after starts_at.

entitled_collection_ids

deprecated

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

deprecated

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

deprecated

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

deprecated

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.

read-only

deprecated

The ID for the price rule.

once_per_customer

deprecated

Whether the generated discount code will be valid only for a single use per customer. This is tracked using customer ID.

prerequisite_customer_ids

deprecated

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 customer_segment_prerequisite_ids must be empty.

Was this section helpful?

Anchor to section titled 'POST request, Creates a price rule'

post
Creates a price rule

discountCodeBasicCreate

discountAutomaticBasicCreate

discountCodeBxgyCreate

discountAutomaticBxgyCreate

discountCodeFreeShippingCreate

discountAutomaticFreeShippingCreate

Creates a price rule

Anchor to section titled 'Parameters of Creates a price rule'

Parameters

api_version

string

required

Was this section helpful?

Anchor to section titled 'Examples of Creates a price rule'

Examples

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

Request body

pricerule

Price_rule resource

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

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

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

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

Was this section helpful?

Anchor to section titled 'GET request, Retrieves a list of price rules'

get
Retrieves a list of price rules

discountNodes

Retrieves a list of price rules. Note: This endpoint implements pagination by using links that are provided in the response header. To learn more, refer to Make paginated requests to the REST Admin API.

Anchor to section titled 'Parameters of Retrieves a list of price rules'

Parameters

api_version

string

required

created_at_max

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

created_at_min

Show price rules created 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).

ends_at_min

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

limit

≤ 250

default 50

The maximum number of results to retrieve.

since_id

Restrict results to after the specified ID.

starts_at_max

Show price rules starting 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).

times_used

Show price rules with times used.

updated_at_max

Show price rules last updated 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).

Was this section helpful?

Anchor to section titled 'Examples of Retrieves a list of price rules'

Examples

Retrieve all price rules

Retrieve all price rules after a specified ID

Was this section helpful?

{}Response

JSON

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": "2024-09-24T17:52:44-04:00",
      "ends_at": "2024-10-06T17:52:44-04:00",
      "created_at": "2024-09-30T17:52:44-04:00",
      "updated_at": "2024-09-30T17:52:44-04:00",
      "entitled_product_ids": [],
      "entitled_variant_ids": [],
      "entitled_collection_ids": [],
      "entitled_country_ids": [],
      "prerequisite_product_ids": [],
      "prerequisite_variant_ids": [],
      "prerequisite_collection_ids": [],
      "customer_segment_prerequisite_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
      },
      "prerequisite_to_entitlement_purchase": {
        "prerequisite_amount": 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": "2024-09-28T17:52:44-04:00",
      "ends_at": "2024-10-02T17:52:44-04:00",
      "created_at": "2024-09-30T17:52:44-04:00",
      "updated_at": "2024-09-30T17:52:44-04:00",
      "entitled_product_ids": [],
      "entitled_variant_ids": [],
      "entitled_collection_ids": [],
      "entitled_country_ids": [],
      "prerequisite_product_ids": [],
      "prerequisite_variant_ids": [],
      "prerequisite_collection_ids": [],
      "customer_segment_prerequisite_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
      },
      "prerequisite_to_entitlement_purchase": {
        "prerequisite_amount": null
      },
      "title": "TENOFF",
      "admin_graphql_api_id": "gid://shopify/PriceRule/106886544"
    }
  ]
}

Anchor to section titled 'GET request, Retrieves a single price rule'