Fields
Needs Restrictions: Read and write. Send the restriction's fields as GET /restrictions shows them, without id. A field left out is null, false or an empty list.
| Field | Type | Rule |
|---|---|---|
| namerequired | string | Up to 120 characters. |
| restriction_typerequired | string | exclude hides what it matches; only_show hides what no switched-on only-show matches. |
| distributorsoptional | list of strings | Distributor slugs, as a product's sourced_from names them: it applies to those distributors' offers, never to your own stock. Empty or left out: any. |
| 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. |
| upcsoptional | list of strings | UPCs, 6 to 14 digits each. A code that can never match (a spreadsheet's scientific notation, a leading apostrophe) is refused. Empty or left out: any. |
| skusoptional | list of strings | SKUs of up to 64 characters: a distributor's, matched against its offer, or your own in-house one. A code that can never match is refused. Empty or left out: any. |
| min_stockoptional | integer or null | 0 to 1000000. On an exclude, it matches an offer with fewer than this in stock; on an only-show, one with at least this many. Null: any. |
| from_priceoptional | string, number or null | The lowest distributor cost it matches, 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 matches, on the same terms, and never below from_price, or null for no upper bound. |
| disabledoptional | boolean | true keeps the restriction and hides nothing. |
| confirm_tokenoptional | string | After a 422 catalogue_wipe_confirmation_required: the confirm_token from that answer, to save a restriction that empties your store anyway. |
| acknowledge_zero_matchoptional | boolean | Send true to save a restriction 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. Name distributors in distributors: distributor_slug and distributor_slugs are refused.
- Checked, not guessed. A slug that names nothing is
422 validation_failed, named by its place, as on a pricing rule; so is ato_pricebelowfrom_price, and a UPC or SKU that can never match. - An only-show with no condition is refused (
422 validation_failed, oncategories): it would match every product and restrict nothing. - What follows: exactly what follows a restriction saved on your Exclusions screen. Your store is worked out again (products leave or come back as
merchant_price.recomputedchanges), and the restriction is announced asrestriction.created.
A restriction that would empty your store
Two shapes hide everything in one save: an exclude with no condition, which matches every product, and your first switched-on only_show, which hides everything it does not match. Neither is saved until you confirm it. The answer is 422 catalogue_wipe_confirmation_required, with the sentence your Exclusions screen shows, wipe_shape (exclude_everything or first_only_show) and a confirm_token. If you meant it, send the same body again with that confirm_token.
A restriction that would match nothing
One whose conditions name no product in the catalog is held back as a pricing rule is: 422 zero_match_confirmation_required, until you send "acknowledge_zero_match": true. A switched-off restriction is never asked. The empty-store question is asked first, so a first only-show that matches nothing needs both.
A retried create makes a second restriction
A create is not idempotent. If a request timed out, list the restrictions before you send it again, and delete a copy you find with DELETE /restrictions/{id}. Two identical restrictions hide the same products.
Returns
- 201Created: the restriction, in
data, with itsid. - 422validation_failed: a field broke a rule.
errorsnames each one. - 422catalogue_wipe_confirmation_required: it would empty your store. Nothing was saved.
- 422zero_match_confirmation_required: it 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.