Checkout protection has two parts, both kept per store and never shared with another store. The block list holds emails, phone numbers, addresses and IP addresses or ranges, each with an effect: refuse stops checkout, prepaid_only hides cash on delivery and other pay-later methods while online payment still works. Order rules belong to a market and decide each new order: allow, require_prepaid, hold or refuse. Block list, settings and held-order endpoints use read_orders and write_orders; order rules use read_markets and write_markets. Read every cap from GET /checkout-protection/limits instead of hard-coding it.
The block list is checked when the shopper submits contact and address, and again when the order is placed. Values are stored normalised, so an email matches in any letter case (for Gmail, also without dots or a +tag), a phone in E.164, an address by postcode and first line without spaces or punctuation. Bulk add and remove run as background jobs: start one, then poll GET /checkout-protection/jobs/{jobId} for progress and per-row errors. One bulk job runs per store at a time. For a CSV file, use an import or export of type checkout_blocks (columns kind, value, effect, note, expires_at, country_code) from CSV imports and exports.
Order rules run by ascending priority when an order is placed. Every condition of a rule must match; the first matching rule decides, and allow stops checking. Counts are this store's own: placed, uncancelled orders and returned-to-sender orders by the shopper's email or phone, and orders already placed in the last hour or day by phone, email or IP. A count that can't be read doesn't match. A removed tag, category, vendor or brand matches nothing, so deleting one never widens a rule. Cash on delivery rules are separate and unchanged.
A held order is created and its stock committed, but it isn't released to fulfilment until it is approved, and it carries protection with a one-line reason built from the rule. Approving it fires orders/released; cancelling it refunds any captured payment and fires orders/cancelled. A held order nobody reviews is cancelled automatically hold_auto_cancel_days after it was placed (default 3). Holding fires orders/held.
Shoppers only ever see the store's own storefront messages CHECKOUT_PROTECTION_REFUSED and CHECKOUT_PROTECTION_PREPAID_REQUIRED, which merchants can reword; never the reason. Nothing is scored or counted across stores.
Endpoints#
Get checkout protection limits
Caps, block kinds, effects, where each kind can apply, rule actions and condition fields.
Read these instead of hard-coding them: the block list holds up to blocks_max_per_store entries, a market up to rules_max_per_market order rules of up to conditions_max_per_rule conditions each. order_fields lists every shopper and order field with its operators; order rules also accept the product fields and customer_group from the COD rule catalog.
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
List blocked shoppers
The store's block list, newest first.
Each entry is an email, phone, address or IP address/range with its effect: refuse stops checkout with the store's message; prepaid_only hides cash on delivery and other pay-later methods while online payment still works. applies_to says where it applies: checkout, comments (blog comments), reviews (product reviews), contact (the contact form), newsletter (newsletter and app sign-up forms), restock (back-in-stock requests), accounts (customer sign-in and saved addresses), portals (order tracking and the Returns and Delivery portals) and votes (review helpfulness votes). Outside checkout the effect is always to refuse, and the shopper is never told why: a blocked comment is saved as spam and a blocked review as rejected (the shopper is told it is waiting for review), a contact message is kept as spam and not sent, a sign-up, back-in-stock request, sign-in code, order lookup or vote looks accepted and sends or counts nothing, and saving an address or looking up a gift card (which follows checkout) is refused. source is merchant, or spam for an entry learned when the merchant marked a blog comment, review or contact message as spam (source_surface is comments, reviews or contact and source_id that submission's id): it applies to comments, reviews and contact for 90 days, never anywhere else, and goes away when that submission is approved or set back to pending (deleting it keeps the entry); editing it makes it the merchant's own. Entries past expires_at no longer apply and are removed. Pass next_cursor back as cursor for the next page.
Query parameters
| Name | Type | Description |
|---|---|---|
kind
|
string |
email, phone, address or ip. Omit for every kind. |
search
|
string |
Part of the value or note. |
limit
|
integer |
Page size, 1 to limits.list_max_limit (default limits.list_default_limit). |
cursor
|
string |
next_cursor of the previous page. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
400STORE_API_QUERY_PARAMETER_UNKNOWNThe query string has a parameter this request does not accept. The message and
error.details.allowed_parameterslist the ones it does.
Block a shopper
Add one entry to the block list.
The value is stored normalised so variants match: an email lowercased (for Gmail without dots or a +tag), a phone in E.164 (country_code reads a number without a calling code), an address as postcode|line 1 keyed by postcode and line 1 without spaces or punctuation, an IP as an address or CIDR range. At checkout the block is checked when the shopper submits contact and address, and again when the order is placed; on every other surface in applies_to, when the form is submitted. It never tells the shopper why. Only this store is affected.
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
kind
required
|
string |
email, phone, address or ip. |
value
required
|
string |
The email, phone number, |
effect
|
string |
refuse (default) or prepaid_only. |
note
|
string |
For staff, up to limits.note_max_chars characters. Never shown to the shopper. |
expires_at
|
string |
RFC 3339 time the block stops applying; omit for no end. |
country_code
|
string |
Country used to read a phone number without a calling code. |
applies_to
|
array<string> |
Where the entry applies: checkout, comments, reviews, contact, newsletter, restock, accounts, portals, votes. Omit for everywhere its kind allows (limits.surfaces). Email and IP entries may apply to any of them; phone entries to checkout, contact, restock and accounts (the forms that take a phone number); address entries to checkout only. |
Errors
-
400CHECKOUT_PROTECTION_BLOCK_INVALIDkind or effect is unknown, or value is not a valid email, phone number, address (postcode|line 1) or IP address/CIDR range.
-
409CHECKOUT_PROTECTION_BLOCK_EXISTSThe same value (after normalising) is already on the list.
-
400CHECKOUT_PROTECTION_BLOCK_LIMIT_REACHEDThe list already holds limits.blocks_max_per_store entries.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
Update a block
Change an entry's effect, note, end or where it applies.
The value and kind can't change; delete the entry and add a new one. clear_expires_at removes the end.
Path parameters
| Name | Type | Description |
|---|---|---|
blockId
required
|
uuid |
Block list entry id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
effect
|
string |
refuse or prepaid_only. |
note
|
string |
For staff. |
expires_at
|
string |
RFC 3339 end. |
clear_expires_at
|
boolean |
true removes the end. |
applies_to
|
array<string> |
Replaces where the entry applies (checkout, comments, reviews, contact, newsletter, restock, accounts, portals, votes); at least one. Phone entries apply to checkout, contact, restock and accounts only, address entries to checkout only. Editing an entry learned from spam makes it the merchant's own. |
Errors
-
404CHECKOUT_PROTECTION_BLOCK_NOT_FOUNDNo such entry in this store.
-
400CHECKOUT_PROTECTION_BLOCK_INVALIDkind or effect is unknown, or value is not a valid email, phone number, address (postcode|line 1) or IP address/CIDR range.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
Unblock a shopper
Remove one entry from the block list.
Takes effect on the shopper's next checkout step.
Path parameters
| Name | Type | Description |
|---|---|---|
blockId
required
|
uuid |
Block list entry id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
404CHECKOUT_PROTECTION_BLOCK_NOT_FOUNDNo such entry in this store.
Block shoppers in bulk
Add many entries in one background job.
Starts a job that adds up to limits.bulk_max_entries entries. Entries already on the list are skipped, invalid ones are reported in the job's errors with their row, and the rest are added. Poll the job for progress. One bulk job runs per store at a time. To add a CSV file, use an import of type checkout_blocks.
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
entries
required
|
array<object> |
Entries with kind, value and optionally effect, note, expires_at, country_code and applies_to, as for one block. |
Errors
-
409CHECKOUT_PROTECTION_JOB_RUNNINGAnother bulk change to the list is still running.
-
400CHECKOUT_PROTECTION_BLOCK_LIMIT_REACHEDThe list already holds limits.blocks_max_per_store entries.
-
400INVALID_INPUTentries is empty or longer than limits.bulk_max_entries.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
Unblock shoppers in bulk
Remove many entries in one background job.
Send ids (up to limits.bulk_max_entries), or all true with an optional kind to clear the list or one kind of it. Poll the job for progress.
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
ids
|
array<uuid> |
Entries to remove. |
all
|
boolean |
Remove every entry (of kind, when given). |
kind
|
string |
With all: only this kind. |
Errors
-
409CHECKOUT_PROTECTION_JOB_RUNNINGAnother bulk change to the list is still running.
-
400INVALID_INPUTNeither ids nor all was sent, or ids is too long.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
Get a block list job
Progress and errors of a bulk add or remove.
status is queued, running, completed, failed or cancelled; processed of total rows are done, with succeeded and failed counts and up to 100 errors.
Path parameters
| Name | Type | Description |
|---|---|---|
jobId
required
|
uuid |
Bulk job id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
404CHECKOUT_PROTECTION_JOB_NOT_FOUNDNo such job in this store.
Cancel a block list job
Stop a bulk add or remove.
The job stops before its next batch and ends as cancelled; entries it already added or removed stay. Cancelling a job that has ended returns it unchanged. Cancelling a checkout_blocks CSV import cancels its job too.
Path parameters
| Name | Type | Description |
|---|---|---|
jobId
required
|
uuid |
Bulk job id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
404CHECKOUT_PROTECTION_JOB_NOT_FOUNDNo such job in this store.
Get checkout protection settings
How long a held order waits for review.
An order held by an order rule is cancelled automatically, with any captured payment refunded, hold_auto_cancel_days after it was placed (default 3).
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Update checkout protection settings
Change how long a held order waits for review.
Applies to orders held from now on.
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
hold_auto_cancel_days
required
|
integer |
Days, 1 to limits.hold_auto_cancel_days_max. |
Errors
-
400CHECKOUT_PROTECTION_SETTINGS_INVALIDhold_auto_cancel_days is outside 1 to limits.hold_auto_cancel_days_max.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
List order rules
A market's order rules, in the order they run.
Rules run by ascending priority (oldest first on ties) when an order is placed; the first rule whose conditions all match decides, and allow stops checking. Every count is this store's own: placed, uncancelled orders and returned-to-sender orders by the shopper's email or phone, and orders already placed in the last hour or day by phone, email or IP. order_total is compared in the store's base currency. When a velocity count can't be read, a condition on it doesn't match. reason is the one-line reason stored on orders the rule decides.
Path parameters
| Name | Type | Description |
|---|---|---|
marketId
required
|
uuid |
Market id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
400STORE_API_INVALID_REQUEST_BODYmarketIdmust be a valid UUID. -
404ORDER_RULE_NOT_FOUNDMarket or rule not found in this store.
Create an order rule
Allow, require online payment, hold or refuse orders that match.
Send the complete rule. A held order is created and its stock committed as usual, but it isn't released to fulfilment until approved; it fires orders/held. A refused order is never created, and the shopper sees the store's CHECKOUT_PROTECTION_REFUSED storefront message; require_prepaid takes cash on delivery and other pay-later methods away at checkout (CHECKOUT_PROTECTION_PREPAID_REQUIRED if the shopper still tries to pay that way). Reword both under storefront messages; neither ever says why.
Path parameters
| Name | Type | Description |
|---|---|---|
marketId
required
|
uuid |
Market id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
priority
required
|
integer |
1 to limits.rules_max_per_market; lower runs first. Equal priorities run from oldest to newest. |
action
required
|
string |
allow (stop checking), require_prepaid (no cash on delivery or other pay-later method), hold (create the order but keep it from fulfilment until approved) or refuse. |
conditions
required
|
array<object> |
1 to limits.conditions_max_per_rule conditions, all of which must match. Each has field, operator and value; orders_last_hour and orders_last_day also take by (phone, email or ip); postcode with in_list takes values (up to limits.postcode_list_max postcodes). Fields: order_total (the order's total in the store's base currency), payment_method (cod or prepaid), customer_order_count and customer_rto_count (this store's orders by the shopper's email or phone), orders_last_hour, orders_last_day, postcode, is_guest (true or false), item_quantity, customer_group (is_member / is_not_member) and the product fields tag, category, vendor, brand and title as COD rules use them. |
Errors
-
400STORE_API_INVALID_REQUEST_BODYmarketIdmust be a valid UUID. -
404ORDER_RULE_NOT_FOUNDMarket or rule not found in this store.
-
400ORDER_RULE_INVALIDA condition's field, operator, by or value is invalid, or it names a tag, category, vendor, brand or customer group that is not this store's. details.position is the condition's 1-based position.
-
400ORDER_RULE_ACTION_INVALIDaction is not allow, require_prepaid, hold or refuse.
-
400ORDER_RULE_PRIORITY_INVALIDpriority is outside 1 to limits.rules_max_per_market.
-
400ORDER_RULE_CONDITION_COUNT_INVALIDThere are no conditions, or more than limits.conditions_max_per_rule.
-
400ORDER_RULE_LIMIT_REACHEDThe market already has limits.rules_max_per_market order rules.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
Update an order rule
Replace a rule's conditions, action and priority.
Send the complete rule.
Path parameters
| Name | Type | Description |
|---|---|---|
marketId
required
|
uuid |
Market id. |
ruleId
required
|
uuid |
Order rule id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
priority
required
|
integer |
1 to limits.rules_max_per_market; lower runs first. Equal priorities run from oldest to newest. |
action
required
|
string |
allow (stop checking), require_prepaid (no cash on delivery or other pay-later method), hold (create the order but keep it from fulfilment until approved) or refuse. |
conditions
required
|
array<object> |
1 to limits.conditions_max_per_rule conditions, all of which must match. Each has field, operator and value; orders_last_hour and orders_last_day also take by (phone, email or ip); postcode with in_list takes values (up to limits.postcode_list_max postcodes). Fields: order_total (the order's total in the store's base currency), payment_method (cod or prepaid), customer_order_count and customer_rto_count (this store's orders by the shopper's email or phone), orders_last_hour, orders_last_day, postcode, is_guest (true or false), item_quantity, customer_group (is_member / is_not_member) and the product fields tag, category, vendor, brand and title as COD rules use them. |
Errors
-
400STORE_API_INVALID_REQUEST_BODYmarketIdmust be a valid UUID. -
404ORDER_RULE_NOT_FOUNDMarket or rule not found in this store.
-
400ORDER_RULE_INVALIDA condition's field, operator, by or value is invalid, or it names a tag, category, vendor, brand or customer group that is not this store's. details.position is the condition's 1-based position.
-
400ORDER_RULE_ACTION_INVALIDaction is not allow, require_prepaid, hold or refuse.
-
400ORDER_RULE_PRIORITY_INVALIDpriority is outside 1 to limits.rules_max_per_market.
-
400ORDER_RULE_CONDITION_COUNT_INVALIDThere are no conditions, or more than limits.conditions_max_per_rule.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
Delete an order rule
Remove one order rule.
Orders it already decided keep their reason.
Path parameters
| Name | Type | Description |
|---|---|---|
marketId
required
|
uuid |
Market id. |
ruleId
required
|
uuid |
Order rule id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
400STORE_API_INVALID_REQUEST_BODYmarketIdmust be a valid UUID. -
404ORDER_RULE_NOT_FOUNDMarket or rule not found in this store.
Approve a held order
Release an order held for review to fulfilment.
The order continues exactly as if it had not been held: stock stays committed and fulfilment starts. Fires orders/released.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
Order id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
404ORDER_NOT_FOUNDThe order does not exist in this store.
-
409ORDER_NOT_HELDThe order is not held for review: it was never held, or it was already approved or cancelled.
Cancel a held order
Cancel an order held for review and refund it.
The order is cancelled, its stock released, any captured payment refunded to the original payment method, and the customer gets the order cancelled email. Fires orders/cancelled.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
Order id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
404ORDER_NOT_FOUNDThe order does not exist in this store.
-
409ORDER_NOT_HELDThe order is not held for review: it was never held, or it was already approved or cancelled.