Partners

Cash on delivery

Offer cash on delivery across a market or tailor its availability and fees by destination.

Use these endpoints to offer cash on delivery in a market. Read requests require read_markets; changes require write_markets. Start with simple mode for one market-wide rule, or use advanced mode when destinations need different availability, fees, or order-value conditions.

Choose how cash on delivery applies#

Simple mode#

Use simple mode when one cash-on-delivery rule should cover the whole market. The market settings decide whether the option is available, how its fee is calculated, and which order values qualify.

Advanced mode#

Use advanced mode when availability or fees differ by destination. Checkout first looks for a subdivision zone, then a country zone, and finally the default zone. A disabled matching zone blocks COD; checkout does not fall back to a broader zone. A non-default zone selects countries or subdivisions; the default zone has no regions and covers destinations left unmatched.

Product eligibility and unavailable options#

Read the cod-rules list response for supported fields, operators, priorities and max_rules. Priority 1 runs first; equal priorities run from oldest to newest. The first rule matching any product wins. A block rule makes COD unavailable. An allow rule still requires COD to be enabled and the destination and order-value checks to pass. When no product rule matches, those checks still apply.

Use unavailable_display to hide an unavailable COD option or show its reason. unavailable_message accepts up to 200 characters after trimming surrounding whitespace. Send both fields when replacing settings: omission resets the display to hide and clears the message. Switching COD off for the market hides it regardless of these preferences.

How order values and fees are calculated#

Minimum, maximum, fee-waiver, and percentage-fee rules use the merchandise subtotal after every merchandise discount. Shipping, tax, duties, checkout fees, and the COD fee are not part of that subtotal. Minimum and maximum values include the boundary itself. The fee is waived when the subtotal reaches or exceeds the waiver amount.

A fixed fee uses the amount saved for the order currency. A percentage fee uses the discounted merchandise subtotal. After the fee is resolved, Tringify applies the selected market tax class and records the fee, tax class, and HSN or SAC code in the order pricing snapshot.

Endpoints#

Get COD settings

GET read_markets

Read the cash-on-delivery configuration for a market.

The response includes unavailable_display and unavailable_message; keep both when editing other settings. It also tells you whether cash on delivery is enabled, whether the market uses one simple rule or destination-based zones, and how its fee and order-value conditions are configured. Amount maps are keyed by the market's currency codes. Threshold fields remain present when their corresponding toggle is off, but they do not affect checkout. Supplied inactive amounts still need valid currency codes, nonnegative values, supported precision and valid ranges.

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 COD_SETTINGS_NOT_FOUND

    Cash-on-delivery settings have not been created for this market.
  • 404 NOT_FOUND

    The market does not exist in this store.

Update COD settings

PUT write_markets

Choose the COD mode and save its market-wide rules.

Send the complete settings object. is_enabled controls whether COD can be offered in either mode. In simple mode these rules apply throughout the market. In advanced mode checkout uses COD zones instead. Simple fee and threshold amounts may be incomplete while COD is disabled or Advanced mode is selected; supplied values still require valid currencies, precision and ranges. Enabling Simple COD requires complete valid amounts for every enabled rule. Zone writes always require their own complete fee and threshold configuration. Changing modes requires the confirmation token returned by the first request. An unchanged request leaves the settings untouched and publishes no webhook; a successful change publishes cod_settings/update.

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
mode required string

Use simple for one market-wide rule or advanced for destination-based zones.

Example: simple
is_enabled required boolean

Whether checkout may offer cash on delivery in this market.

Example: true
fee_type required string

Use free, fixed, or percent.

Example: fixed
percent_value string|null

Percentage of discounted merchandise subtotal when fee_type is percent: greater than 0 and at most 100, with at most six fractional digits. Trailing zeros are accepted. Completeness is required when mode is simple and is_enabled is true. Otherwise this Simple-mode value may be omitted or incomplete; a missing percentage must be null, not an empty string. Supplied values must still satisfy the stated currency, precision and range rules.

Example: 2.5
fee_amounts object

Positive decimal-string COD fees for every market currency when fee_type is fixed. Missing values are not converted. Amounts must not exceed 9999999999999999.9999 and must fit currency amount precision: CAD and IDR allow two fractional digits, KWD three, and KRW none. Trailing zeros are accepted. Completeness is required when mode is simple and is_enabled is true. Otherwise this Simple-mode value may be omitted or incomplete; a missing percentage must be null, not an empty string. Supplied values must still satisfy the stated currency, precision and range rules.

Example: {"INR":"25.00"}
min_order_enabled required boolean

Whether checkout requires a minimum discounted merchandise subtotal.

Example: true
min_order_amounts object

Inclusive minimum subtotal keyed by currency code. When enabled, provide a positive amount for every market currency using the same precision and maximum as fee_amounts. A saved nonzero minimum cannot exceed the corresponding nonzero maximum. Completeness is required when mode is simple and is_enabled is true. Otherwise this Simple-mode value may be omitted or incomplete; a missing percentage must be null, not an empty string. Supplied values must still satisfy the stated currency, precision and range rules.

Example: {"INR":"500.00"}
max_order_enabled required boolean

Whether checkout enforces a maximum discounted merchandise subtotal.

Example: true
max_order_amounts object

Inclusive maximum subtotal keyed by currency code. When enabled, provide a positive amount for every market currency using the same precision and maximum as fee_amounts. Equal minimum and maximum values are allowed. Completeness is required when mode is simple and is_enabled is true. Otherwise this Simple-mode value may be omitted or incomplete; a missing percentage must be null, not an empty string. Supplied values must still satisfy the stated currency, precision and range rules.

Example: {"INR":"10000.00"}
waive_fee_enabled required boolean

Whether qualifying orders receive cash on delivery without its fee.

Example: true
waive_fee_over_amounts object

Subtotal at or above which the fee is waived. When enabled, provide a positive amount for every market currency using the same precision and maximum as fee_amounts. A saved nonzero waiver cannot exceed the corresponding nonzero maximum. Completeness is required when mode is simple and is_enabled is true. Otherwise this Simple-mode value may be omitted or incomplete; a missing percentage must be null, not an empty string. Supplied values must still satisfy the stated currency, precision and range rules.

Example: {"INR":"2500.00"}
tax_class_id uuid|null

A tax class assigned to this market. Its rate is applied to the resolved COD fee.

Example: 4be5c5d1-0999-48ea-a2e0-f86703d99169
hsn_code string

HSN or SAC code recorded with the COD fee for tax reporting.

Example: 996812
confirmed boolean

Set to true when retrying a mode change after confirmation.

Example: true
unavailable_display string

Use hide or show_reason when COD is unavailable.

Example: hide
unavailable_message string

Shopper-facing explanation when COD is unavailable. Leading and trailing whitespace is trimmed; at most 200 characters are accepted. Omission clears the saved message.

Example: Cash on delivery is unavailable for this order.
confirmation_token string

Token returned by CONFIRMATION_REQUIRED for the same settings change.

Example: confirm_...

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.
  • 400 STORE_API_INVALID_REQUEST_BODY

    The request body is not valid JSON.
  • 400 SETTINGS_MODE_INVALID

    mode is not simple or advanced.
  • 400 COD_FEE_TYPE_INVALID

    fee_type is not free, fixed, or percent.
  • 400 INVALID_INPUT

    A required amount is missing or nonpositive, an amount uses an unassigned currency, or saved thresholds contradict each other.
  • 400 CHECKOUT_FEE_PERCENT_RANGE

    The COD percentage is missing, is not greater than 0 and at most 100, or exceeds six fractional digits.
  • 400 CHECKOUT_AMOUNT_TOO_LARGE

    An amount exceeds 9999999999999999.9999.
  • 400 CHECKOUT_AMOUNT_TOO_PRECISE

    An amount cannot be represented exactly at its currency's amount precision.
  • 400 DUTY_HSN_CODE_TOO_LONG

    hsn_code exceeds the configured length limit.
  • 400 TAX_CLASS_NOT_IN_MARKET

    The selected tax class does not belong to this market.
  • 400 MARKET_CONFIRMATION_INVALID

    The confirmation token is missing, expired, or does not match this mode change.
  • 409 CONFIRMATION_REQUIRED

    Changing between simple and advanced mode requires confirmation.
  • 403 STORE_COMMERCE_TEST_GATEWAY_ONLY

    is_enabled is true on a development or transfer store. Those stores take payments through the test gateway only; save the settings with is_enabled false.
  • 404 NOT_FOUND

    The market does not exist in this store.

Get COD zone limits

GET read_markets

Read the limits used when creating and editing COD zones.

Use these values to validate zone names, descriptions, HSN or SAC codes, and the number of zones before sending a write. The limits come from the same contract enforced by the service.

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 MARKET_NOT_FOUND

    No market with this id exists in the store.

List COD zones

GET read_markets

List the destination rules configured for advanced mode.

Zones are returned in matching priority order. A non-default zone covers its saved countries or subdivisions. The default zone catches market destinations that no more specific zone covers. A disabled matching zone blocks COD; it does not fall back to a broader zone.

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 MARKET_NOT_FOUND

    No market with this id exists in the store.

Create a COD zone

POST write_markets

Add a destination-specific or default COD rule.

Choose either a country or subdivision scope, or create a default zone with no regions. The first zone respects is_default: false; it is not automatically made the default. Without a matching zone or an explicit default, COD is unavailable for the destination. Every zone has its own availability, fee, minimum, maximum, waiver, and fee-tax configuration. Countries must belong to the market, subdivisions must belong to a selected country, and zone names must be unique within the market. A successful create publishes cod_zones/create.

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
name required string

A name merchants can recognize when managing the zone.

Example: North India
description string

Optional note describing when this rule should be used.

Example: Cash on delivery for northern states
countries array<string>

Country codes from this market covered by the zone. Leave empty for the default zone.

Example: ["IN"]
subdivisions array<string>

Canonical subdivision codes covered by the zone. Each subdivision must belong to a selected country.

Example: ["IN-UP"]
is_default required boolean

Whether this zone covers market destinations not matched by a more specific zone. Explicit opt-in, including for the first zone; when true, countries and subdivisions must be empty.

Example: false
is_enabled required boolean

Whether checkout may offer cash on delivery when this zone matches.

Example: true
fee_type required string

Use free, fixed, or percent.

Example: fixed
percent_value string|null

Percentage of discounted merchandise subtotal when fee_type is percent: greater than 0 and at most 100, with at most six fractional digits. Trailing zeros are accepted.

Example: 2.5
fee_amounts object

Positive decimal-string COD fees for every market currency when fee_type is fixed. Missing values are not converted. Amounts must not exceed 9999999999999999.9999 and must fit currency amount precision: CAD and IDR allow two fractional digits, KWD three, and KRW none. Trailing zeros are accepted.

Example: {"INR":"25.00"}
min_order_enabled required boolean

Whether checkout requires a minimum discounted merchandise subtotal.

Example: true
min_order_amounts object

Inclusive minimum subtotal keyed by currency code. When enabled, provide a positive amount for every market currency using the same precision and maximum as fee_amounts. A saved nonzero minimum cannot exceed the corresponding nonzero maximum.

Example: {"INR":"500.00"}
max_order_enabled required boolean

Whether checkout enforces a maximum discounted merchandise subtotal.

Example: true
max_order_amounts object

Inclusive maximum subtotal keyed by currency code. When enabled, provide a positive amount for every market currency using the same precision and maximum as fee_amounts. Equal minimum and maximum values are allowed.

Example: {"INR":"10000.00"}
waive_fee_enabled required boolean

Whether qualifying orders receive cash on delivery without its fee.

Example: true
waive_fee_over_amounts object

Subtotal at or above which the fee is waived. When enabled, provide a positive amount for every market currency using the same precision and maximum as fee_amounts. A saved nonzero waiver cannot exceed the corresponding nonzero maximum.

Example: {"INR":"2500.00"}
tax_class_id uuid|null

A tax class assigned to this market. Its rate is applied to the resolved COD fee.

Example: 4be5c5d1-0999-48ea-a2e0-f86703d99169
hsn_code string

HSN or SAC code recorded with the COD fee for tax reporting.

Example: 996812

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.
  • 400 STORE_API_INVALID_REQUEST_BODY

    The request body is not valid JSON.
  • 400 COD_ZONE_NAME_REQUIRED

    name is empty.
  • 400 COD_ZONE_NAME_TOO_LONG

    name exceeds the configured limit.
  • 400 COD_ZONE_DESCRIPTION_TOO_LONG

    description exceeds the configured limit.
  • 400 ZONE_DEFAULT_NO_REGIONS

    A default zone cannot also select countries or subdivisions.
  • 400 ZONE_NEEDS_REGION

    A non-default zone must select at least one country or subdivision.
  • 400 ZONE_COUNTRY_INVALID

    A selected country does not belong to this market.
  • 400 ZONE_SUBDIVISION_INVALID

    A subdivision code is invalid or does not belong to this market.
  • 400 ZONE_SUBDIVISION_NOT_IN_COUNTRY

    A selected subdivision does not belong to one of the zone's selected countries.
  • 400 COD_FEE_TYPE_INVALID

    fee_type is not free, fixed, or percent.
  • 400 INVALID_INPUT

    A required amount is missing or nonpositive, an amount uses an unassigned currency, or saved thresholds contradict each other.
  • 400 CHECKOUT_FEE_PERCENT_RANGE

    The COD percentage is missing, is not greater than 0 and at most 100, or exceeds six fractional digits.
  • 400 CHECKOUT_AMOUNT_TOO_LARGE

    An amount exceeds 9999999999999999.9999.
  • 400 CHECKOUT_AMOUNT_TOO_PRECISE

    An amount cannot be represented exactly at its currency's amount precision.
  • 400 DUTY_HSN_CODE_TOO_LONG

    hsn_code exceeds the configured length limit.
  • 400 TAX_CLASS_NOT_IN_MARKET

    The selected tax class does not belong to this market.
  • 404 NOT_FOUND

    The market does not exist in this store.
  • 400 COD_ZONE_LIMIT_REACHED

    The market already has the maximum number of COD zones.
  • 409 COD_ZONE_NAME_DUPLICATE

    Another COD zone in this market already uses this name.

Get a COD zone

GET read_markets

Read one destination rule and its complete fee configuration.

Use the returned values to populate an edit form or inspect the exact rule checkout will consider for this zone.

Path parameters

Name Type Description
marketId required uuid

Market id.

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

COD zone ID.

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 NOT_FOUND

    The market or COD zone does not exist in this store.

Update a COD zone

PUT write_markets

Replace the editable definition of a COD zone.

Send the complete zone definition you want to keep. The same geographic, currency, threshold, and tax-class rules used during creation apply here. To make a zone the default, send is_default: true with empty countries and subdivisions arrays. This clears the previous default. An unchanged request publishes no webhook; a successful change publishes cod_zones/update.

Path parameters

Name Type Description
marketId required uuid

Market id.

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

COD zone ID.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
name required string

A name merchants can recognize when managing the zone.

Example: North India
description string

Optional note describing when this rule should be used.

Example: Cash on delivery for northern states
countries array<string>

Country codes from this market covered by the zone. Leave empty for the default zone.

Example: ["IN"]
subdivisions array<string>

Canonical subdivision codes covered by the zone. Each subdivision must belong to a selected country.

Example: ["IN-UP"]
is_default required boolean

Whether this zone covers market destinations not matched by a more specific zone. Explicit opt-in, including for the first zone; when true, countries and subdivisions must be empty.

Example: false
is_enabled required boolean

Whether checkout may offer cash on delivery when this zone matches.

Example: true
fee_type required string

Use free, fixed, or percent.

Example: fixed
percent_value string|null

Percentage of discounted merchandise subtotal when fee_type is percent: greater than 0 and at most 100, with at most six fractional digits. Trailing zeros are accepted.

Example: 2.5
fee_amounts object

Positive decimal-string COD fees for every market currency when fee_type is fixed. Missing values are not converted. Amounts must not exceed 9999999999999999.9999 and must fit currency amount precision: CAD and IDR allow two fractional digits, KWD three, and KRW none. Trailing zeros are accepted.

Example: {"INR":"25.00"}
min_order_enabled required boolean

Whether checkout requires a minimum discounted merchandise subtotal.

Example: true
min_order_amounts object

Inclusive minimum subtotal keyed by currency code. When enabled, provide a positive amount for every market currency using the same precision and maximum as fee_amounts. A saved nonzero minimum cannot exceed the corresponding nonzero maximum.

Example: {"INR":"500.00"}
max_order_enabled required boolean

Whether checkout enforces a maximum discounted merchandise subtotal.

Example: true
max_order_amounts object

Inclusive maximum subtotal keyed by currency code. When enabled, provide a positive amount for every market currency using the same precision and maximum as fee_amounts. Equal minimum and maximum values are allowed.

Example: {"INR":"10000.00"}
waive_fee_enabled required boolean

Whether qualifying orders receive cash on delivery without its fee.

Example: true
waive_fee_over_amounts object

Subtotal at or above which the fee is waived. When enabled, provide a positive amount for every market currency using the same precision and maximum as fee_amounts. A saved nonzero waiver cannot exceed the corresponding nonzero maximum.

Example: {"INR":"2500.00"}
tax_class_id uuid|null

A tax class assigned to this market. Its rate is applied to the resolved COD fee.

Example: 4be5c5d1-0999-48ea-a2e0-f86703d99169
hsn_code string

HSN or SAC code recorded with the COD fee for tax reporting.

Example: 996812

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.
  • 400 STORE_API_INVALID_REQUEST_BODY

    The request body is not valid JSON.
  • 400 COD_ZONE_NAME_REQUIRED

    name is empty.
  • 400 COD_ZONE_NAME_TOO_LONG

    name exceeds the configured limit.
  • 400 COD_ZONE_DESCRIPTION_TOO_LONG

    description exceeds the configured limit.
  • 400 ZONE_DEFAULT_NO_REGIONS

    A default zone cannot also select countries or subdivisions.
  • 400 ZONE_NEEDS_REGION

    A non-default zone must select at least one country or subdivision.
  • 400 ZONE_COUNTRY_INVALID

    A selected country does not belong to this market.
  • 400 ZONE_SUBDIVISION_INVALID

    A subdivision code is invalid or does not belong to this market.
  • 400 ZONE_SUBDIVISION_NOT_IN_COUNTRY

    A selected subdivision does not belong to one of the zone's selected countries.
  • 400 COD_FEE_TYPE_INVALID

    fee_type is not free, fixed, or percent.
  • 400 INVALID_INPUT

    A required amount is missing or nonpositive, an amount uses an unassigned currency, or saved thresholds contradict each other.
  • 400 CHECKOUT_FEE_PERCENT_RANGE

    The COD percentage is missing, is not greater than 0 and at most 100, or exceeds six fractional digits.
  • 400 CHECKOUT_AMOUNT_TOO_LARGE

    An amount exceeds 9999999999999999.9999.
  • 400 CHECKOUT_AMOUNT_TOO_PRECISE

    An amount cannot be represented exactly at its currency's amount precision.
  • 400 DUTY_HSN_CODE_TOO_LONG

    hsn_code exceeds the configured length limit.
  • 400 TAX_CLASS_NOT_IN_MARKET

    The selected tax class does not belong to this market.
  • 404 NOT_FOUND

    The market does not exist in this store.
  • 400 COD_ZONE_DEFAULT_UNSET_LOCKED

    The only zone cannot stop being the default zone.
  • 409 COD_ZONE_NAME_DUPLICATE

    Another COD zone in this market already uses this name.

Delete a COD zone

DELETE write_markets

Remove a destination rule from the market.

The only zone cannot be deleted. A default zone must be replaced as the default before it can be removed. Existing orders keep the COD fee and tax snapshots recorded when they were placed. A successful deletion publishes cod_zones/delete.

Path parameters

Name Type Description
marketId required uuid

Market id.

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

COD zone ID.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.
  • 400 COD_ZONE_ONLY_DELETE_LOCKED

    The only COD zone cannot be deleted.
  • 400 COD_ZONE_DEFAULT_DELETE_LOCKED

    Choose another default zone before deleting this one.
  • 404 NOT_FOUND

    The market or COD zone does not exist in this store.

List product COD rules

GET read_markets

Read product eligibility rules and the choices supported by the rule editor.

The response contains rules, max_rules, rule_fields, actions and priorities. Use the returned field/operator catalog, including requires_value, when building an editor. The example shows illustrative records and current choices; use the live response for limits. Rules run by ascending priority, with equal priorities evaluated from oldest to newest. The first rule matching any product decides. An allow rule still requires COD to be enabled and destination and order-value checks to pass. No matching product rule leaves those checks in effect.

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 NOT_FOUND

    Market or rule not found in this store.

Create a product COD rule

POST write_markets

Add an allow or block condition for cash on delivery.

Send the complete rule definition using a field and operator from the list response. Title conditions use contains or not_contains. For tag, category, vendor and brand comparisons, value is the resource ID as a string and must belong to this store. Presence checks do not require a value. include_subcategories applies to category conditions. The response returns the saved rule, including its ID and timestamps. Store and market ownership come from the token and URL.

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

Priority from 1 through 10; lower is evaluated first. Equal priorities are evaluated from oldest to newest.

Example: 1
action required string

Use allow or block.

Example: block
field required string

A field from the list response rule_fields catalog.

Example: title
operator required string

An operator supported by the selected field. For title, use contains or not_contains.

Example: contains
value string|null

Condition value required by the selected operator.

Example: Gift card
include_subcategories boolean

Include descendant categories for a category condition.

Example: false

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.
  • 404 NOT_FOUND

    Market or rule not found in this store.
  • 400 INVALID_INPUT

    Invalid action or priority.
  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body must be a JSON object.
  • 400 COLLECTION_RULE_FIELD_INVALID

    Rule field is not valid.
  • 400 COLLECTION_RULE_OPERATOR_INVALID

    Rule operator is not valid for the selected field.
  • 400 COLLECTION_RULE_VALUE_REQUIRED

    This rule operator requires a value.
  • 400 COLLECTION_RULE_SUBCATEGORIES_NOT_ALLOWED

    Include_subcategories is only valid for category rules.
  • 400 COLLECTION_RULE_TAG_ID_INVALID

    Tag value is not a valid integer id.
  • 400 COLLECTION_RULE_CATEGORY_ID_INVALID

    Category value is not a valid integer id.
  • 400 COLLECTION_RULE_VENDOR_ID_INVALID

    Vendor value is not a valid integer id.
  • 400 COLLECTION_RULE_BRAND_ID_INVALID

    Brand value is not a valid integer id.
  • 400 COLLECTION_RULE_TITLE_TOO_LONG

    Title rule value exceeds the contract max length.
  • 400 COLLECTION_RULE_TAG_NOT_FOUND

    Referenced tag does not exist in this store.
  • 400 COLLECTION_RULE_CATEGORY_NOT_FOUND

    Referenced category does not exist in this store.
  • 400 COLLECTION_RULE_VENDOR_NOT_FOUND

    Referenced vendor does not exist in this store.
  • 400 COLLECTION_RULE_BRAND_NOT_FOUND

    Referenced brand does not exist in this store.
  • 400 COD_RULE_LIMIT_REACHED

    The market already has the maximum number of COD rules.

Update a product COD rule

PUT write_markets

Replace a saved product condition and its priority.

Send the complete rule definition using a field and operator from the list response. Title conditions use contains or not_contains. For tag, category, vendor and brand comparisons, value is the resource ID as a string and must belong to this store. Presence checks do not require a value. include_subcategories applies to category conditions. The response returns the saved rule, including its ID and timestamps. Store and market ownership come from the token and URL.

Path parameters

Name Type Description
marketId required uuid

Market id.

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

COD 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

Priority from 1 through 10; lower is evaluated first. Equal priorities are evaluated from oldest to newest.

Example: 1
action required string

Use allow or block.

Example: block
field required string

A field from the list response rule_fields catalog.

Example: title
operator required string

An operator supported by the selected field. For title, use contains or not_contains.

Example: contains
value string|null

Condition value required by the selected operator.

Example: Gift card
include_subcategories boolean

Include descendant categories for a category condition.

Example: false

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.
  • 404 NOT_FOUND

    Market or rule not found in this store.
  • 400 INVALID_INPUT

    Invalid action or priority.
  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body must be a JSON object.
  • 400 COLLECTION_RULE_FIELD_INVALID

    Rule field is not valid.
  • 400 COLLECTION_RULE_OPERATOR_INVALID

    Rule operator is not valid for the selected field.
  • 400 COLLECTION_RULE_VALUE_REQUIRED

    This rule operator requires a value.
  • 400 COLLECTION_RULE_SUBCATEGORIES_NOT_ALLOWED

    Include_subcategories is only valid for category rules.
  • 400 COLLECTION_RULE_TAG_ID_INVALID

    Tag value is not a valid integer id.
  • 400 COLLECTION_RULE_CATEGORY_ID_INVALID

    Category value is not a valid integer id.
  • 400 COLLECTION_RULE_VENDOR_ID_INVALID

    Vendor value is not a valid integer id.
  • 400 COLLECTION_RULE_BRAND_ID_INVALID

    Brand value is not a valid integer id.
  • 400 COLLECTION_RULE_TITLE_TOO_LONG

    Title rule value exceeds the contract max length.
  • 400 COLLECTION_RULE_TAG_NOT_FOUND

    Referenced tag does not exist in this store.
  • 400 COLLECTION_RULE_CATEGORY_NOT_FOUND

    Referenced category does not exist in this store.
  • 400 COLLECTION_RULE_VENDOR_NOT_FOUND

    Referenced vendor does not exist in this store.
  • 400 COLLECTION_RULE_BRAND_NOT_FOUND

    Referenced brand does not exist in this store.

Delete a product COD rule

DELETE write_markets

Remove one cash-on-delivery product condition.

The rule must belong to the market and store identified by the URL and token. A successful response contains deleted: true. Remaining rules keep their priorities.

Path parameters

Name Type Description
marketId required uuid

Market id.

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

COD 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 NOT_FOUND

    Market or rule not found in this store.

Webhook events#

Subscribe to these events when your app keeps a local copy of cash-on-delivery settings or zones. Settings updates contain the complete saved configuration. Zone create and update events contain the complete zone; zone delete identifies the removed zone. Requests that make no effective change do not publish an event.

Cash on delivery settings updated

EVENT cod_settings/update App scope: read_markets Staff permission: markets:write

Fired when a market's cash-on-delivery mode, availability, fee, threshold, or fee-tax settings change.

Payload fields

Field Type Description
cod_settings.id string Always present
cod_settings.market_id string Selectable in the Payload builder
cod_settings.mode string Selectable in the Payload builder
cod_settings.is_enabled boolean Selectable in the Payload builder
cod_settings.fee_type string Selectable in the Payload builder
cod_settings.percent_value string Selectable in the Payload builder
cod_settings.fee_amounts object Selectable in the Payload builder
cod_settings.min_order_enabled boolean Selectable in the Payload builder
cod_settings.min_order_amounts object Selectable in the Payload builder
cod_settings.max_order_enabled boolean Selectable in the Payload builder
cod_settings.max_order_amounts object Selectable in the Payload builder
cod_settings.waive_fee_enabled boolean Selectable in the Payload builder
cod_settings.waive_fee_over_amounts object Selectable in the Payload builder
cod_settings.tax_class_id string Selectable in the Payload builder
cod_settings.hsn_code string Selectable in the Payload builder
cod_settings.unavailable_display string Selectable in the Payload builder
cod_settings.unavailable_message string Selectable in the Payload builder
cod_settings.created_at string Selectable in the Payload builder
cod_settings.updated_at string Selectable in the Payload builder

Cash on delivery zone created

EVENT cod_zones/create App scope: read_markets Staff permission: markets:write

Fired when a cash-on-delivery zone is created in a market.

Payload fields

Field Type Description
cod_zone.id string Always present
cod_zone.market_id string Selectable in the Payload builder
cod_zone.name string Selectable in the Payload builder
cod_zone.description string Selectable in the Payload builder
cod_zone.countries array Selectable in the Payload builder
cod_zone.subdivisions array Selectable in the Payload builder
cod_zone.is_default boolean Selectable in the Payload builder
cod_zone.priority integer Selectable in the Payload builder
cod_zone.is_enabled boolean Selectable in the Payload builder
cod_zone.fee_type string Selectable in the Payload builder
cod_zone.percent_value string Selectable in the Payload builder
cod_zone.fee_amounts object Selectable in the Payload builder
cod_zone.min_order_enabled boolean Selectable in the Payload builder
cod_zone.min_order_amounts object Selectable in the Payload builder
cod_zone.max_order_enabled boolean Selectable in the Payload builder
cod_zone.max_order_amounts object Selectable in the Payload builder
cod_zone.waive_fee_enabled boolean Selectable in the Payload builder
cod_zone.waive_fee_over_amounts object Selectable in the Payload builder
cod_zone.tax_class_id string Selectable in the Payload builder
cod_zone.hsn_code string Selectable in the Payload builder
cod_zone.created_at string Selectable in the Payload builder
cod_zone.updated_at string Selectable in the Payload builder

Cash on delivery zone updated

EVENT cod_zones/update App scope: read_markets Staff permission: markets:write

Fired when a cash-on-delivery zone changes.

Payload fields

Field Type Description
cod_zone.id string Always present
cod_zone.market_id string Selectable in the Payload builder
cod_zone.name string Selectable in the Payload builder
cod_zone.description string Selectable in the Payload builder
cod_zone.countries array Selectable in the Payload builder
cod_zone.subdivisions array Selectable in the Payload builder
cod_zone.is_default boolean Selectable in the Payload builder
cod_zone.priority integer Selectable in the Payload builder
cod_zone.is_enabled boolean Selectable in the Payload builder
cod_zone.fee_type string Selectable in the Payload builder
cod_zone.percent_value string Selectable in the Payload builder
cod_zone.fee_amounts object Selectable in the Payload builder
cod_zone.min_order_enabled boolean Selectable in the Payload builder
cod_zone.min_order_amounts object Selectable in the Payload builder
cod_zone.max_order_enabled boolean Selectable in the Payload builder
cod_zone.max_order_amounts object Selectable in the Payload builder
cod_zone.waive_fee_enabled boolean Selectable in the Payload builder
cod_zone.waive_fee_over_amounts object Selectable in the Payload builder
cod_zone.tax_class_id string Selectable in the Payload builder
cod_zone.hsn_code string Selectable in the Payload builder
cod_zone.created_at string Selectable in the Payload builder
cod_zone.updated_at string Selectable in the Payload builder

Cash on delivery zone deleted

EVENT cod_zones/delete App scope: read_markets Staff permission: markets:write

Fired when a cash-on-delivery zone is deleted.

Payload fields

Field Type Description
cod_zone.id string Always present
cod_zone.market_id string Selectable in the Payload builder
cod_zone.name string Selectable in the Payload builder

Last updated Oct 21, 2026