Checkout protection

Block shoppers from checking out, and allow, require online payment for, hold or refuse orders with per-market order rules.

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

GET read_orders

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

GET read_orders

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.

Example: phone
search string

Part of the value or note.

Example: 98765
limit integer

Page size, 1 to limits.list_max_limit (default limits.list_default_limit).

Example: 50
cursor string

next_cursor of the previous page.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 STORE_API_QUERY_PARAMETER_UNKNOWN

    The query string has a parameter this request does not accept. The message and error.details.allowed_parameters list the ones it does.

Block a shopper

POST write_orders

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.

Example: phone
value required string

The email, phone number, postcode|line 1 address, or IP address or CIDR range.

Example: +91 98765 43210
effect string

refuse (default) or prepaid_only.

Example: prepaid_only
note string

For staff, up to limits.note_max_chars characters. Never shown to the shopper.

Example: Two refused COD parcels
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.

Example: IN
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.

Example: ["checkout"]

Errors

  • 400 CHECKOUT_PROTECTION_BLOCK_INVALID

    kind or effect is unknown, or value is not a valid email, phone number, address (postcode|line 1) or IP address/CIDR range.

  • 409 CHECKOUT_PROTECTION_BLOCK_EXISTS

    The same value (after normalising) is already on the list.

  • 400 CHECKOUT_PROTECTION_BLOCK_LIMIT_REACHED

    The list already holds limits.blocks_max_per_store entries.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Update a block

PUT write_orders

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.

Example: 3f0d6a2e-5b1c-4d8e-9a7f-2c4b6d8e0a1c

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
effect string

refuse or prepaid_only.

Example: refuse
note string

For staff.

expires_at string

RFC 3339 end.

Example: 2027-01-01T00:00:00Z
clear_expires_at boolean

true removes the end.

Example: false
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.

Example: ["checkout","comments","reviews","contact","newsletter","restock","accounts","portals","votes"]

Errors

  • 404 CHECKOUT_PROTECTION_BLOCK_NOT_FOUND

    No such entry in this store.

  • 400 CHECKOUT_PROTECTION_BLOCK_INVALID

    kind or effect is unknown, or value is not a valid email, phone number, address (postcode|line 1) or IP address/CIDR range.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Unblock a shopper

DELETE write_orders

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.

Example: 3f0d6a2e-5b1c-4d8e-9a7f-2c4b6d8e0a1c

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 404 CHECKOUT_PROTECTION_BLOCK_NOT_FOUND

    No such entry in this store.

Block shoppers in bulk

POST write_orders

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.

Example: [{"kind":"email","value":"buyer@example.com","effect":"refuse"}]

Errors

  • 409 CHECKOUT_PROTECTION_JOB_RUNNING

    Another bulk change to the list is still running.

  • 400 CHECKOUT_PROTECTION_BLOCK_LIMIT_REACHED

    The list already holds limits.blocks_max_per_store entries.

  • 400 INVALID_INPUT

    entries is empty or longer than limits.bulk_max_entries.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Unblock shoppers in bulk

POST write_orders

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.

Example: ["3f0d6a2e-5b1c-4d8e-9a7f-2c4b6d8e0a1c"]
all boolean

Remove every entry (of kind, when given).

Example: false
kind string

With all: only this kind.

Errors

  • 409 CHECKOUT_PROTECTION_JOB_RUNNING

    Another bulk change to the list is still running.

  • 400 INVALID_INPUT

    Neither ids nor all was sent, or ids is too long.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Get a block list job

GET read_orders

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.

Example: 7a1b2c3d-4e5f-4061-8a7b-9c0d1e2f3a4b

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 404 CHECKOUT_PROTECTION_JOB_NOT_FOUND

    No such job in this store.

Cancel a block list job

POST write_orders

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.

Example: 7a1b2c3d-4e5f-4061-8a7b-9c0d1e2f3a4b

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 404 CHECKOUT_PROTECTION_JOB_NOT_FOUND

    No such job in this store.

Get checkout protection settings

GET read_orders

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

PUT write_orders

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.

Example: 3

Errors

  • 400 CHECKOUT_PROTECTION_SETTINGS_INVALID

    hold_auto_cancel_days is outside 1 to limits.hold_auto_cancel_days_max.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

List order rules

GET read_markets

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.

Example: 9a1f2c3d-4e5f-6789-abcd-ef0123456789

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.

  • 404 ORDER_RULE_NOT_FOUND

    Market or rule not found in this store.

Create an order rule

POST write_markets

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.

Example: 9a1f2c3d-4e5f-6789-abcd-ef0123456789

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.

Example: 1
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.

Example: hold
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.

Example: [{"field":"payment_method","operator":"is","value":"cod"},{"field":"order_total","operator":"greater_than","value":"5000"}]

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.

  • 404 ORDER_RULE_NOT_FOUND

    Market or rule not found in this store.

  • 400 ORDER_RULE_INVALID

    A 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.

  • 400 ORDER_RULE_ACTION_INVALID

    action is not allow, require_prepaid, hold or refuse.

  • 400 ORDER_RULE_PRIORITY_INVALID

    priority is outside 1 to limits.rules_max_per_market.

  • 400 ORDER_RULE_CONDITION_COUNT_INVALID

    There are no conditions, or more than limits.conditions_max_per_rule.

  • 400 ORDER_RULE_LIMIT_REACHED

    The market already has limits.rules_max_per_market order rules.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Update an order rule

PUT write_markets

Replace a rule's conditions, action and priority.

Send the complete rule.

Path parameters

Name Type Description
marketId required uuid

Market id.

Example: 9a1f2c3d-4e5f-6789-abcd-ef0123456789
ruleId required uuid

Order rule id.

Example: 6b2e8d90-1234-4678-9abc-def012345678

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.

Example: 1
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.

Example: hold
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.

Example: [{"field":"payment_method","operator":"is","value":"cod"},{"field":"order_total","operator":"greater_than","value":"5000"}]

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.

  • 404 ORDER_RULE_NOT_FOUND

    Market or rule not found in this store.

  • 400 ORDER_RULE_INVALID

    A 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.

  • 400 ORDER_RULE_ACTION_INVALID

    action is not allow, require_prepaid, hold or refuse.

  • 400 ORDER_RULE_PRIORITY_INVALID

    priority is outside 1 to limits.rules_max_per_market.

  • 400 ORDER_RULE_CONDITION_COUNT_INVALID

    There are no conditions, or more than limits.conditions_max_per_rule.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Delete an order rule

DELETE write_markets

Remove one order rule.

Orders it already decided keep their reason.

Path parameters

Name Type Description
marketId required uuid

Market id.

Example: 9a1f2c3d-4e5f-6789-abcd-ef0123456789
ruleId required uuid

Order rule id.

Example: 6b2e8d90-1234-4678-9abc-def012345678

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.

  • 404 ORDER_RULE_NOT_FOUND

    Market or rule not found in this store.

Approve a held order

POST write_orders

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.

Example: da9b07a6-803f-4e41-8a18-97ff831bd588

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 404 ORDER_NOT_FOUND

    The order does not exist in this store.

  • 409 ORDER_NOT_HELD

    The order is not held for review: it was never held, or it was already approved or cancelled.

Cancel a held order

POST write_orders

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.

Example: da9b07a6-803f-4e41-8a18-97ff831bd588

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 404 ORDER_NOT_FOUND

    The order does not exist in this store.

  • 409 ORDER_NOT_HELD

    The order is not held for review: it was never held, or it was already approved or cancelled.