Fields
Needs Pricing rules: Read and write. Send the rule's fields as GET /pricing-rules shows them, without id and sort_order. A field left out is null, false or an empty list.
| Field | Type | Rule |
|---|---|---|
| namerequired | string | Up to 120 characters. |
| markup_percentageoptional | string, number or null | Percent added to the base, -100 to 999.99, at most two decimals, or null for none. Best sent as a string, such as "22.50". |
| markup_value_fixedoptional | string, number or null | Dollars added after the percentage, -100000 to 100000, at most two decimals, or null for none. |
| apply_markup_price_torequired | string | The base the markup is added to: cost, msrp, map_then_cost or map_then_msrp. |
| apply_only_when_has_mapoptional | boolean | true skips a product whose offer has no MAP above its cost. |
| apply_only_when_has_msrpoptional | boolean | true skips a product whose offer has no MSRP. |
| enforce_map_flooroptional | boolean or null | true never prices below MAP, false may, null follows your store's setting. |
| categoriesoptional | list of strings | Category slugs from GET /categories; each takes in the categories below it. Empty or left out: any. |
| manufacturersoptional | list of strings | Brand slugs from GET /manufacturers. Empty or left out: any. |
| product_classesoptional | list of strings | Product class slugs from GET /product-classes. Empty or left out: any. |
| distributorsoptional | list of strings | Distributor slugs, as a product's sourced_from names them. Empty or left out: any. |
| upcsoptional | list of strings | UPCs, each up to 32 characters. Empty or left out: any. |
| from_priceoptional | string, number or null | The lowest distributor cost the rule applies to, 0 to 9999999.99, at most two decimals, or null for no lower bound. |
| to_priceoptional | string, number or null | The highest distributor cost it applies to, on the same terms, or null for no upper bound. |
| disabledoptional | boolean | true keeps the rule and never applies it. |
| auto_placeoptional | boolean | Default true: directly above the first rule that is broader than this one. false: last. |
| acknowledge_zero_matchoptional | boolean | Send true to save a rule that matches no product in the catalog, after a 422 zero_match_confirmation_required. |
Each list takes at most 1,000 entries. Money with a third decimal is refused, never rounded. A rule's place is not a field: sort_order is refused. Move a rule with POST /pricing-rules/reorder.
- Where it goes. With
auto_place(the default) it goes directly above the first rule that is broader than it, as your Pricing screen places a new rule, so a narrow rule is checked before a general one.falseputs it last. To choose another place, reorder afterwards. - Slugs are checked, not guessed. A slug that names nothing, or a brand merged into another, is
422 validation_failed, named by its place, such asmanufacturers.1. It is never dropped: a dropped slug would widen the rule. Slugs are checked once every other field passes, so fix the fieldserrorsnames first; then every slug that names nothing is named at once. - What follows: exactly what follows a rule saved on the Pricing screen. Your prices are worked out again and arrive as
merchant_price.recomputedchanges, and the rule is announced aspricing_rule.created.
A rule that would match nothing
A rule whose conditions name no product in the catalog is not saved: the answer is 422 zero_match_confirmation_required, with the sentence your Pricing screen shows and acknowledge_field naming the field to send. If you meant it (the stock is still to arrive, say), send the same body again with "acknowledge_zero_match": true. It is not asked for a rule with no condition, or one with a cost range, whose products cannot be counted. Preview a rule to see what it names before you save it.
A retried create makes a second rule
A create is not idempotent. If a request timed out, list the rules before you send it again, and delete a copy you find with DELETE /pricing-rules/{id}. Two identical rules price the same, since the first one wins.
Returns
- 201Created: the rule, in
data, with itsidandsort_order. - 422validation_failed: a field broke a rule.
errorsnames each one. - 422zero_match_confirmation_required: the rule matches no product. Nothing was saved.
This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.