Shipping

Get shipping settings

GET read_markets

Get shipping settings.

Returns persisted simple/advanced mode, simple currency maps, shared tax class, and HS code. Zone and method routes reject unless persisted mode is advanced.

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.
400 STORE_API_INVALID_REQUEST_BODY
The JSON request body is malformed.
400 SHIPPING_SETTINGS_TYPE_INVALID
The simple shipping type is not free, flat, or threshold.
400 TAX_CLASS_NOT_IN_MARKET
The selected tax class does not belong to this market.
400 SHIPPING_RATE_TYPE_INVALID
The method rate type is not a Store API-writable manual type.
400 SHIPPING_RATES_REQUIRED
This rate type requires at least one rate row.
400 SHIPPING_RATES_LIMIT
The method contains more rate rows than the published limit.
400 SHIPPING_RATE_FLAT_SINGLE
A flat method must contain exactly one rate row.
400 SHIPPING_RATE_PRICES_REQUIRED
A paid rate is missing its prices map.
400 SHIPPING_RATE_TIER_GAP
Tier boundaries do not cover a contiguous range beginning at zero.
400 SHIPPING_RATE_TIER_OVERLAP
Two tier boundaries overlap.
400 SHIPPING_RATE_COORDINATE_MISMATCH
A price-tier currency override is incomplete across its prices and boundaries.
400 SHIPPING_RATE_ITEM_COUNT_INVALID
An item-quantity boundary is not a valid whole number within the published limit.
400 SHIPPING_RATE_BASE_PRICE_REQUIRED
A rate is missing its required base-currency price.
400 SHIPPING_RATE_THRESHOLDS_REQUIRED
A price tier is missing its currency boundary maps.
400 SHIPPING_RATE_THRESHOLD_BASE_REQUIRED
A price tier is missing its required base-currency boundary.
400 SHIPPING_RATE_CURRENCY_UNKNOWN
A rate contains a currency that is not enabled for the market.
400 SHIPPING_RATE_PRICE_INVALID
A rate price is not a valid exact decimal.
400 SHIPPING_RATE_PRICE_NEGATIVE
A rate price is negative.
400 SHIPPING_RATE_PRICE_TOO_LARGE
A rate price exceeds the backend-published monetary limit.
400 SHIPPING_RATE_PRICE_TOO_PRECISE
A rate price exceeds that currency's decimal precision.
400 SHIPPING_RATE_THRESHOLD_INVALID
A price-tier boundary is not a valid exact decimal.
400 SHIPPING_RATE_THRESHOLD_NEGATIVE
A price-tier boundary is negative.
400 SHIPPING_RATE_THRESHOLD_TOO_LARGE
A price-tier boundary exceeds the backend-published monetary limit.
400 SHIPPING_RATE_THRESHOLD_TOO_PRECISE
A price-tier boundary exceeds that currency's decimal precision.
400 SHIPPING_RATE_MIN_INVALID
A weight or item tier minimum is invalid.
400 SHIPPING_RATE_MIN_NEGATIVE
A weight or item tier minimum is negative.
400 SHIPPING_RATE_MAX_INVALID
A weight or item tier maximum is invalid.
400 SHIPPING_RATE_MAX_NEGATIVE
A weight or item tier maximum is negative.
400 SHIPPING_RATE_MIN_ABOVE_MAX
A tier minimum is not below its maximum.
400 SHIPPING_RATE_DATA_INVALID
A stored rate violates the shipping contract.
400 SHIPPING_ZONE_DEFAULT_DELETE_LOCKED
The immutable default zone cannot be deleted.
400 SHIPPING_ZONE_DEFAULT_UNSET_LOCKED
The immutable default zone cannot be converted to an explicit zone.
400 SHIPPING_ZONE_DEFAULT_CREATE_LOCKED
Only the advanced-mode transition can create the default zone.
400 ZONE_COUNTRY_INVALID
A zone country does not belong to this market.
400 ZONE_SUBDIVISION_INVALID
A subdivision code is invalid.
400 ZONE_SUBDIVISION_NOT_IN_COUNTRY
A subdivision does not belong to a country selected in the zone.
400 ZONE_COUNTRY_TAKEN
Another zone already provides the fallback for this country. Select unclaimed subdivisions or edit the existing fallback.
400 ZONE_SUBDIVISION_TAKEN
Another zone already claims the subdivision.
409 SHIPPING_ADVANCED_REQUIRED
The persisted shipping mode must be advanced. First save shipping settings with mode=advanced and wait for success, then retry the zone or method request.
409 SHIPPING_ZONE_NAME_DUPLICATE
Another zone in this market already has this name.
409 SHIPPING_METHOD_NAME_DUPLICATE
Another method in this zone already has this name.
409 SHIPPING_ZONE_LIMIT_REACHED
The market has reached its published zone limit.
409 SHIPPING_METHOD_LIMIT_REACHED
The zone has reached its published method limit.
409 CONFIRMATION_REQUIRED
A destructive mode transition requires confirmation.
404 MARKET_NOT_FOUND
The market does not exist in this store.
404 SHIPPING_ZONE_NOT_FOUND
The shipping zone does not exist in this market.
404 SHIPPING_METHOD_NOT_FOUND
The shipping method does not exist in this zone.

Response

200

Sample response

{"success":true,"data":{"shipping_settings":{"id":"2c7c8547-cc7b-46b2-b32d-31c9f3f2abf8","market_id":"9a1f2c3d-4e5f-6789-abcd-ef0123456789","mode":"simple","shipping_type":"threshold","flat_rate":{},"free_threshold":{"EUR":"100.00"},"threshold_rate":{"EUR":"10.00"},"tax_class_id":"4be5c5d1-0999-48ea-a2e0-f86703d99169","hsn_code":"9965","preview":{"mode":"simple","shipping_type":"threshold","basis":"post_discount_merchandise_subtotal","currency_code":"EUR","scenarios":[{"condition":"below_threshold","threshold":"100.00","shipping_amount":"10.00"},{"condition":"at_or_above_threshold","threshold":"100.00","shipping_amount":"0"}]},"created_at":"2026-07-01T10:15:00+02:00","updated_at":"2026-07-08T18:40:00+02:00"}}}

Update shipping settings

PUT write_markets

Update shipping settings.

Save mode=advanced successfully before managing zones or methods. Limits can be fetched before activation. Sending mode=advanced alongside a zone or method does not activate shipping. The settings write switches modes atomically, clears simple amounts, and creates the immutable empty default zone. Configure its methods or add zones in subsequent requests. Advanced to simple returns CONFIRMATION_REQUIRED, then permanently deletes every zone, method, and rate in the confirmed transaction.

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`	Simple or advanced.
`shipping_type`	`string`	Free, flat, or threshold in simple mode.
`flat_rate`	`object`	Required base-currency decimal string plus optional exact overrides for other enabled currencies. Zero is allowed. Amounts use a decimal point, without currency symbols or grouping, and must respect currency precision and money limits. Missing overrides use base-currency conversion.
`free_threshold`	`object`	Required base-currency decimal string plus optional exact overrides for other enabled currencies. Every supplied threshold must be greater than zero and within the currency precision and money limit. At or above the threshold, post-discount merchandise qualifies for free shipping.
`threshold_rate`	`object`	Charge below the free-shipping threshold: required base-currency decimal string plus optional exact overrides. Zero is allowed. Missing overrides use base-currency conversion; all amounts respect currency precision and money limits.
`tax_class_id`	`string\|null`	Shared market tax class.
`hsn_code`	`string`	Canonicalizable 2-12 digit HS code.
`confirmed`	`boolean`	Confirmation retry flag.
`confirmation_token`	`string`	Token from CONFIRMATION_REQUIRED.

Errors

400 STORE_API_INVALID_REQUEST_BODY
marketId must be a valid UUID.
400 STORE_API_INVALID_REQUEST_BODY
The JSON request body is malformed.
400 SHIPPING_SETTINGS_TYPE_INVALID
The simple shipping type is not free, flat, or threshold.
400 TAX_CLASS_NOT_IN_MARKET
The selected tax class does not belong to this market.
400 SHIPPING_RATE_TYPE_INVALID
The method rate type is not a Store API-writable manual type.
400 SHIPPING_RATES_REQUIRED
This rate type requires at least one rate row.
400 SHIPPING_RATES_LIMIT
The method contains more rate rows than the published limit.
400 SHIPPING_RATE_FLAT_SINGLE
A flat method must contain exactly one rate row.
400 SHIPPING_RATE_PRICES_REQUIRED
A paid rate is missing its prices map.
400 SHIPPING_RATE_TIER_GAP
Tier boundaries do not cover a contiguous range beginning at zero.
400 SHIPPING_RATE_TIER_OVERLAP
Two tier boundaries overlap.
400 SHIPPING_RATE_COORDINATE_MISMATCH
A price-tier currency override is incomplete across its prices and boundaries.
400 SHIPPING_RATE_ITEM_COUNT_INVALID
An item-quantity boundary is not a valid whole number within the published limit.
400 SHIPPING_RATE_BASE_PRICE_REQUIRED
A rate is missing its required base-currency price.
400 SHIPPING_RATE_THRESHOLDS_REQUIRED
A price tier is missing its currency boundary maps.
400 SHIPPING_RATE_THRESHOLD_BASE_REQUIRED
A price tier is missing its required base-currency boundary.
400 SHIPPING_RATE_CURRENCY_UNKNOWN
A rate contains a currency that is not enabled for the market.
400 SHIPPING_RATE_PRICE_INVALID
A rate price is not a valid exact decimal.
400 SHIPPING_RATE_PRICE_NEGATIVE
A rate price is negative.
400 SHIPPING_RATE_PRICE_TOO_LARGE
A rate price exceeds the backend-published monetary limit.
400 SHIPPING_RATE_PRICE_TOO_PRECISE
A rate price exceeds that currency's decimal precision.
400 SHIPPING_RATE_THRESHOLD_INVALID
A price-tier boundary is not a valid exact decimal.
400 SHIPPING_RATE_THRESHOLD_NEGATIVE
A price-tier boundary is negative.
400 SHIPPING_RATE_THRESHOLD_TOO_LARGE
A price-tier boundary exceeds the backend-published monetary limit.
400 SHIPPING_RATE_THRESHOLD_TOO_PRECISE
A price-tier boundary exceeds that currency's decimal precision.
400 SHIPPING_RATE_MIN_INVALID
A weight or item tier minimum is invalid.
400 SHIPPING_RATE_MIN_NEGATIVE
A weight or item tier minimum is negative.
400 SHIPPING_RATE_MAX_INVALID
A weight or item tier maximum is invalid.
400 SHIPPING_RATE_MAX_NEGATIVE
A weight or item tier maximum is negative.
400 SHIPPING_RATE_MIN_ABOVE_MAX
A tier minimum is not below its maximum.
400 SHIPPING_RATE_DATA_INVALID
A stored rate violates the shipping contract.
400 SHIPPING_ZONE_DEFAULT_DELETE_LOCKED
The immutable default zone cannot be deleted.
400 SHIPPING_ZONE_DEFAULT_UNSET_LOCKED
The immutable default zone cannot be converted to an explicit zone.
400 SHIPPING_ZONE_DEFAULT_CREATE_LOCKED
Only the advanced-mode transition can create the default zone.
400 ZONE_COUNTRY_INVALID
A zone country does not belong to this market.
400 ZONE_SUBDIVISION_INVALID
A subdivision code is invalid.
400 ZONE_SUBDIVISION_NOT_IN_COUNTRY
A subdivision does not belong to a country selected in the zone.
400 ZONE_COUNTRY_TAKEN
Another zone already provides the fallback for this country. Select unclaimed subdivisions or edit the existing fallback.
400 ZONE_SUBDIVISION_TAKEN
Another zone already claims the subdivision.
409 SHIPPING_ADVANCED_REQUIRED
The persisted shipping mode must be advanced. First save shipping settings with mode=advanced and wait for success, then retry the zone or method request.
409 SHIPPING_ZONE_NAME_DUPLICATE
Another zone in this market already has this name.
409 SHIPPING_METHOD_NAME_DUPLICATE
Another method in this zone already has this name.
409 SHIPPING_ZONE_LIMIT_REACHED
The market has reached its published zone limit.
409 SHIPPING_METHOD_LIMIT_REACHED
The zone has reached its published method limit.
409 CONFIRMATION_REQUIRED
A destructive mode transition requires confirmation.
404 MARKET_NOT_FOUND
The market does not exist in this store.
404 SHIPPING_ZONE_NOT_FOUND
The shipping zone does not exist in this market.
404 SHIPPING_METHOD_NOT_FOUND
The shipping method does not exist in this zone.

Response

200

Sample response

{"success":true,"data":{"shipping_settings":{"id":"2c7c8547-cc7b-46b2-b32d-31c9f3f2abf8","market_id":"9a1f2c3d-4e5f-6789-abcd-ef0123456789","mode":"simple","shipping_type":"threshold","flat_rate":{},"free_threshold":{"EUR":"100.00"},"threshold_rate":{"EUR":"10.00"},"tax_class_id":"4be5c5d1-0999-48ea-a2e0-f86703d99169","hsn_code":"9965","preview":{"mode":"simple","shipping_type":"threshold","basis":"post_discount_merchandise_subtotal","currency_code":"EUR","scenarios":[{"condition":"below_threshold","threshold":"100.00","shipping_amount":"10.00"},{"condition":"at_or_above_threshold","threshold":"100.00","shipping_amount":"0"}]},"created_at":"2026-07-01T10:15:00+02:00","updated_at":"2026-07-08T18:40:00+02:00"}},"code":"SHIPPING_SETTINGS_UPDATED","message":"Shipping settings updated."}

Get shipping zone limits

GET read_markets

Get shipping zone limits.

Returns live zone name, description, search, pagination, and per-market limits.

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.
400 STORE_API_INVALID_REQUEST_BODY
The JSON request body is malformed.
400 SHIPPING_SETTINGS_TYPE_INVALID
The simple shipping type is not free, flat, or threshold.
400 TAX_CLASS_NOT_IN_MARKET
The selected tax class does not belong to this market.
400 SHIPPING_RATE_TYPE_INVALID
The method rate type is not a Store API-writable manual type.
400 SHIPPING_RATES_REQUIRED
This rate type requires at least one rate row.
400 SHIPPING_RATES_LIMIT
The method contains more rate rows than the published limit.
400 SHIPPING_RATE_FLAT_SINGLE
A flat method must contain exactly one rate row.
400 SHIPPING_RATE_PRICES_REQUIRED
A paid rate is missing its prices map.
400 SHIPPING_RATE_TIER_GAP
Tier boundaries do not cover a contiguous range beginning at zero.
400 SHIPPING_RATE_TIER_OVERLAP
Two tier boundaries overlap.
400 SHIPPING_RATE_COORDINATE_MISMATCH
A price-tier currency override is incomplete across its prices and boundaries.
400 SHIPPING_RATE_ITEM_COUNT_INVALID
An item-quantity boundary is not a valid whole number within the published limit.
400 SHIPPING_RATE_BASE_PRICE_REQUIRED
A rate is missing its required base-currency price.
400 SHIPPING_RATE_THRESHOLDS_REQUIRED
A price tier is missing its currency boundary maps.
400 SHIPPING_RATE_THRESHOLD_BASE_REQUIRED
A price tier is missing its required base-currency boundary.
400 SHIPPING_RATE_CURRENCY_UNKNOWN
A rate contains a currency that is not enabled for the market.
400 SHIPPING_RATE_PRICE_INVALID
A rate price is not a valid exact decimal.
400 SHIPPING_RATE_PRICE_NEGATIVE
A rate price is negative.
400 SHIPPING_RATE_PRICE_TOO_LARGE
A rate price exceeds the backend-published monetary limit.
400 SHIPPING_RATE_PRICE_TOO_PRECISE
A rate price exceeds that currency's decimal precision.
400 SHIPPING_RATE_THRESHOLD_INVALID
A price-tier boundary is not a valid exact decimal.
400 SHIPPING_RATE_THRESHOLD_NEGATIVE
A price-tier boundary is negative.
400 SHIPPING_RATE_THRESHOLD_TOO_LARGE
A price-tier boundary exceeds the backend-published monetary limit.
400 SHIPPING_RATE_THRESHOLD_TOO_PRECISE
A price-tier boundary exceeds that currency's decimal precision.
400 SHIPPING_RATE_MIN_INVALID
A weight or item tier minimum is invalid.
400 SHIPPING_RATE_MIN_NEGATIVE
A weight or item tier minimum is negative.
400 SHIPPING_RATE_MAX_INVALID
A weight or item tier maximum is invalid.
400 SHIPPING_RATE_MAX_NEGATIVE
A weight or item tier maximum is negative.
400 SHIPPING_RATE_MIN_ABOVE_MAX
A tier minimum is not below its maximum.
400 SHIPPING_RATE_DATA_INVALID
A stored rate violates the shipping contract.
400 SHIPPING_ZONE_DEFAULT_DELETE_LOCKED
The immutable default zone cannot be deleted.
400 SHIPPING_ZONE_DEFAULT_UNSET_LOCKED
The immutable default zone cannot be converted to an explicit zone.
400 SHIPPING_ZONE_DEFAULT_CREATE_LOCKED
Only the advanced-mode transition can create the default zone.
400 ZONE_COUNTRY_INVALID
A zone country does not belong to this market.
400 ZONE_SUBDIVISION_INVALID
A subdivision code is invalid.
400 ZONE_SUBDIVISION_NOT_IN_COUNTRY
A subdivision does not belong to a country selected in the zone.
400 ZONE_COUNTRY_TAKEN
Another zone already provides the fallback for this country. Select unclaimed subdivisions or edit the existing fallback.
400 ZONE_SUBDIVISION_TAKEN
Another zone already claims the subdivision.
409 SHIPPING_ADVANCED_REQUIRED
The persisted shipping mode must be advanced. First save shipping settings with mode=advanced and wait for success, then retry the zone or method request.
409 SHIPPING_ZONE_NAME_DUPLICATE
Another zone in this market already has this name.
409 SHIPPING_METHOD_NAME_DUPLICATE
Another method in this zone already has this name.
409 SHIPPING_ZONE_LIMIT_REACHED
The market has reached its published zone limit.
409 SHIPPING_METHOD_LIMIT_REACHED
The zone has reached its published method limit.
409 CONFIRMATION_REQUIRED
A destructive mode transition requires confirmation.
404 MARKET_NOT_FOUND
The market does not exist in this store.
404 SHIPPING_ZONE_NOT_FOUND
The shipping zone does not exist in this market.
404 SHIPPING_METHOD_NOT_FOUND
The shipping method does not exist in this zone.

Response

200

Sample response

{"success":true,"data":{"max_per_market":50,"name_max_length":100,"description_max_length":500,"list_page_size":20,"list_max_limit":200,"search_max_length":200}}

List available shipping countries

GET read_markets

List available shipping countries.

Returns market countries with country-fallback and explicit subdivision claims. fully_claimed means another country fallback exists; unclaimed subdivisions remain selectable. claimed_subdivisions lists explicit claims even when a fallback exists. Use exclude_zone_id while editing so the zone's existing claims remain selectable.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`

Query parameters

Name	Type	Description
`search`	`string`	Search by country name or ISO country code. Example: `india`
`page`	`integer`	Page number starting at 1. Example: `1`
`per_page`	`integer`	Page size, capped by the service limit. Example: `20`
`exclude_zone_id`	`uuid`	Zone whose existing claims should be ignored while editing. Example: `7c9e4f2b-1a3d-4e5f-8b6c-2d0e1f3a4b5c`

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 STORE_API_INVALID_REQUEST_BODY
The JSON request body is malformed.
400 SHIPPING_SETTINGS_TYPE_INVALID
The simple shipping type is not free, flat, or threshold.
400 TAX_CLASS_NOT_IN_MARKET
The selected tax class does not belong to this market.
400 SHIPPING_RATE_TYPE_INVALID
The method rate type is not a Store API-writable manual type.
400 SHIPPING_RATES_REQUIRED
This rate type requires at least one rate row.
400 SHIPPING_RATES_LIMIT
The method contains more rate rows than the published limit.
400 SHIPPING_RATE_FLAT_SINGLE
A flat method must contain exactly one rate row.
400 SHIPPING_RATE_PRICES_REQUIRED
A paid rate is missing its prices map.
400 SHIPPING_RATE_TIER_GAP
Tier boundaries do not cover a contiguous range beginning at zero.
400 SHIPPING_RATE_TIER_OVERLAP
Two tier boundaries overlap.
400 SHIPPING_RATE_COORDINATE_MISMATCH
A price-tier currency override is incomplete across its prices and boundaries.
400 SHIPPING_RATE_ITEM_COUNT_INVALID
An item-quantity boundary is not a valid whole number within the published limit.
400 SHIPPING_RATE_BASE_PRICE_REQUIRED
A rate is missing its required base-currency price.
400 SHIPPING_RATE_THRESHOLDS_REQUIRED
A price tier is missing its currency boundary maps.
400 SHIPPING_RATE_THRESHOLD_BASE_REQUIRED
A price tier is missing its required base-currency boundary.
400 SHIPPING_RATE_CURRENCY_UNKNOWN
A rate contains a currency that is not enabled for the market.
400 SHIPPING_RATE_PRICE_INVALID
A rate price is not a valid exact decimal.
400 SHIPPING_RATE_PRICE_NEGATIVE
A rate price is negative.
400 SHIPPING_RATE_PRICE_TOO_LARGE
A rate price exceeds the backend-published monetary limit.
400 SHIPPING_RATE_PRICE_TOO_PRECISE
A rate price exceeds that currency's decimal precision.
400 SHIPPING_RATE_THRESHOLD_INVALID
A price-tier boundary is not a valid exact decimal.
400 SHIPPING_RATE_THRESHOLD_NEGATIVE
A price-tier boundary is negative.
400 SHIPPING_RATE_THRESHOLD_TOO_LARGE
A price-tier boundary exceeds the backend-published monetary limit.
400 SHIPPING_RATE_THRESHOLD_TOO_PRECISE
A price-tier boundary exceeds that currency's decimal precision.
400 SHIPPING_RATE_MIN_INVALID
A weight or item tier minimum is invalid.
400 SHIPPING_RATE_MIN_NEGATIVE
A weight or item tier minimum is negative.
400 SHIPPING_RATE_MAX_INVALID
A weight or item tier maximum is invalid.
400 SHIPPING_RATE_MAX_NEGATIVE
A weight or item tier maximum is negative.
400 SHIPPING_RATE_MIN_ABOVE_MAX
A tier minimum is not below its maximum.
400 SHIPPING_RATE_DATA_INVALID
A stored rate violates the shipping contract.
400 SHIPPING_ZONE_DEFAULT_DELETE_LOCKED
The immutable default zone cannot be deleted.
400 SHIPPING_ZONE_DEFAULT_UNSET_LOCKED
The immutable default zone cannot be converted to an explicit zone.
400 SHIPPING_ZONE_DEFAULT_CREATE_LOCKED
Only the advanced-mode transition can create the default zone.
400 ZONE_COUNTRY_INVALID
A zone country does not belong to this market.
400 ZONE_SUBDIVISION_INVALID
A subdivision code is invalid.
400 ZONE_SUBDIVISION_NOT_IN_COUNTRY
A subdivision does not belong to a country selected in the zone.
400 ZONE_COUNTRY_TAKEN
Another zone already provides the fallback for this country. Select unclaimed subdivisions or edit the existing fallback.
400 ZONE_SUBDIVISION_TAKEN
Another zone already claims the subdivision.
409 SHIPPING_ADVANCED_REQUIRED
The persisted shipping mode must be advanced. First save shipping settings with mode=advanced and wait for success, then retry the zone or method request.
409 SHIPPING_ZONE_NAME_DUPLICATE
Another zone in this market already has this name.
409 SHIPPING_METHOD_NAME_DUPLICATE
Another method in this zone already has this name.
409 SHIPPING_ZONE_LIMIT_REACHED
The market has reached its published zone limit.
409 SHIPPING_METHOD_LIMIT_REACHED
The zone has reached its published method limit.
409 CONFIRMATION_REQUIRED
A destructive mode transition requires confirmation.
404 MARKET_NOT_FOUND
The market does not exist in this store.
404 SHIPPING_ZONE_NOT_FOUND
The shipping zone does not exist in this market.
404 SHIPPING_METHOD_NOT_FOUND
The shipping method does not exist in this zone.

Response

200

Sample response

{"success":true,"data":{"countries":[{"code":"DE","name":"Germany","fully_claimed":true,"claimed_subdivisions":[],"claimed_by_zone":"Germany"},{"code":"FR","name":"France","fully_claimed":false,"claimed_subdivisions":["FR-IDF"],"claimed_by_zone":"France regions"}],"total":2,"page":1,"per_page":20}}

List shipping zones

GET read_markets

List shipping zones.

Returns all zones in priority order, including the immutable default catch-all and each zone's method count.

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.
400 STORE_API_INVALID_REQUEST_BODY
The JSON request body is malformed.
400 SHIPPING_SETTINGS_TYPE_INVALID
The simple shipping type is not free, flat, or threshold.
400 TAX_CLASS_NOT_IN_MARKET
The selected tax class does not belong to this market.
400 SHIPPING_RATE_TYPE_INVALID
The method rate type is not a Store API-writable manual type.
400 SHIPPING_RATES_REQUIRED
This rate type requires at least one rate row.
400 SHIPPING_RATES_LIMIT
The method contains more rate rows than the published limit.
400 SHIPPING_RATE_FLAT_SINGLE
A flat method must contain exactly one rate row.
400 SHIPPING_RATE_PRICES_REQUIRED
A paid rate is missing its prices map.
400 SHIPPING_RATE_TIER_GAP
Tier boundaries do not cover a contiguous range beginning at zero.
400 SHIPPING_RATE_TIER_OVERLAP
Two tier boundaries overlap.
400 SHIPPING_RATE_COORDINATE_MISMATCH
A price-tier currency override is incomplete across its prices and boundaries.
400 SHIPPING_RATE_ITEM_COUNT_INVALID
An item-quantity boundary is not a valid whole number within the published limit.
400 SHIPPING_RATE_BASE_PRICE_REQUIRED
A rate is missing its required base-currency price.
400 SHIPPING_RATE_THRESHOLDS_REQUIRED
A price tier is missing its currency boundary maps.
400 SHIPPING_RATE_THRESHOLD_BASE_REQUIRED
A price tier is missing its required base-currency boundary.
400 SHIPPING_RATE_CURRENCY_UNKNOWN
A rate contains a currency that is not enabled for the market.
400 SHIPPING_RATE_PRICE_INVALID
A rate price is not a valid exact decimal.
400 SHIPPING_RATE_PRICE_NEGATIVE
A rate price is negative.
400 SHIPPING_RATE_PRICE_TOO_LARGE
A rate price exceeds the backend-published monetary limit.
400 SHIPPING_RATE_PRICE_TOO_PRECISE
A rate price exceeds that currency's decimal precision.
400 SHIPPING_RATE_THRESHOLD_INVALID
A price-tier boundary is not a valid exact decimal.
400 SHIPPING_RATE_THRESHOLD_NEGATIVE
A price-tier boundary is negative.
400 SHIPPING_RATE_THRESHOLD_TOO_LARGE
A price-tier boundary exceeds the backend-published monetary limit.
400 SHIPPING_RATE_THRESHOLD_TOO_PRECISE
A price-tier boundary exceeds that currency's decimal precision.
400 SHIPPING_RATE_MIN_INVALID
A weight or item tier minimum is invalid.
400 SHIPPING_RATE_MIN_NEGATIVE
A weight or item tier minimum is negative.
400 SHIPPING_RATE_MAX_INVALID
A weight or item tier maximum is invalid.
400 SHIPPING_RATE_MAX_NEGATIVE
A weight or item tier maximum is negative.
400 SHIPPING_RATE_MIN_ABOVE_MAX
A tier minimum is not below its maximum.
400 SHIPPING_RATE_DATA_INVALID
A stored rate violates the shipping contract.
400 SHIPPING_ZONE_DEFAULT_DELETE_LOCKED
The immutable default zone cannot be deleted.
400 SHIPPING_ZONE_DEFAULT_UNSET_LOCKED
The immutable default zone cannot be converted to an explicit zone.
400 SHIPPING_ZONE_DEFAULT_CREATE_LOCKED
Only the advanced-mode transition can create the default zone.
400 ZONE_COUNTRY_INVALID
A zone country does not belong to this market.
400 ZONE_SUBDIVISION_INVALID
A subdivision code is invalid.
400 ZONE_SUBDIVISION_NOT_IN_COUNTRY
A subdivision does not belong to a country selected in the zone.
400 ZONE_COUNTRY_TAKEN
Another zone already provides the fallback for this country. Select unclaimed subdivisions or edit the existing fallback.
400 ZONE_SUBDIVISION_TAKEN
Another zone already claims the subdivision.
409 SHIPPING_ADVANCED_REQUIRED
The persisted shipping mode must be advanced. First save shipping settings with mode=advanced and wait for success, then retry the zone or method request.
409 SHIPPING_ZONE_NAME_DUPLICATE
Another zone in this market already has this name.
409 SHIPPING_METHOD_NAME_DUPLICATE
Another method in this zone already has this name.
409 SHIPPING_ZONE_LIMIT_REACHED
The market has reached its published zone limit.
409 SHIPPING_METHOD_LIMIT_REACHED
The zone has reached its published method limit.
409 CONFIRMATION_REQUIRED
A destructive mode transition requires confirmation.
404 MARKET_NOT_FOUND
The market does not exist in this store.
404 SHIPPING_ZONE_NOT_FOUND
The shipping zone does not exist in this market.
404 SHIPPING_METHOD_NOT_FOUND
The shipping method does not exist in this zone.

Response

200

Sample response

{"success":true,"data":{"shipping_zones":[{"id":"7c9e4f2b-1a3d-4e5f-8b6c-2d0e1f3a4b5c","market_id":"9a1f2c3d-4e5f-6789-abcd-ef0123456789","name":"Germany","description":"Delivery across Germany","countries":["DE"],"subdivisions":[],"is_default":false,"priority":10,"method_count":2,"created_at":"2026-07-01T10:15:00+02:00","updated_at":"2026-07-08T18:40:00+02:00"}]}}

Create a shipping zone

POST write_markets

Create a shipping zone.

Creates a non-default country/subdivision claim. For each country, no selected subdivisions means its fallback coverage. A separate Uttar Pradesh zone may coexist with India and no subdivisions, in either creation order; India then covers the remaining states. Duplicate country fallbacks or explicit subdivisions are rejected. The default zone is created only by the advanced-mode transition.

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`	Zone name.
`description`	`string`	Zone description.
`countries`	`string[]`	ISO country codes. Each country without selected subdivisions is a fallback for its remaining regions.
`subdivisions`	`string[]`	Subdivision codes belonging to the selected countries. Explicit subdivision zones take precedence over country fallbacks. Duplicate subdivision claims are rejected.
`is_default`	`boolean`	Read-only invariant; false for create and unchanged for update.

Errors

400 STORE_API_INVALID_REQUEST_BODY
marketId must be a valid UUID.
400 STORE_API_INVALID_REQUEST_BODY
The JSON request body is malformed.
400 SHIPPING_SETTINGS_TYPE_INVALID
The simple shipping type is not free, flat, or threshold.
400 TAX_CLASS_NOT_IN_MARKET
The selected tax class does not belong to this market.
400 SHIPPING_RATE_TYPE_INVALID
The method rate type is not a Store API-writable manual type.
400 SHIPPING_RATES_REQUIRED
This rate type requires at least one rate row.
400 SHIPPING_RATES_LIMIT
The method contains more rate rows than the published limit.
400 SHIPPING_RATE_FLAT_SINGLE
A flat method must contain exactly one rate row.
400 SHIPPING_RATE_PRICES_REQUIRED
A paid rate is missing its prices map.
400 SHIPPING_RATE_TIER_GAP
Tier boundaries do not cover a contiguous range beginning at zero.
400 SHIPPING_RATE_TIER_OVERLAP
Two tier boundaries overlap.
400 SHIPPING_RATE_COORDINATE_MISMATCH
A price-tier currency override is incomplete across its prices and boundaries.
400 SHIPPING_RATE_ITEM_COUNT_INVALID
An item-quantity boundary is not a valid whole number within the published limit.
400 SHIPPING_RATE_BASE_PRICE_REQUIRED
A rate is missing its required base-currency price.
400 SHIPPING_RATE_THRESHOLDS_REQUIRED
A price tier is missing its currency boundary maps.
400 SHIPPING_RATE_THRESHOLD_BASE_REQUIRED
A price tier is missing its required base-currency boundary.
400 SHIPPING_RATE_CURRENCY_UNKNOWN
A rate contains a currency that is not enabled for the market.
400 SHIPPING_RATE_PRICE_INVALID
A rate price is not a valid exact decimal.
400 SHIPPING_RATE_PRICE_NEGATIVE
A rate price is negative.
400 SHIPPING_RATE_PRICE_TOO_LARGE
A rate price exceeds the backend-published monetary limit.
400 SHIPPING_RATE_PRICE_TOO_PRECISE
A rate price exceeds that currency's decimal precision.
400 SHIPPING_RATE_THRESHOLD_INVALID
A price-tier boundary is not a valid exact decimal.
400 SHIPPING_RATE_THRESHOLD_NEGATIVE
A price-tier boundary is negative.
400 SHIPPING_RATE_THRESHOLD_TOO_LARGE
A price-tier boundary exceeds the backend-published monetary limit.
400 SHIPPING_RATE_THRESHOLD_TOO_PRECISE
A price-tier boundary exceeds that currency's decimal precision.
400 SHIPPING_RATE_MIN_INVALID
A weight or item tier minimum is invalid.
400 SHIPPING_RATE_MIN_NEGATIVE
A weight or item tier minimum is negative.
400 SHIPPING_RATE_MAX_INVALID
A weight or item tier maximum is invalid.
400 SHIPPING_RATE_MAX_NEGATIVE
A weight or item tier maximum is negative.
400 SHIPPING_RATE_MIN_ABOVE_MAX
A tier minimum is not below its maximum.
400 SHIPPING_RATE_DATA_INVALID
A stored rate violates the shipping contract.
400 SHIPPING_ZONE_DEFAULT_DELETE_LOCKED
The immutable default zone cannot be deleted.
400 SHIPPING_ZONE_DEFAULT_UNSET_LOCKED
The immutable default zone cannot be converted to an explicit zone.
400 SHIPPING_ZONE_DEFAULT_CREATE_LOCKED
Only the advanced-mode transition can create the default zone.
400 ZONE_COUNTRY_INVALID
A zone country does not belong to this market.
400 ZONE_SUBDIVISION_INVALID
A subdivision code is invalid.
400 ZONE_SUBDIVISION_NOT_IN_COUNTRY
A subdivision does not belong to a country selected in the zone.
400 ZONE_COUNTRY_TAKEN
Another zone already provides the fallback for this country. Select unclaimed subdivisions or edit the existing fallback.
400 ZONE_SUBDIVISION_TAKEN
Another zone already claims the subdivision.
409 SHIPPING_ADVANCED_REQUIRED
The persisted shipping mode must be advanced. First save shipping settings with mode=advanced and wait for success, then retry the zone or method request.
409 SHIPPING_ZONE_NAME_DUPLICATE
Another zone in this market already has this name.
409 SHIPPING_METHOD_NAME_DUPLICATE
Another method in this zone already has this name.
409 SHIPPING_ZONE_LIMIT_REACHED
The market has reached its published zone limit.
409 SHIPPING_METHOD_LIMIT_REACHED
The zone has reached its published method limit.
409 CONFIRMATION_REQUIRED
A destructive mode transition requires confirmation.
404 MARKET_NOT_FOUND
The market does not exist in this store.
404 SHIPPING_ZONE_NOT_FOUND
The shipping zone does not exist in this market.
404 SHIPPING_METHOD_NOT_FOUND
The shipping method does not exist in this zone.

Response

201

Sample response

{"success":true,"data":{"shipping_zone":{"id":"7c9e4f2b-1a3d-4e5f-8b6c-2d0e1f3a4b5c","market_id":"9a1f2c3d-4e5f-6789-abcd-ef0123456789","name":"Germany","description":"Delivery across Germany","countries":["DE"],"subdivisions":[],"is_default":false,"priority":10,"method_count":2,"created_at":"2026-07-01T10:15:00+02:00","updated_at":"2026-07-08T18:40:00+02:00"}},"code":"SHIPPING_ZONE_CREATED","message":"Shipping zone created."}

Get a shipping zone

GET read_markets

Get a shipping zone.

Returns one zone in the market.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`
`zoneId` required	`uuid`	Shipping 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 STORE_API_INVALID_REQUEST_BODY
The JSON request body is malformed.
400 SHIPPING_SETTINGS_TYPE_INVALID
The simple shipping type is not free, flat, or threshold.
400 TAX_CLASS_NOT_IN_MARKET
The selected tax class does not belong to this market.
400 SHIPPING_RATE_TYPE_INVALID
The method rate type is not a Store API-writable manual type.
400 SHIPPING_RATES_REQUIRED
This rate type requires at least one rate row.
400 SHIPPING_RATES_LIMIT
The method contains more rate rows than the published limit.
400 SHIPPING_RATE_FLAT_SINGLE
A flat method must contain exactly one rate row.
400 SHIPPING_RATE_PRICES_REQUIRED
A paid rate is missing its prices map.
400 SHIPPING_RATE_TIER_GAP
Tier boundaries do not cover a contiguous range beginning at zero.
400 SHIPPING_RATE_TIER_OVERLAP
Two tier boundaries overlap.
400 SHIPPING_RATE_COORDINATE_MISMATCH
A price-tier currency override is incomplete across its prices and boundaries.
400 SHIPPING_RATE_ITEM_COUNT_INVALID
An item-quantity boundary is not a valid whole number within the published limit.
400 SHIPPING_RATE_BASE_PRICE_REQUIRED
A rate is missing its required base-currency price.
400 SHIPPING_RATE_THRESHOLDS_REQUIRED
A price tier is missing its currency boundary maps.
400 SHIPPING_RATE_THRESHOLD_BASE_REQUIRED
A price tier is missing its required base-currency boundary.
400 SHIPPING_RATE_CURRENCY_UNKNOWN
A rate contains a currency that is not enabled for the market.
400 SHIPPING_RATE_PRICE_INVALID
A rate price is not a valid exact decimal.
400 SHIPPING_RATE_PRICE_NEGATIVE
A rate price is negative.
400 SHIPPING_RATE_PRICE_TOO_LARGE
A rate price exceeds the backend-published monetary limit.
400 SHIPPING_RATE_PRICE_TOO_PRECISE
A rate price exceeds that currency's decimal precision.
400 SHIPPING_RATE_THRESHOLD_INVALID
A price-tier boundary is not a valid exact decimal.
400 SHIPPING_RATE_THRESHOLD_NEGATIVE
A price-tier boundary is negative.
400 SHIPPING_RATE_THRESHOLD_TOO_LARGE
A price-tier boundary exceeds the backend-published monetary limit.
400 SHIPPING_RATE_THRESHOLD_TOO_PRECISE
A price-tier boundary exceeds that currency's decimal precision.
400 SHIPPING_RATE_MIN_INVALID
A weight or item tier minimum is invalid.
400 SHIPPING_RATE_MIN_NEGATIVE
A weight or item tier minimum is negative.
400 SHIPPING_RATE_MAX_INVALID
A weight or item tier maximum is invalid.
400 SHIPPING_RATE_MAX_NEGATIVE
A weight or item tier maximum is negative.
400 SHIPPING_RATE_MIN_ABOVE_MAX
A tier minimum is not below its maximum.
400 SHIPPING_RATE_DATA_INVALID
A stored rate violates the shipping contract.
400 SHIPPING_ZONE_DEFAULT_DELETE_LOCKED
The immutable default zone cannot be deleted.
400 SHIPPING_ZONE_DEFAULT_UNSET_LOCKED
The immutable default zone cannot be converted to an explicit zone.
400 SHIPPING_ZONE_DEFAULT_CREATE_LOCKED
Only the advanced-mode transition can create the default zone.
400 ZONE_COUNTRY_INVALID
A zone country does not belong to this market.
400 ZONE_SUBDIVISION_INVALID
A subdivision code is invalid.
400 ZONE_SUBDIVISION_NOT_IN_COUNTRY
A subdivision does not belong to a country selected in the zone.
400 ZONE_COUNTRY_TAKEN
Another zone already provides the fallback for this country. Select unclaimed subdivisions or edit the existing fallback.
400 ZONE_SUBDIVISION_TAKEN
Another zone already claims the subdivision.
409 SHIPPING_ADVANCED_REQUIRED
The persisted shipping mode must be advanced. First save shipping settings with mode=advanced and wait for success, then retry the zone or method request.
409 SHIPPING_ZONE_NAME_DUPLICATE
Another zone in this market already has this name.
409 SHIPPING_METHOD_NAME_DUPLICATE
Another method in this zone already has this name.
409 SHIPPING_ZONE_LIMIT_REACHED
The market has reached its published zone limit.
409 SHIPPING_METHOD_LIMIT_REACHED
The zone has reached its published method limit.
409 CONFIRMATION_REQUIRED
A destructive mode transition requires confirmation.
404 MARKET_NOT_FOUND
The market does not exist in this store.
404 SHIPPING_ZONE_NOT_FOUND
The shipping zone does not exist in this market.
404 SHIPPING_METHOD_NOT_FOUND
The shipping method does not exist in this zone.

Response

200

Sample response

{"success":true,"data":{"shipping_zone":{"id":"7c9e4f2b-1a3d-4e5f-8b6c-2d0e1f3a4b5c","market_id":"9a1f2c3d-4e5f-6789-abcd-ef0123456789","name":"Germany","description":"Delivery across Germany","countries":["DE"],"subdivisions":[],"is_default":false,"priority":10,"method_count":2,"created_at":"2026-07-01T10:15:00+02:00","updated_at":"2026-07-08T18:40:00+02:00"}}}

Update a shipping zone

PUT write_markets

Update a shipping zone.

Replaces a zone definition. The default flag cannot be moved or cleared; the default zone cannot contain explicit regions.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`
`zoneId` required	`uuid`	Shipping zone ID.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`name` required	`string`	Zone name.
`description`	`string`	Zone description.
`countries`	`string[]`	ISO country codes. Each country without selected subdivisions is a fallback for its remaining regions.
`subdivisions`	`string[]`	Subdivision codes belonging to the selected countries. Explicit subdivision zones take precedence over country fallbacks. Duplicate subdivision claims are rejected.
`is_default`	`boolean`	Read-only invariant; false for create and unchanged for update.

Errors

400 STORE_API_INVALID_REQUEST_BODY
marketId must be a valid UUID.
400 STORE_API_INVALID_REQUEST_BODY
The JSON request body is malformed.
400 SHIPPING_SETTINGS_TYPE_INVALID
The simple shipping type is not free, flat, or threshold.
400 TAX_CLASS_NOT_IN_MARKET
The selected tax class does not belong to this market.
400 SHIPPING_RATE_TYPE_INVALID
The method rate type is not a Store API-writable manual type.
400 SHIPPING_RATES_REQUIRED
This rate type requires at least one rate row.
400 SHIPPING_RATES_LIMIT
The method contains more rate rows than the published limit.
400 SHIPPING_RATE_FLAT_SINGLE
A flat method must contain exactly one rate row.
400 SHIPPING_RATE_PRICES_REQUIRED
A paid rate is missing its prices map.
400 SHIPPING_RATE_TIER_GAP
Tier boundaries do not cover a contiguous range beginning at zero.
400 SHIPPING_RATE_TIER_OVERLAP
Two tier boundaries overlap.
400 SHIPPING_RATE_COORDINATE_MISMATCH
A price-tier currency override is incomplete across its prices and boundaries.
400 SHIPPING_RATE_ITEM_COUNT_INVALID
An item-quantity boundary is not a valid whole number within the published limit.
400 SHIPPING_RATE_BASE_PRICE_REQUIRED
A rate is missing its required base-currency price.
400 SHIPPING_RATE_THRESHOLDS_REQUIRED
A price tier is missing its currency boundary maps.
400 SHIPPING_RATE_THRESHOLD_BASE_REQUIRED
A price tier is missing its required base-currency boundary.
400 SHIPPING_RATE_CURRENCY_UNKNOWN
A rate contains a currency that is not enabled for the market.
400 SHIPPING_RATE_PRICE_INVALID
A rate price is not a valid exact decimal.
400 SHIPPING_RATE_PRICE_NEGATIVE
A rate price is negative.
400 SHIPPING_RATE_PRICE_TOO_LARGE
A rate price exceeds the backend-published monetary limit.
400 SHIPPING_RATE_PRICE_TOO_PRECISE
A rate price exceeds that currency's decimal precision.
400 SHIPPING_RATE_THRESHOLD_INVALID
A price-tier boundary is not a valid exact decimal.
400 SHIPPING_RATE_THRESHOLD_NEGATIVE
A price-tier boundary is negative.
400 SHIPPING_RATE_THRESHOLD_TOO_LARGE
A price-tier boundary exceeds the backend-published monetary limit.
400 SHIPPING_RATE_THRESHOLD_TOO_PRECISE
A price-tier boundary exceeds that currency's decimal precision.
400 SHIPPING_RATE_MIN_INVALID
A weight or item tier minimum is invalid.
400 SHIPPING_RATE_MIN_NEGATIVE
A weight or item tier minimum is negative.
400 SHIPPING_RATE_MAX_INVALID
A weight or item tier maximum is invalid.
400 SHIPPING_RATE_MAX_NEGATIVE
A weight or item tier maximum is negative.
400 SHIPPING_RATE_MIN_ABOVE_MAX
A tier minimum is not below its maximum.
400 SHIPPING_RATE_DATA_INVALID
A stored rate violates the shipping contract.
400 SHIPPING_ZONE_DEFAULT_DELETE_LOCKED
The immutable default zone cannot be deleted.
400 SHIPPING_ZONE_DEFAULT_UNSET_LOCKED
The immutable default zone cannot be converted to an explicit zone.
400 SHIPPING_ZONE_DEFAULT_CREATE_LOCKED
Only the advanced-mode transition can create the default zone.
400 ZONE_COUNTRY_INVALID
A zone country does not belong to this market.
400 ZONE_SUBDIVISION_INVALID
A subdivision code is invalid.
400 ZONE_SUBDIVISION_NOT_IN_COUNTRY
A subdivision does not belong to a country selected in the zone.
400 ZONE_COUNTRY_TAKEN
Another zone already provides the fallback for this country. Select unclaimed subdivisions or edit the existing fallback.
400 ZONE_SUBDIVISION_TAKEN
Another zone already claims the subdivision.
409 SHIPPING_ADVANCED_REQUIRED
The persisted shipping mode must be advanced. First save shipping settings with mode=advanced and wait for success, then retry the zone or method request.
409 SHIPPING_ZONE_NAME_DUPLICATE
Another zone in this market already has this name.
409 SHIPPING_METHOD_NAME_DUPLICATE
Another method in this zone already has this name.
409 SHIPPING_ZONE_LIMIT_REACHED
The market has reached its published zone limit.
409 SHIPPING_METHOD_LIMIT_REACHED
The zone has reached its published method limit.
409 CONFIRMATION_REQUIRED
A destructive mode transition requires confirmation.
404 MARKET_NOT_FOUND
The market does not exist in this store.
404 SHIPPING_ZONE_NOT_FOUND
The shipping zone does not exist in this market.
404 SHIPPING_METHOD_NOT_FOUND
The shipping method does not exist in this zone.

Response

200

Sample response

{"success":true,"data":{"shipping_zone":{"id":"7c9e4f2b-1a3d-4e5f-8b6c-2d0e1f3a4b5c","market_id":"9a1f2c3d-4e5f-6789-abcd-ef0123456789","name":"Germany","description":"Delivery across Germany","countries":["DE"],"subdivisions":[],"is_default":false,"priority":10,"method_count":2,"created_at":"2026-07-01T10:15:00+02:00","updated_at":"2026-07-08T18:40:00+02:00"}},"code":"SHIPPING_ZONE_UPDATED","message":"Shipping zone updated."}

Delete a shipping zone

DELETE write_markets

Delete a shipping zone.

Deletes a non-default zone and cascades its methods and rates. If the zone has methods, retry with the confirmation token returned by CONFIRMATION_REQUIRED.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`
`zoneId` required	`uuid`	Shipping zone ID.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`confirmed`	`boolean`	Set true only when retrying after CONFIRMATION_REQUIRED.
`confirmation_token`	`string`	Single-use token returned by CONFIRMATION_REQUIRED.

Errors

400 STORE_API_INVALID_REQUEST_BODY
marketId must be a valid UUID.
400 STORE_API_INVALID_REQUEST_BODY
The JSON request body is malformed.
400 SHIPPING_SETTINGS_TYPE_INVALID
The simple shipping type is not free, flat, or threshold.
400 TAX_CLASS_NOT_IN_MARKET
The selected tax class does not belong to this market.
400 SHIPPING_RATE_TYPE_INVALID
The method rate type is not a Store API-writable manual type.
400 SHIPPING_RATES_REQUIRED
This rate type requires at least one rate row.
400 SHIPPING_RATES_LIMIT
The method contains more rate rows than the published limit.
400 SHIPPING_RATE_FLAT_SINGLE
A flat method must contain exactly one rate row.
400 SHIPPING_RATE_PRICES_REQUIRED
A paid rate is missing its prices map.
400 SHIPPING_RATE_TIER_GAP
Tier boundaries do not cover a contiguous range beginning at zero.
400 SHIPPING_RATE_TIER_OVERLAP
Two tier boundaries overlap.
400 SHIPPING_RATE_COORDINATE_MISMATCH
A price-tier currency override is incomplete across its prices and boundaries.
400 SHIPPING_RATE_ITEM_COUNT_INVALID
An item-quantity boundary is not a valid whole number within the published limit.
400 SHIPPING_RATE_BASE_PRICE_REQUIRED
A rate is missing its required base-currency price.
400 SHIPPING_RATE_THRESHOLDS_REQUIRED
A price tier is missing its currency boundary maps.
400 SHIPPING_RATE_THRESHOLD_BASE_REQUIRED
A price tier is missing its required base-currency boundary.
400 SHIPPING_RATE_CURRENCY_UNKNOWN
A rate contains a currency that is not enabled for the market.
400 SHIPPING_RATE_PRICE_INVALID
A rate price is not a valid exact decimal.
400 SHIPPING_RATE_PRICE_NEGATIVE
A rate price is negative.
400 SHIPPING_RATE_PRICE_TOO_LARGE
A rate price exceeds the backend-published monetary limit.
400 SHIPPING_RATE_PRICE_TOO_PRECISE
A rate price exceeds that currency's decimal precision.
400 SHIPPING_RATE_THRESHOLD_INVALID
A price-tier boundary is not a valid exact decimal.
400 SHIPPING_RATE_THRESHOLD_NEGATIVE
A price-tier boundary is negative.
400 SHIPPING_RATE_THRESHOLD_TOO_LARGE
A price-tier boundary exceeds the backend-published monetary limit.
400 SHIPPING_RATE_THRESHOLD_TOO_PRECISE
A price-tier boundary exceeds that currency's decimal precision.
400 SHIPPING_RATE_MIN_INVALID
A weight or item tier minimum is invalid.
400 SHIPPING_RATE_MIN_NEGATIVE
A weight or item tier minimum is negative.
400 SHIPPING_RATE_MAX_INVALID
A weight or item tier maximum is invalid.
400 SHIPPING_RATE_MAX_NEGATIVE
A weight or item tier maximum is negative.
400 SHIPPING_RATE_MIN_ABOVE_MAX
A tier minimum is not below its maximum.
400 SHIPPING_RATE_DATA_INVALID
A stored rate violates the shipping contract.
400 SHIPPING_ZONE_DEFAULT_DELETE_LOCKED
The immutable default zone cannot be deleted.
400 SHIPPING_ZONE_DEFAULT_UNSET_LOCKED
The immutable default zone cannot be converted to an explicit zone.
400 SHIPPING_ZONE_DEFAULT_CREATE_LOCKED
Only the advanced-mode transition can create the default zone.
400 ZONE_COUNTRY_INVALID
A zone country does not belong to this market.
400 ZONE_SUBDIVISION_INVALID
A subdivision code is invalid.
400 ZONE_SUBDIVISION_NOT_IN_COUNTRY
A subdivision does not belong to a country selected in the zone.
400 ZONE_COUNTRY_TAKEN
Another zone already provides the fallback for this country. Select unclaimed subdivisions or edit the existing fallback.
400 ZONE_SUBDIVISION_TAKEN
Another zone already claims the subdivision.
409 SHIPPING_ADVANCED_REQUIRED
The persisted shipping mode must be advanced. First save shipping settings with mode=advanced and wait for success, then retry the zone or method request.
409 SHIPPING_ZONE_NAME_DUPLICATE
Another zone in this market already has this name.
409 SHIPPING_METHOD_NAME_DUPLICATE
Another method in this zone already has this name.
409 SHIPPING_ZONE_LIMIT_REACHED
The market has reached its published zone limit.
409 SHIPPING_METHOD_LIMIT_REACHED
The zone has reached its published method limit.
409 CONFIRMATION_REQUIRED
A destructive mode transition requires confirmation.
404 MARKET_NOT_FOUND
The market does not exist in this store.
404 SHIPPING_ZONE_NOT_FOUND
The shipping zone does not exist in this market.
404 SHIPPING_METHOD_NOT_FOUND
The shipping method does not exist in this zone.

Response

200

Sample response

{"success":true,"data":{"success":true},"code":"SHIPPING_ZONE_DELETED","message":"Shipping zone deleted."}

Get shipping method limits

GET read_markets

Get shipping method limits.

Returns live method name/description and rates-per-method limits.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`
`zoneId` required	`uuid`	Shipping 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 STORE_API_INVALID_REQUEST_BODY
The JSON request body is malformed.
400 SHIPPING_SETTINGS_TYPE_INVALID
The simple shipping type is not free, flat, or threshold.
400 TAX_CLASS_NOT_IN_MARKET
The selected tax class does not belong to this market.
400 SHIPPING_RATE_TYPE_INVALID
The method rate type is not a Store API-writable manual type.
400 SHIPPING_RATES_REQUIRED
This rate type requires at least one rate row.
400 SHIPPING_RATES_LIMIT
The method contains more rate rows than the published limit.
400 SHIPPING_RATE_FLAT_SINGLE
A flat method must contain exactly one rate row.
400 SHIPPING_RATE_PRICES_REQUIRED
A paid rate is missing its prices map.
400 SHIPPING_RATE_TIER_GAP
Tier boundaries do not cover a contiguous range beginning at zero.
400 SHIPPING_RATE_TIER_OVERLAP
Two tier boundaries overlap.
400 SHIPPING_RATE_COORDINATE_MISMATCH
A price-tier currency override is incomplete across its prices and boundaries.
400 SHIPPING_RATE_ITEM_COUNT_INVALID
An item-quantity boundary is not a valid whole number within the published limit.
400 SHIPPING_RATE_BASE_PRICE_REQUIRED
A rate is missing its required base-currency price.
400 SHIPPING_RATE_THRESHOLDS_REQUIRED
A price tier is missing its currency boundary maps.
400 SHIPPING_RATE_THRESHOLD_BASE_REQUIRED
A price tier is missing its required base-currency boundary.
400 SHIPPING_RATE_CURRENCY_UNKNOWN
A rate contains a currency that is not enabled for the market.
400 SHIPPING_RATE_PRICE_INVALID
A rate price is not a valid exact decimal.
400 SHIPPING_RATE_PRICE_NEGATIVE
A rate price is negative.
400 SHIPPING_RATE_PRICE_TOO_LARGE
A rate price exceeds the backend-published monetary limit.
400 SHIPPING_RATE_PRICE_TOO_PRECISE
A rate price exceeds that currency's decimal precision.
400 SHIPPING_RATE_THRESHOLD_INVALID
A price-tier boundary is not a valid exact decimal.
400 SHIPPING_RATE_THRESHOLD_NEGATIVE
A price-tier boundary is negative.
400 SHIPPING_RATE_THRESHOLD_TOO_LARGE
A price-tier boundary exceeds the backend-published monetary limit.
400 SHIPPING_RATE_THRESHOLD_TOO_PRECISE
A price-tier boundary exceeds that currency's decimal precision.
400 SHIPPING_RATE_MIN_INVALID
A weight or item tier minimum is invalid.
400 SHIPPING_RATE_MIN_NEGATIVE
A weight or item tier minimum is negative.
400 SHIPPING_RATE_MAX_INVALID
A weight or item tier maximum is invalid.
400 SHIPPING_RATE_MAX_NEGATIVE
A weight or item tier maximum is negative.
400 SHIPPING_RATE_MIN_ABOVE_MAX
A tier minimum is not below its maximum.
400 SHIPPING_RATE_DATA_INVALID
A stored rate violates the shipping contract.
400 SHIPPING_ZONE_DEFAULT_DELETE_LOCKED
The immutable default zone cannot be deleted.
400 SHIPPING_ZONE_DEFAULT_UNSET_LOCKED
The immutable default zone cannot be converted to an explicit zone.
400 SHIPPING_ZONE_DEFAULT_CREATE_LOCKED
Only the advanced-mode transition can create the default zone.
400 ZONE_COUNTRY_INVALID
A zone country does not belong to this market.
400 ZONE_SUBDIVISION_INVALID
A subdivision code is invalid.
400 ZONE_SUBDIVISION_NOT_IN_COUNTRY
A subdivision does not belong to a country selected in the zone.
400 ZONE_COUNTRY_TAKEN
Another zone already provides the fallback for this country. Select unclaimed subdivisions or edit the existing fallback.
400 ZONE_SUBDIVISION_TAKEN
Another zone already claims the subdivision.
409 SHIPPING_ADVANCED_REQUIRED
The persisted shipping mode must be advanced. First save shipping settings with mode=advanced and wait for success, then retry the zone or method request.
409 SHIPPING_ZONE_NAME_DUPLICATE
Another zone in this market already has this name.
409 SHIPPING_METHOD_NAME_DUPLICATE
Another method in this zone already has this name.
409 SHIPPING_ZONE_LIMIT_REACHED
The market has reached its published zone limit.
409 SHIPPING_METHOD_LIMIT_REACHED
The zone has reached its published method limit.
409 CONFIRMATION_REQUIRED
A destructive mode transition requires confirmation.
404 MARKET_NOT_FOUND
The market does not exist in this store.
404 SHIPPING_ZONE_NOT_FOUND
The shipping zone does not exist in this market.
404 SHIPPING_METHOD_NOT_FOUND
The shipping method does not exist in this zone.

Response

200

Sample response

{"success":true,"data":{"name_max_length":100,"description_max_length":500,"max_per_zone":50,"max_rates_per_method":20,"item_boundary_max":1000000}}

List shipping methods

GET read_markets

List shipping methods.

Returns methods and exact decimal rates for a zone. Price tiers use min_values/max_values per currency.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`
`zoneId` required	`uuid`	Shipping 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 STORE_API_INVALID_REQUEST_BODY
The JSON request body is malformed.
400 SHIPPING_SETTINGS_TYPE_INVALID
The simple shipping type is not free, flat, or threshold.
400 TAX_CLASS_NOT_IN_MARKET
The selected tax class does not belong to this market.
400 SHIPPING_RATE_TYPE_INVALID
The method rate type is not a Store API-writable manual type.
400 SHIPPING_RATES_REQUIRED
This rate type requires at least one rate row.
400 SHIPPING_RATES_LIMIT
The method contains more rate rows than the published limit.
400 SHIPPING_RATE_FLAT_SINGLE
A flat method must contain exactly one rate row.
400 SHIPPING_RATE_PRICES_REQUIRED
A paid rate is missing its prices map.
400 SHIPPING_RATE_TIER_GAP
Tier boundaries do not cover a contiguous range beginning at zero.
400 SHIPPING_RATE_TIER_OVERLAP
Two tier boundaries overlap.
400 SHIPPING_RATE_COORDINATE_MISMATCH
A price-tier currency override is incomplete across its prices and boundaries.
400 SHIPPING_RATE_ITEM_COUNT_INVALID
An item-quantity boundary is not a valid whole number within the published limit.
400 SHIPPING_RATE_BASE_PRICE_REQUIRED
A rate is missing its required base-currency price.
400 SHIPPING_RATE_THRESHOLDS_REQUIRED
A price tier is missing its currency boundary maps.
400 SHIPPING_RATE_THRESHOLD_BASE_REQUIRED
A price tier is missing its required base-currency boundary.
400 SHIPPING_RATE_CURRENCY_UNKNOWN
A rate contains a currency that is not enabled for the market.
400 SHIPPING_RATE_PRICE_INVALID
A rate price is not a valid exact decimal.
400 SHIPPING_RATE_PRICE_NEGATIVE
A rate price is negative.
400 SHIPPING_RATE_PRICE_TOO_LARGE
A rate price exceeds the backend-published monetary limit.
400 SHIPPING_RATE_PRICE_TOO_PRECISE
A rate price exceeds that currency's decimal precision.
400 SHIPPING_RATE_THRESHOLD_INVALID
A price-tier boundary is not a valid exact decimal.
400 SHIPPING_RATE_THRESHOLD_NEGATIVE
A price-tier boundary is negative.
400 SHIPPING_RATE_THRESHOLD_TOO_LARGE
A price-tier boundary exceeds the backend-published monetary limit.
400 SHIPPING_RATE_THRESHOLD_TOO_PRECISE
A price-tier boundary exceeds that currency's decimal precision.
400 SHIPPING_RATE_MIN_INVALID
A weight or item tier minimum is invalid.
400 SHIPPING_RATE_MIN_NEGATIVE
A weight or item tier minimum is negative.
400 SHIPPING_RATE_MAX_INVALID
A weight or item tier maximum is invalid.
400 SHIPPING_RATE_MAX_NEGATIVE
A weight or item tier maximum is negative.
400 SHIPPING_RATE_MIN_ABOVE_MAX
A tier minimum is not below its maximum.
400 SHIPPING_RATE_DATA_INVALID
A stored rate violates the shipping contract.
400 SHIPPING_ZONE_DEFAULT_DELETE_LOCKED
The immutable default zone cannot be deleted.
400 SHIPPING_ZONE_DEFAULT_UNSET_LOCKED
The immutable default zone cannot be converted to an explicit zone.
400 SHIPPING_ZONE_DEFAULT_CREATE_LOCKED
Only the advanced-mode transition can create the default zone.
400 ZONE_COUNTRY_INVALID
A zone country does not belong to this market.
400 ZONE_SUBDIVISION_INVALID
A subdivision code is invalid.
400 ZONE_SUBDIVISION_NOT_IN_COUNTRY
A subdivision does not belong to a country selected in the zone.
400 ZONE_COUNTRY_TAKEN
Another zone already provides the fallback for this country. Select unclaimed subdivisions or edit the existing fallback.
400 ZONE_SUBDIVISION_TAKEN
Another zone already claims the subdivision.
409 SHIPPING_ADVANCED_REQUIRED
The persisted shipping mode must be advanced. First save shipping settings with mode=advanced and wait for success, then retry the zone or method request.
409 SHIPPING_ZONE_NAME_DUPLICATE
Another zone in this market already has this name.
409 SHIPPING_METHOD_NAME_DUPLICATE
Another method in this zone already has this name.
409 SHIPPING_ZONE_LIMIT_REACHED
The market has reached its published zone limit.
409 SHIPPING_METHOD_LIMIT_REACHED
The zone has reached its published method limit.
409 CONFIRMATION_REQUIRED
A destructive mode transition requires confirmation.
404 MARKET_NOT_FOUND
The market does not exist in this store.
404 SHIPPING_ZONE_NOT_FOUND
The shipping zone does not exist in this market.
404 SHIPPING_METHOD_NOT_FOUND
The shipping method does not exist in this zone.

Response

200

Sample response

{"success":true,"data":{"shipping_methods":[{"id":"d36ec624-7128-4d79-88be-90254c265ac4","shipping_zone_id":"7c9e4f2b-1a3d-4e5f-8b6c-2d0e1f3a4b5c","name":"Standard delivery","description":"Delivered in 3 to 5 business days","tax_class_id":"4be5c5d1-0999-48ea-a2e0-f86703d99169","hsn_code":"9965","rate_type":"price","weight_unit":"g","is_active":true,"sort_order":1,"rates":[{"id":"ec15af06-a743-4a02-9923-e2e34573b376","shipping_method_id":"d36ec624-7128-4d79-88be-90254c265ac4","min_value":"0","max_value":"100","min_values":{"EUR":"0"},"max_values":{"EUR":"100.00"},"prices":{"EUR":"10.00"},"created_at":"2026-07-01T10:15:00+02:00","updated_at":"2026-07-08T18:40:00+02:00"},{"id":"f8eea159-9471-40a5-9c2b-c5829df9b663","shipping_method_id":"d36ec624-7128-4d79-88be-90254c265ac4","min_value":"100","max_value":null,"min_values":{"EUR":"100.00"},"max_values":{},"prices":{"EUR":"0"},"created_at":"2026-07-01T10:15:00+02:00","updated_at":"2026-07-08T18:40:00+02:00"}],"created_at":"2026-07-01T10:15:00+02:00","updated_at":"2026-07-08T18:40:00+02:00"}]}}

Create a shipping method

POST write_markets

Create a shipping method.

Creates free, flat, order-weight, order-value, item-count tiers (item), or per-item shipping (per_item). Per-item multiplies the unit charge by total shippable quantity before currency conversion and rounding. A matched weight, value, or quantity tier returns its configured shipping charge once. Every non-free rate requires a base-currency price. Other enabled currencies are optional exact overrides; absent overrides are converted from the base amount using the store currency conversion rate and rounding policy. Tier bounds are contiguous [min,max) ranges beginning at zero. Weight bounds use the saved weight_unit (g, kg, lb, or oz); create defaults to g. Value bounds are post-discount merchandise subtotals, and quantity bounds use the total shippable item quantity.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`
`zoneId` required	`uuid`	Shipping zone ID.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`name` required	`string`	Method name.
`description`	`string`	Method description.
`rate_type` required	`string`	free, flat, weight, price, item (item-count tiers), or per_item (unit charge multiplied by shippable quantity).
`weight_unit`	`string`	g, kg, lb, or oz. Defaults to g on create; omission preserves the current unit on update. Weight tier min_value/max_value are expressed in this saved method unit. Changing the unit reinterprets the supplied boundaries. Other rate types do not use the unit.
`is_active` required	`boolean`	Availability.
`tax_class_id`	`string\|null`	Shared market tax class.
`hsn_code`	`string`	Canonicalizable HS code.
`rates`	`array`	Exact-decimal tier rows. prices requires the base currency and may include exact overrides for other enabled currencies; absent overrides are converted. For tier methods, prices is the complete shipping charge. per_item instead requires exactly one price row with min_value=0 and max_value=null, no currency boundary maps; prices is a per-unit charge multiplied by total shippable quantity before FX rounding. Weight and item tiers use scalar min_value/max_value; weight bounds use the method's saved weight_unit and item bounds are quantities. Price tiers require base-currency min_values/max_values and may provide complete per-currency boundary overrides. All bounds use [min,max), begin at zero, and must be contiguous.

Errors

400 STORE_API_INVALID_REQUEST_BODY
marketId must be a valid UUID.
400 STORE_API_INVALID_REQUEST_BODY
The JSON request body is malformed.
400 SHIPPING_SETTINGS_TYPE_INVALID
The simple shipping type is not free, flat, or threshold.
400 TAX_CLASS_NOT_IN_MARKET
The selected tax class does not belong to this market.
400 SHIPPING_RATE_TYPE_INVALID
The method rate type is not a Store API-writable manual type.
400 SHIPPING_RATES_REQUIRED
This rate type requires at least one rate row.
400 SHIPPING_RATES_LIMIT
The method contains more rate rows than the published limit.
400 SHIPPING_RATE_FLAT_SINGLE
A flat method must contain exactly one rate row.
400 SHIPPING_RATE_PRICES_REQUIRED
A paid rate is missing its prices map.
400 SHIPPING_RATE_TIER_GAP
Tier boundaries do not cover a contiguous range beginning at zero.
400 SHIPPING_RATE_TIER_OVERLAP
Two tier boundaries overlap.
400 SHIPPING_RATE_COORDINATE_MISMATCH
A price-tier currency override is incomplete across its prices and boundaries.
400 SHIPPING_RATE_ITEM_COUNT_INVALID
An item-quantity boundary is not a valid whole number within the published limit.
400 SHIPPING_RATE_BASE_PRICE_REQUIRED
A rate is missing its required base-currency price.
400 SHIPPING_RATE_THRESHOLDS_REQUIRED
A price tier is missing its currency boundary maps.
400 SHIPPING_RATE_THRESHOLD_BASE_REQUIRED
A price tier is missing its required base-currency boundary.
400 SHIPPING_RATE_CURRENCY_UNKNOWN
A rate contains a currency that is not enabled for the market.
400 SHIPPING_RATE_PRICE_INVALID
A rate price is not a valid exact decimal.
400 SHIPPING_RATE_PRICE_NEGATIVE
A rate price is negative.
400 SHIPPING_RATE_PRICE_TOO_LARGE
A rate price exceeds the backend-published monetary limit.
400 SHIPPING_RATE_PRICE_TOO_PRECISE
A rate price exceeds that currency's decimal precision.
400 SHIPPING_RATE_THRESHOLD_INVALID
A price-tier boundary is not a valid exact decimal.
400 SHIPPING_RATE_THRESHOLD_NEGATIVE
A price-tier boundary is negative.
400 SHIPPING_RATE_THRESHOLD_TOO_LARGE
A price-tier boundary exceeds the backend-published monetary limit.
400 SHIPPING_RATE_THRESHOLD_TOO_PRECISE
A price-tier boundary exceeds that currency's decimal precision.
400 SHIPPING_RATE_MIN_INVALID
A weight or item tier minimum is invalid.
400 SHIPPING_RATE_MIN_NEGATIVE
A weight or item tier minimum is negative.
400 SHIPPING_RATE_MAX_INVALID
A weight or item tier maximum is invalid.
400 SHIPPING_RATE_MAX_NEGATIVE
A weight or item tier maximum is negative.
400 SHIPPING_RATE_MIN_ABOVE_MAX
A tier minimum is not below its maximum.
400 SHIPPING_RATE_DATA_INVALID
A stored rate violates the shipping contract.
400 SHIPPING_ZONE_DEFAULT_DELETE_LOCKED
The immutable default zone cannot be deleted.
400 SHIPPING_ZONE_DEFAULT_UNSET_LOCKED
The immutable default zone cannot be converted to an explicit zone.
400 SHIPPING_ZONE_DEFAULT_CREATE_LOCKED
Only the advanced-mode transition can create the default zone.
400 ZONE_COUNTRY_INVALID
A zone country does not belong to this market.
400 ZONE_SUBDIVISION_INVALID
A subdivision code is invalid.
400 ZONE_SUBDIVISION_NOT_IN_COUNTRY
A subdivision does not belong to a country selected in the zone.
400 ZONE_COUNTRY_TAKEN
Another zone already provides the fallback for this country. Select unclaimed subdivisions or edit the existing fallback.
400 ZONE_SUBDIVISION_TAKEN
Another zone already claims the subdivision.
409 SHIPPING_ADVANCED_REQUIRED
The persisted shipping mode must be advanced. First save shipping settings with mode=advanced and wait for success, then retry the zone or method request.
409 SHIPPING_ZONE_NAME_DUPLICATE
Another zone in this market already has this name.
409 SHIPPING_METHOD_NAME_DUPLICATE
Another method in this zone already has this name.
409 SHIPPING_ZONE_LIMIT_REACHED
The market has reached its published zone limit.
409 SHIPPING_METHOD_LIMIT_REACHED
The zone has reached its published method limit.
409 CONFIRMATION_REQUIRED
A destructive mode transition requires confirmation.
404 MARKET_NOT_FOUND
The market does not exist in this store.
404 SHIPPING_ZONE_NOT_FOUND
The shipping zone does not exist in this market.
404 SHIPPING_METHOD_NOT_FOUND
The shipping method does not exist in this zone.

Response

201

Sample response

{"success":true,"data":{"shipping_method":{"id":"d36ec624-7128-4d79-88be-90254c265ac4","shipping_zone_id":"7c9e4f2b-1a3d-4e5f-8b6c-2d0e1f3a4b5c","name":"Standard delivery","description":"Delivered in 3 to 5 business days","tax_class_id":"4be5c5d1-0999-48ea-a2e0-f86703d99169","hsn_code":"9965","rate_type":"price","weight_unit":"g","is_active":true,"sort_order":1,"rates":[{"id":"ec15af06-a743-4a02-9923-e2e34573b376","shipping_method_id":"d36ec624-7128-4d79-88be-90254c265ac4","min_value":"0","max_value":"100","min_values":{"EUR":"0"},"max_values":{"EUR":"100.00"},"prices":{"EUR":"10.00"},"created_at":"2026-07-01T10:15:00+02:00","updated_at":"2026-07-08T18:40:00+02:00"},{"id":"f8eea159-9471-40a5-9c2b-c5829df9b663","shipping_method_id":"d36ec624-7128-4d79-88be-90254c265ac4","min_value":"100","max_value":null,"min_values":{"EUR":"100.00"},"max_values":{},"prices":{"EUR":"0"},"created_at":"2026-07-01T10:15:00+02:00","updated_at":"2026-07-08T18:40:00+02:00"}],"created_at":"2026-07-01T10:15:00+02:00","updated_at":"2026-07-08T18:40:00+02:00"}},"code":"SHIPPING_METHOD_CREATED","message":"Shipping method created."}

Get a shipping method

GET read_markets

Get a shipping method.

Returns one method with its full rates.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`
`zoneId` required	`uuid`	Shipping zone ID.
`methodId` required	`uuid`	Shipping method 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 STORE_API_INVALID_REQUEST_BODY
The JSON request body is malformed.
400 SHIPPING_SETTINGS_TYPE_INVALID
The simple shipping type is not free, flat, or threshold.
400 TAX_CLASS_NOT_IN_MARKET
The selected tax class does not belong to this market.
400 SHIPPING_RATE_TYPE_INVALID
The method rate type is not a Store API-writable manual type.
400 SHIPPING_RATES_REQUIRED
This rate type requires at least one rate row.
400 SHIPPING_RATES_LIMIT
The method contains more rate rows than the published limit.
400 SHIPPING_RATE_FLAT_SINGLE
A flat method must contain exactly one rate row.
400 SHIPPING_RATE_PRICES_REQUIRED
A paid rate is missing its prices map.
400 SHIPPING_RATE_TIER_GAP
Tier boundaries do not cover a contiguous range beginning at zero.
400 SHIPPING_RATE_TIER_OVERLAP
Two tier boundaries overlap.
400 SHIPPING_RATE_COORDINATE_MISMATCH
A price-tier currency override is incomplete across its prices and boundaries.
400 SHIPPING_RATE_ITEM_COUNT_INVALID
An item-quantity boundary is not a valid whole number within the published limit.
400 SHIPPING_RATE_BASE_PRICE_REQUIRED
A rate is missing its required base-currency price.
400 SHIPPING_RATE_THRESHOLDS_REQUIRED
A price tier is missing its currency boundary maps.
400 SHIPPING_RATE_THRESHOLD_BASE_REQUIRED
A price tier is missing its required base-currency boundary.
400 SHIPPING_RATE_CURRENCY_UNKNOWN
A rate contains a currency that is not enabled for the market.
400 SHIPPING_RATE_PRICE_INVALID
A rate price is not a valid exact decimal.
400 SHIPPING_RATE_PRICE_NEGATIVE
A rate price is negative.
400 SHIPPING_RATE_PRICE_TOO_LARGE
A rate price exceeds the backend-published monetary limit.
400 SHIPPING_RATE_PRICE_TOO_PRECISE
A rate price exceeds that currency's decimal precision.
400 SHIPPING_RATE_THRESHOLD_INVALID
A price-tier boundary is not a valid exact decimal.
400 SHIPPING_RATE_THRESHOLD_NEGATIVE
A price-tier boundary is negative.
400 SHIPPING_RATE_THRESHOLD_TOO_LARGE
A price-tier boundary exceeds the backend-published monetary limit.
400 SHIPPING_RATE_THRESHOLD_TOO_PRECISE
A price-tier boundary exceeds that currency's decimal precision.
400 SHIPPING_RATE_MIN_INVALID
A weight or item tier minimum is invalid.
400 SHIPPING_RATE_MIN_NEGATIVE
A weight or item tier minimum is negative.
400 SHIPPING_RATE_MAX_INVALID
A weight or item tier maximum is invalid.
400 SHIPPING_RATE_MAX_NEGATIVE
A weight or item tier maximum is negative.
400 SHIPPING_RATE_MIN_ABOVE_MAX
A tier minimum is not below its maximum.
400 SHIPPING_RATE_DATA_INVALID
A stored rate violates the shipping contract.
400 SHIPPING_ZONE_DEFAULT_DELETE_LOCKED
The immutable default zone cannot be deleted.
400 SHIPPING_ZONE_DEFAULT_UNSET_LOCKED
The immutable default zone cannot be converted to an explicit zone.
400 SHIPPING_ZONE_DEFAULT_CREATE_LOCKED
Only the advanced-mode transition can create the default zone.
400 ZONE_COUNTRY_INVALID
A zone country does not belong to this market.
400 ZONE_SUBDIVISION_INVALID
A subdivision code is invalid.
400 ZONE_SUBDIVISION_NOT_IN_COUNTRY
A subdivision does not belong to a country selected in the zone.
400 ZONE_COUNTRY_TAKEN
Another zone already provides the fallback for this country. Select unclaimed subdivisions or edit the existing fallback.
400 ZONE_SUBDIVISION_TAKEN
Another zone already claims the subdivision.
409 SHIPPING_ADVANCED_REQUIRED
The persisted shipping mode must be advanced. First save shipping settings with mode=advanced and wait for success, then retry the zone or method request.
409 SHIPPING_ZONE_NAME_DUPLICATE
Another zone in this market already has this name.
409 SHIPPING_METHOD_NAME_DUPLICATE
Another method in this zone already has this name.
409 SHIPPING_ZONE_LIMIT_REACHED
The market has reached its published zone limit.
409 SHIPPING_METHOD_LIMIT_REACHED
The zone has reached its published method limit.
409 CONFIRMATION_REQUIRED
A destructive mode transition requires confirmation.
404 MARKET_NOT_FOUND
The market does not exist in this store.
404 SHIPPING_ZONE_NOT_FOUND
The shipping zone does not exist in this market.
404 SHIPPING_METHOD_NOT_FOUND
The shipping method does not exist in this zone.

Response

200

Sample response

{"success":true,"data":{"shipping_method":{"id":"d36ec624-7128-4d79-88be-90254c265ac4","shipping_zone_id":"7c9e4f2b-1a3d-4e5f-8b6c-2d0e1f3a4b5c","name":"Standard delivery","description":"Delivered in 3 to 5 business days","tax_class_id":"4be5c5d1-0999-48ea-a2e0-f86703d99169","hsn_code":"9965","rate_type":"price","weight_unit":"g","is_active":true,"sort_order":1,"rates":[{"id":"ec15af06-a743-4a02-9923-e2e34573b376","shipping_method_id":"d36ec624-7128-4d79-88be-90254c265ac4","min_value":"0","max_value":"100","min_values":{"EUR":"0"},"max_values":{"EUR":"100.00"},"prices":{"EUR":"10.00"},"created_at":"2026-07-01T10:15:00+02:00","updated_at":"2026-07-08T18:40:00+02:00"},{"id":"f8eea159-9471-40a5-9c2b-c5829df9b663","shipping_method_id":"d36ec624-7128-4d79-88be-90254c265ac4","min_value":"100","max_value":null,"min_values":{"EUR":"100.00"},"max_values":{},"prices":{"EUR":"0"},"created_at":"2026-07-01T10:15:00+02:00","updated_at":"2026-07-08T18:40:00+02:00"}],"created_at":"2026-07-01T10:15:00+02:00","updated_at":"2026-07-08T18:40:00+02:00"}}}

Update a shipping method

PUT write_markets

Update a shipping method.

Replaces a method and its complete rate set with the same validation rules as create.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`
`zoneId` required	`uuid`	Shipping zone ID.
`methodId` required	`uuid`	Shipping method ID.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`name` required	`string`	Method name.
`description`	`string`	Method description.
`rate_type` required	`string`	free, flat, weight, price, item (item-count tiers), or per_item (unit charge multiplied by shippable quantity).
`weight_unit`	`string`	g, kg, lb, or oz. Defaults to g on create; omission preserves the current unit on update. Weight tier min_value/max_value are expressed in this saved method unit. Changing the unit reinterprets the supplied boundaries. Other rate types do not use the unit.
`is_active` required	`boolean`	Availability.
`tax_class_id`	`string\|null`	Shared market tax class.
`hsn_code`	`string`	Canonicalizable HS code.
`rates`	`array`	Exact-decimal tier rows. prices requires the base currency and may include exact overrides for other enabled currencies; absent overrides are converted. For tier methods, prices is the complete shipping charge. per_item instead requires exactly one price row with min_value=0 and max_value=null, no currency boundary maps; prices is a per-unit charge multiplied by total shippable quantity before FX rounding. Weight and item tiers use scalar min_value/max_value; weight bounds use the method's saved weight_unit and item bounds are quantities. Price tiers require base-currency min_values/max_values and may provide complete per-currency boundary overrides. All bounds use [min,max), begin at zero, and must be contiguous.

Errors

400 STORE_API_INVALID_REQUEST_BODY
marketId must be a valid UUID.
400 STORE_API_INVALID_REQUEST_BODY
The JSON request body is malformed.
400 SHIPPING_SETTINGS_TYPE_INVALID
The simple shipping type is not free, flat, or threshold.
400 TAX_CLASS_NOT_IN_MARKET
The selected tax class does not belong to this market.
400 SHIPPING_RATE_TYPE_INVALID
The method rate type is not a Store API-writable manual type.
400 SHIPPING_RATES_REQUIRED
This rate type requires at least one rate row.
400 SHIPPING_RATES_LIMIT
The method contains more rate rows than the published limit.
400 SHIPPING_RATE_FLAT_SINGLE
A flat method must contain exactly one rate row.
400 SHIPPING_RATE_PRICES_REQUIRED
A paid rate is missing its prices map.
400 SHIPPING_RATE_TIER_GAP
Tier boundaries do not cover a contiguous range beginning at zero.
400 SHIPPING_RATE_TIER_OVERLAP
Two tier boundaries overlap.
400 SHIPPING_RATE_COORDINATE_MISMATCH
A price-tier currency override is incomplete across its prices and boundaries.
400 SHIPPING_RATE_ITEM_COUNT_INVALID
An item-quantity boundary is not a valid whole number within the published limit.
400 SHIPPING_RATE_BASE_PRICE_REQUIRED
A rate is missing its required base-currency price.
400 SHIPPING_RATE_THRESHOLDS_REQUIRED
A price tier is missing its currency boundary maps.
400 SHIPPING_RATE_THRESHOLD_BASE_REQUIRED
A price tier is missing its required base-currency boundary.
400 SHIPPING_RATE_CURRENCY_UNKNOWN
A rate contains a currency that is not enabled for the market.
400 SHIPPING_RATE_PRICE_INVALID
A rate price is not a valid exact decimal.
400 SHIPPING_RATE_PRICE_NEGATIVE
A rate price is negative.
400 SHIPPING_RATE_PRICE_TOO_LARGE
A rate price exceeds the backend-published monetary limit.
400 SHIPPING_RATE_PRICE_TOO_PRECISE
A rate price exceeds that currency's decimal precision.
400 SHIPPING_RATE_THRESHOLD_INVALID
A price-tier boundary is not a valid exact decimal.
400 SHIPPING_RATE_THRESHOLD_NEGATIVE
A price-tier boundary is negative.
400 SHIPPING_RATE_THRESHOLD_TOO_LARGE
A price-tier boundary exceeds the backend-published monetary limit.
400 SHIPPING_RATE_THRESHOLD_TOO_PRECISE
A price-tier boundary exceeds that currency's decimal precision.
400 SHIPPING_RATE_MIN_INVALID
A weight or item tier minimum is invalid.
400 SHIPPING_RATE_MIN_NEGATIVE
A weight or item tier minimum is negative.
400 SHIPPING_RATE_MAX_INVALID
A weight or item tier maximum is invalid.
400 SHIPPING_RATE_MAX_NEGATIVE
A weight or item tier maximum is negative.
400 SHIPPING_RATE_MIN_ABOVE_MAX
A tier minimum is not below its maximum.
400 SHIPPING_RATE_DATA_INVALID
A stored rate violates the shipping contract.
400 SHIPPING_ZONE_DEFAULT_DELETE_LOCKED
The immutable default zone cannot be deleted.
400 SHIPPING_ZONE_DEFAULT_UNSET_LOCKED
The immutable default zone cannot be converted to an explicit zone.
400 SHIPPING_ZONE_DEFAULT_CREATE_LOCKED
Only the advanced-mode transition can create the default zone.
400 ZONE_COUNTRY_INVALID
A zone country does not belong to this market.
400 ZONE_SUBDIVISION_INVALID
A subdivision code is invalid.
400 ZONE_SUBDIVISION_NOT_IN_COUNTRY
A subdivision does not belong to a country selected in the zone.
400 ZONE_COUNTRY_TAKEN
Another zone already provides the fallback for this country. Select unclaimed subdivisions or edit the existing fallback.
400 ZONE_SUBDIVISION_TAKEN
Another zone already claims the subdivision.
409 SHIPPING_ADVANCED_REQUIRED
The persisted shipping mode must be advanced. First save shipping settings with mode=advanced and wait for success, then retry the zone or method request.
409 SHIPPING_ZONE_NAME_DUPLICATE
Another zone in this market already has this name.
409 SHIPPING_METHOD_NAME_DUPLICATE
Another method in this zone already has this name.
409 SHIPPING_ZONE_LIMIT_REACHED
The market has reached its published zone limit.
409 SHIPPING_METHOD_LIMIT_REACHED
The zone has reached its published method limit.
409 CONFIRMATION_REQUIRED
A destructive mode transition requires confirmation.
404 MARKET_NOT_FOUND
The market does not exist in this store.
404 SHIPPING_ZONE_NOT_FOUND
The shipping zone does not exist in this market.
404 SHIPPING_METHOD_NOT_FOUND
The shipping method does not exist in this zone.

Response

200

Sample response

{"success":true,"data":{"shipping_method":{"id":"d36ec624-7128-4d79-88be-90254c265ac4","shipping_zone_id":"7c9e4f2b-1a3d-4e5f-8b6c-2d0e1f3a4b5c","name":"Standard delivery","description":"Delivered in 3 to 5 business days","tax_class_id":"4be5c5d1-0999-48ea-a2e0-f86703d99169","hsn_code":"9965","rate_type":"price","weight_unit":"g","is_active":true,"sort_order":1,"rates":[{"id":"ec15af06-a743-4a02-9923-e2e34573b376","shipping_method_id":"d36ec624-7128-4d79-88be-90254c265ac4","min_value":"0","max_value":"100","min_values":{"EUR":"0"},"max_values":{"EUR":"100.00"},"prices":{"EUR":"10.00"},"created_at":"2026-07-01T10:15:00+02:00","updated_at":"2026-07-08T18:40:00+02:00"},{"id":"f8eea159-9471-40a5-9c2b-c5829df9b663","shipping_method_id":"d36ec624-7128-4d79-88be-90254c265ac4","min_value":"100","max_value":null,"min_values":{"EUR":"100.00"},"max_values":{},"prices":{"EUR":"0"},"created_at":"2026-07-01T10:15:00+02:00","updated_at":"2026-07-08T18:40:00+02:00"}],"created_at":"2026-07-01T10:15:00+02:00","updated_at":"2026-07-08T18:40:00+02:00"}},"code":"SHIPPING_METHOD_UPDATED","message":"Shipping method updated."}

Delete a shipping method

DELETE write_markets

Delete a shipping method.

Deletes a method and all of its rates. If rates exist, retry with the confirmation token returned by CONFIRMATION_REQUIRED.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`
`zoneId` required	`uuid`	Shipping zone ID.
`methodId` required	`uuid`	Shipping method ID.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`confirmed`	`boolean`	Set true only when retrying after CONFIRMATION_REQUIRED.
`confirmation_token`	`string`	Single-use token returned by CONFIRMATION_REQUIRED.

Errors

400 STORE_API_INVALID_REQUEST_BODY
marketId must be a valid UUID.
400 STORE_API_INVALID_REQUEST_BODY
The JSON request body is malformed.
400 SHIPPING_SETTINGS_TYPE_INVALID
The simple shipping type is not free, flat, or threshold.
400 TAX_CLASS_NOT_IN_MARKET
The selected tax class does not belong to this market.
400 SHIPPING_RATE_TYPE_INVALID
The method rate type is not a Store API-writable manual type.
400 SHIPPING_RATES_REQUIRED
This rate type requires at least one rate row.
400 SHIPPING_RATES_LIMIT
The method contains more rate rows than the published limit.
400 SHIPPING_RATE_FLAT_SINGLE
A flat method must contain exactly one rate row.
400 SHIPPING_RATE_PRICES_REQUIRED
A paid rate is missing its prices map.
400 SHIPPING_RATE_TIER_GAP
Tier boundaries do not cover a contiguous range beginning at zero.
400 SHIPPING_RATE_TIER_OVERLAP
Two tier boundaries overlap.
400 SHIPPING_RATE_COORDINATE_MISMATCH
A price-tier currency override is incomplete across its prices and boundaries.
400 SHIPPING_RATE_ITEM_COUNT_INVALID
An item-quantity boundary is not a valid whole number within the published limit.
400 SHIPPING_RATE_BASE_PRICE_REQUIRED
A rate is missing its required base-currency price.
400 SHIPPING_RATE_THRESHOLDS_REQUIRED
A price tier is missing its currency boundary maps.
400 SHIPPING_RATE_THRESHOLD_BASE_REQUIRED
A price tier is missing its required base-currency boundary.
400 SHIPPING_RATE_CURRENCY_UNKNOWN
A rate contains a currency that is not enabled for the market.
400 SHIPPING_RATE_PRICE_INVALID
A rate price is not a valid exact decimal.
400 SHIPPING_RATE_PRICE_NEGATIVE
A rate price is negative.
400 SHIPPING_RATE_PRICE_TOO_LARGE
A rate price exceeds the backend-published monetary limit.
400 SHIPPING_RATE_PRICE_TOO_PRECISE
A rate price exceeds that currency's decimal precision.
400 SHIPPING_RATE_THRESHOLD_INVALID
A price-tier boundary is not a valid exact decimal.
400 SHIPPING_RATE_THRESHOLD_NEGATIVE
A price-tier boundary is negative.
400 SHIPPING_RATE_THRESHOLD_TOO_LARGE
A price-tier boundary exceeds the backend-published monetary limit.
400 SHIPPING_RATE_THRESHOLD_TOO_PRECISE
A price-tier boundary exceeds that currency's decimal precision.
400 SHIPPING_RATE_MIN_INVALID
A weight or item tier minimum is invalid.
400 SHIPPING_RATE_MIN_NEGATIVE
A weight or item tier minimum is negative.
400 SHIPPING_RATE_MAX_INVALID
A weight or item tier maximum is invalid.
400 SHIPPING_RATE_MAX_NEGATIVE
A weight or item tier maximum is negative.
400 SHIPPING_RATE_MIN_ABOVE_MAX
A tier minimum is not below its maximum.
400 SHIPPING_RATE_DATA_INVALID
A stored rate violates the shipping contract.
400 SHIPPING_ZONE_DEFAULT_DELETE_LOCKED
The immutable default zone cannot be deleted.
400 SHIPPING_ZONE_DEFAULT_UNSET_LOCKED
The immutable default zone cannot be converted to an explicit zone.
400 SHIPPING_ZONE_DEFAULT_CREATE_LOCKED
Only the advanced-mode transition can create the default zone.
400 ZONE_COUNTRY_INVALID
A zone country does not belong to this market.
400 ZONE_SUBDIVISION_INVALID
A subdivision code is invalid.
400 ZONE_SUBDIVISION_NOT_IN_COUNTRY
A subdivision does not belong to a country selected in the zone.
400 ZONE_COUNTRY_TAKEN
Another zone already provides the fallback for this country. Select unclaimed subdivisions or edit the existing fallback.
400 ZONE_SUBDIVISION_TAKEN
Another zone already claims the subdivision.
409 SHIPPING_ADVANCED_REQUIRED
The persisted shipping mode must be advanced. First save shipping settings with mode=advanced and wait for success, then retry the zone or method request.
409 SHIPPING_ZONE_NAME_DUPLICATE
Another zone in this market already has this name.
409 SHIPPING_METHOD_NAME_DUPLICATE
Another method in this zone already has this name.
409 SHIPPING_ZONE_LIMIT_REACHED
The market has reached its published zone limit.
409 SHIPPING_METHOD_LIMIT_REACHED
The zone has reached its published method limit.
409 CONFIRMATION_REQUIRED
A destructive mode transition requires confirmation.
404 MARKET_NOT_FOUND
The market does not exist in this store.
404 SHIPPING_ZONE_NOT_FOUND
The shipping zone does not exist in this market.
404 SHIPPING_METHOD_NOT_FOUND
The shipping method does not exist in this zone.

Response

200

Sample response

{"success":true,"data":{"success":true},"code":"SHIPPING_METHOD_DELETED","message":"Shipping method deleted."}

Shipping settings updated

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

Fired when a market's shipping mode or simple shipping settings change.

Payload fields

Field	Type	Description
`shipping_settings.id`	`string`	Always present
`shipping_settings.market_id`	`string`	Selectable in the Payload builder
`shipping_settings.mode`	`string`	Selectable in the Payload builder
`shipping_settings.shipping_type`	`string`	Selectable in the Payload builder
`shipping_settings.flat_rate`	`object`	Selectable in the Payload builder
`shipping_settings.free_threshold`	`object`	Selectable in the Payload builder
`shipping_settings.threshold_rate`	`object`	Selectable in the Payload builder
`shipping_settings.tax_class_id`	`string`	Selectable in the Payload builder
`shipping_settings.hsn_code`	`string`	Selectable in the Payload builder
`shipping_settings.created_at`	`string`	Selectable in the Payload builder
`shipping_settings.updated_at`	`string`	Selectable in the Payload builder

Payload shape

Sample payload

{
  "shipping_settings": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "flat_rate": "...",
    "free_threshold": "...",
    "hsn_code": "...",
    "id": "...",
    "market_id": "...",
    "mode": "...",
    "shipping_type": "...",
    "tax_class_id": null,
    "threshold_rate": "...",
    "updated_at": "2026-06-09T12:00:00+05:30"
  }
}

Shipping zone created

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

Fired when a shipping zone is created in a market.

Payload fields

Field	Type	Description
`shipping_zone.id`	`string`	Always present
`shipping_zone.market_id`	`string`	Selectable in the Payload builder
`shipping_zone.name`	`string`	Selectable in the Payload builder
`shipping_zone.description`	`string`	Selectable in the Payload builder
`shipping_zone.countries`	`array`	Selectable in the Payload builder
`shipping_zone.subdivisions`	`array`	Selectable in the Payload builder
`shipping_zone.is_default`	`boolean`	Selectable in the Payload builder
`shipping_zone.priority`	`integer`	Selectable in the Payload builder
`shipping_zone.created_at`	`string`	Selectable in the Payload builder
`shipping_zone.updated_at`	`string`	Selectable in the Payload builder

Payload shape

Sample payload

{
  "shipping_zone": {
    "countries": [],
    "created_at": "2026-06-09T12:00:00+05:30",
    "description": "...",
    "id": "...",
    "is_default": false,
    "market_id": "...",
    "name": "...",
    "priority": 0,
    "subdivisions": [],
    "updated_at": "2026-06-09T12:00:00+05:30"
  }
}

Shipping zone updated

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

Fired when a shipping zone changes.

Payload fields

Field	Type	Description
`shipping_zone.id`	`string`	Always present
`shipping_zone.market_id`	`string`	Selectable in the Payload builder
`shipping_zone.name`	`string`	Selectable in the Payload builder
`shipping_zone.description`	`string`	Selectable in the Payload builder
`shipping_zone.countries`	`array`	Selectable in the Payload builder
`shipping_zone.subdivisions`	`array`	Selectable in the Payload builder
`shipping_zone.is_default`	`boolean`	Selectable in the Payload builder
`shipping_zone.priority`	`integer`	Selectable in the Payload builder
`shipping_zone.created_at`	`string`	Selectable in the Payload builder
`shipping_zone.updated_at`	`string`	Selectable in the Payload builder

Payload shape

Sample payload

{
  "shipping_zone": {
    "countries": [],
    "created_at": "2026-06-09T12:00:00+05:30",
    "description": "...",
    "id": "...",
    "is_default": false,
    "market_id": "...",
    "name": "...",
    "priority": 0,
    "subdivisions": [],
    "updated_at": "2026-06-09T12:00:00+05:30"
  }
}

Shipping zone deleted

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

Fired when a shipping zone is deleted.

Payload fields

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

Payload shape

Sample payload

{
  "shipping_zone": {
    "id": "...",
    "market_id": "...",
    "name": "..."
  }
}

Shipping method created

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

Fired when a shipping method and its rates are created.

Payload fields

Field	Type	Description
`shipping_method.id`	`string`	Always present
`shipping_method.market_id`	`string`	Selectable in the Payload builder
`shipping_method.shipping_zone_id`	`string`	Selectable in the Payload builder
`shipping_method.name`	`string`	Selectable in the Payload builder
`shipping_method.description`	`string`	Selectable in the Payload builder
`shipping_method.tax_class_id`	`string`	Selectable in the Payload builder
`shipping_method.hsn_code`	`string`	Selectable in the Payload builder
`shipping_method.rate_type`	`string`	Selectable in the Payload builder free, flat, weight, price, item (one charge for the matching quantity tier), or per_item (unit charge multiplied by shippable quantity before currency conversion and rounding).
`shipping_method.weight_unit`	`string`	Selectable in the Payload builder Saved weight-tier unit: g, kg, lb, or oz. Bounds use this unit. Other rate types ignore it.
`shipping_method.is_active`	`boolean`	Selectable in the Payload builder
`shipping_method.sort_order`	`integer`	Selectable in the Payload builder
`shipping_method.rates[*].id`	`string`	Selectable in the Payload builder
`shipping_method.rates[*].min_value`	`string`	Selectable in the Payload builder Inclusive minimum and exclusive maximum. Weight bounds use the saved weight_unit; item bounds use shippable quantity. per_item uses one row beginning at zero with no upper bound. An absent maximum means unbounded.
`shipping_method.rates[*].max_value`	`string`	Selectable in the Payload builder Inclusive minimum and exclusive maximum. Weight bounds use the saved weight_unit; item bounds use shippable quantity. per_item uses one row beginning at zero with no upper bound. An absent maximum means unbounded.
`shipping_method.rates[*].min_values`	`object`	Selectable in the Payload builder
`shipping_method.rates[*].max_values`	`object`	Selectable in the Payload builder
`shipping_method.rates[*].prices`	`object`	Selectable in the Payload builder Exact-decimal currency map. For per_item these are per-unit charges; for tier methods these are complete shipping charges. Missing currency overrides use base-currency conversion.
`shipping_method.created_at`	`string`	Selectable in the Payload builder
`shipping_method.updated_at`	`string`	Selectable in the Payload builder

Payload shape

Sample payload

{
  "shipping_method": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "description": "...",
    "hsn_code": "...",
    "id": "d36ec624-7128-4d79-88be-90254c265ac4",
    "is_active": true,
    "market_id": "9a1f2c3d-4e5f-6789-abcd-ef0123456789",
    "name": "Weight-based delivery",
    "rate_type": "weight",
    "rates": [
      {
        "id": "ec15af06-a743-4a02-9923-e2e34573b376",
        "max_value": "2",
        "min_value": "0",
        "prices": {
          "EUR": "5.00"
        }
      },
      {
        "id": "f8eea159-9471-40a5-9c2b-c5829df9b663",
        "min_value": "2",
        "prices": {
          "EUR": "10.00"
        }
      }
    ],
    "shipping_zone_id": "7c9e4f2b-1a3d-4e5f-8b6c-2d0e1f3a4b5c",
    "sort_order": 0,
    "tax_class_id": null,
    "updated_at": "2026-06-09T12:00:00+05:30",
    "weight_unit": "kg"
  }
}

Shipping method updated

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

Fired when a shipping method or its rates change.

Payload fields

Field	Type	Description
`shipping_method.id`	`string`	Always present
`shipping_method.market_id`	`string`	Selectable in the Payload builder
`shipping_method.shipping_zone_id`	`string`	Selectable in the Payload builder
`shipping_method.name`	`string`	Selectable in the Payload builder
`shipping_method.description`	`string`	Selectable in the Payload builder
`shipping_method.tax_class_id`	`string`	Selectable in the Payload builder
`shipping_method.hsn_code`	`string`	Selectable in the Payload builder
`shipping_method.rate_type`	`string`	Selectable in the Payload builder free, flat, weight, price, item (one charge for the matching quantity tier), or per_item (unit charge multiplied by shippable quantity before currency conversion and rounding).
`shipping_method.weight_unit`	`string`	Selectable in the Payload builder Saved weight-tier unit: g, kg, lb, or oz. Bounds use this unit. Other rate types ignore it.
`shipping_method.is_active`	`boolean`	Selectable in the Payload builder
`shipping_method.sort_order`	`integer`	Selectable in the Payload builder
`shipping_method.rates[*].id`	`string`	Selectable in the Payload builder
`shipping_method.rates[*].min_value`	`string`	Selectable in the Payload builder Inclusive minimum and exclusive maximum. Weight bounds use the saved weight_unit; item bounds use shippable quantity. per_item uses one row beginning at zero with no upper bound. An absent maximum means unbounded.
`shipping_method.rates[*].max_value`	`string`	Selectable in the Payload builder Inclusive minimum and exclusive maximum. Weight bounds use the saved weight_unit; item bounds use shippable quantity. per_item uses one row beginning at zero with no upper bound. An absent maximum means unbounded.
`shipping_method.rates[*].min_values`	`object`	Selectable in the Payload builder
`shipping_method.rates[*].max_values`	`object`	Selectable in the Payload builder
`shipping_method.rates[*].prices`	`object`	Selectable in the Payload builder Exact-decimal currency map. For per_item these are per-unit charges; for tier methods these are complete shipping charges. Missing currency overrides use base-currency conversion.
`shipping_method.created_at`	`string`	Selectable in the Payload builder
`shipping_method.updated_at`	`string`	Selectable in the Payload builder

Payload shape

Sample payload

{
  "shipping_method": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "description": "...",
    "hsn_code": "...",
    "id": "d36ec624-7128-4d79-88be-90254c265ac4",
    "is_active": true,
    "market_id": "9a1f2c3d-4e5f-6789-abcd-ef0123456789",
    "name": "Weight-based delivery",
    "rate_type": "weight",
    "rates": [
      {
        "id": "ec15af06-a743-4a02-9923-e2e34573b376",
        "max_value": "2",
        "min_value": "0",
        "prices": {
          "EUR": "5.00"
        }
      },
      {
        "id": "f8eea159-9471-40a5-9c2b-c5829df9b663",
        "min_value": "2",
        "prices": {
          "EUR": "10.00"
        }
      }
    ],
    "shipping_zone_id": "7c9e4f2b-1a3d-4e5f-8b6c-2d0e1f3a4b5c",
    "sort_order": 0,
    "tax_class_id": null,
    "updated_at": "2026-06-09T12:00:00+05:30",
    "weight_unit": "kg"
  }
}

Shipping method deleted

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

Fired when a shipping method is deleted.

Payload fields

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

Payload shape

Sample payload

{
  "shipping_method": {
    "id": "...",
    "market_id": "...",
    "name": "..."
  }
}

Endpoints#

Path parameters

Headers

Errors

Path parameters

Headers

Body parameters

Errors

Path parameters

Headers

Errors

Path parameters

Query parameters

Headers

Errors

Path parameters

Headers

Errors

Path parameters

Headers

Body parameters

Errors

Path parameters

Headers

Errors

Path parameters

Headers

Body parameters

Errors

Path parameters

Headers

Body parameters

Errors

Path parameters

Headers

Errors

Path parameters

Headers

Errors

Path parameters

Headers

Body parameters

Errors

Path parameters

Headers

Errors

Path parameters

Headers

Body parameters

Errors

Path parameters

Headers

Body parameters

Errors

Webhook events#

Payload fields

Payload fields

Payload fields

Payload fields

Payload fields

Payload fields

Payload fields