Fields
Needs Pricing rules: Read and write, like the save it stands in for. It is the preview your Pricing screen shows, and it saves nothing: no rule, no price and no change are written or announced. Send one of two bodies:
- A new rule: the body you would send to POST /pricing-rules, checked as a create is. It is previewed where that create would put it.
- A change to a rule:
rule_idand the fields you would send to PATCH /pricing-rules/{id}, laid over the rule as the PATCH would lay them.rule_idalone previews the rule as it is.
| Field | Type | Rule |
|---|---|---|
| rule_idoptional | integer | A stored rule to preview a change to. With it, every other field is optional and is laid over the rule as a PATCH would lay it. Without it, the body is a new rule's. |
| nameoptional | string | Up to 120 characters. Required for a new rule. |
| 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_tooptional | string | The base the markup is added to: cost, msrp, map_then_cost or map_then_msrp. Required for a new rule. |
| 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. Refused with rule_id. |
| acknowledge_zero_matchoptional | boolean | Accepted, and changes nothing: a preview is never refused for matching nothing, it says so in zero_match. |
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.
10 previews a minute per store, pricing rules and restrictions together, whichever key asks, on top of the key's own limit: each one works part of your catalog out twice, for up to five seconds.
What it answers
How many products the rule names, and up to 25 real products worked out both ways, those that would change first.
| Field | Meaning |
|---|---|
| scope_count | How many products in the catalog its conditions name, counted up to limits.max_count. The whole catalog when narrowed is false. |
| narrowed | false when its conditions could not be counted (no condition at all, or a cost range), so scope_count is the whole catalog. |
| scope_capped | The count stopped at limits.max_count: there are more. |
| scope_exact | false when a condition is judged per offer (MAP or MSRP only, a cost range, a stock floor), so scope_count is an upper bound and the samples are the truth. |
| catalog_count | Products in the catalog, up to limits.max_count. |
| sampled | Products worked out both ways, up to 200. |
| changed | Of those, how many would change. |
| timed_out | The five seconds ran out while sampling: sampled is what was done. |
| zero_match | It names no product in the catalog, so saving it would ask for acknowledge_zero_match. |
| samples | Up to limits.max_samples products, those that would change first. See below. |
| limits | The limits the answer was worked out under: max_count (100,001), max_samples (25) and timeout_seconds (5). |
Each sample
| Field | Meaning |
|---|---|
| product_id | The product, as GET /products/{id} takes it. |
| title | Its name. |
| upc | Its UPC, or null. |
| image_url | Its thumbnail, or null. |
| before | The product as your store stands now. See below. |
| after | The product once the rule is saved. |
| changed | Its price, whether it is sold, why not, or where it comes from would change. |
Each side, before and after
| Field | Meaning |
|---|---|
| price | The price your store would sell it at, or null when it would not be sold. |
| visible | Whether your store would sell it. |
| hidden_reason | Why it would not be sold, such as restricted, no_offers or no_price, or null when it would. |
| sourced_from | The distributor it would come from, in_house for your own stock, or null. |
| applied_rule_id | The pricing rule that would price it, or null: your default margin, or the rule you are previewing while it has no id yet. |
| cost_price | The winning distributor offer's cost; null for your own stock. |
| map_price | The winning offer's MAP, or null. |
| msrp_price | The winning offer's MSRP, or null. |
| this_rule | true when the rule you are previewing would price it: the new rule, or the stored rule you are changing, which keeps its own id. Pricing rule previews only. |
Returns
- 200What saving it would do, in
data. Nothing was saved. - 404pricing_rule_not_found: your store has no rule with that
rule_id. - 422validation_failed: a field broke a rule, as it would on the save.
- 429rate_limited: more than 10 previews in a minute for this store. Wait for
Retry-Afterseconds.
This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.