Shipping Zones API — Create, List & Retrieve Zones

Zones are the geographic building blocks of the Ship Quote rate engine. Each zone groups one or more destination province admin codes under a single name — for example, Cayco’s ZONA 1 covers only Madrid (ES-M), while its ZONA 7 spans eight north-western provinces. When a quote request arrives with a destination postal code or province, the engine resolves the province’s admin code, finds the matching zone for the active agency, and uses that zone name to look up the correct price row in the agency’s rate table. Postal code exceptions — which override the default zone for specific postal code ranges within a province — are stored in a separate ZoneRules collection, not on the zone document itself. Tecum, for example, redirects certain postal codes in Guadalajara (ES-GU) to ZONA 2 instead of the province’s default zone, enabling fine-grained pricing for rural or remote areas. See the bootstrap reference below for sample ZoneRules data.

Each zone is agency-scoped via agencyId. An agency’s zone set must be complete — every province it serves should be covered by at least one zone, otherwise the rate engine will return no quote for destinations in uncovered provinces.

POST /api/v1/zones

Create a new zone for an agency. The pricingMode and volumetric fields are set to their model defaults on creation; use the bootstrap utilities to set custom values during data seeding.

Request body

agencyId

string

required

MongoDB ObjectId of the agency this zone belongs to.

name

string

required

Zone identifier as it appears in the agency’s rate table (e.g. "ZONA 1", "ZONA 3", "ZONA 21", "NACIONAL"). This value is used verbatim as the lookup key when pricing a shipment.

provinces

array

List of province admin full codes covered by this zone. Each entry must be a string in the format "CC-ADMINCODE" matching the adminFullCode field in the locations collection (e.g. "ES-M" for Madrid, "ES-B" for Barcelona). A zone may cover multiple provinces or none (for special zones such as international or unassigned tiers).

calculationMode

string

Controls which rate table the engine consults when pricing a shipment destined for this zone. Accepted values:

"pallet" — use the pallet rate table (default)
"parcel" — use the parcel rate table

Response — 201 Created

string

MongoDB ObjectId of the newly created zone.

agencyId

string

ObjectId of the owning agency. The GET endpoints populate this with name and code from the agency document.

name

string

Zone name as stored.

provinces

array

Array of province admin full codes covered by this zone.

calculationMode

string

"pallet" or "parcel".

volumetric

object

Volumetric weight configuration for this zone.

Show volumetric fields

volumetric.enabled

boolean

Whether volumetric weight calculation is active for this zone. Defaults to false.

volumetric.factor

number

Divisor used to convert cubic centimetres to a volumetric weight in kg. Defaults to 200.

pricingMode

object

Internal pricing configuration applied by the engine for this zone. Set automatically by the server; not accepted as a POST request body field.

Show pricingMode fields

pricingMode.type

string

"weight" — price based on gross weight only. "weight_volume" — price based on the greater of gross weight and volumetric weight. Cayco’s ZONA 11 and ZONA 12 (Andalucia) use "weight_volume".

pricingMode.tonnagePricingRule

object

Tonnage threshold rule applied for heavy shipments.

Show tonnagePricingRule fields

pricingMode.tonnagePricingRule.enabled

boolean

Whether the tonnage rule is active for this zone. Defaults to false.

pricingMode.tonnagePricingRule.threshold

number

Weight threshold in kg above which the per-tonne rate applies. Defaults to 2001.

pricingMode.tonnagePricingRule.unit

string

Pricing unit label. Defaults to "€/ton".

createdAt

string

ISO 8601 creation timestamp.

updatedAt

string

ISO 8601 last-updated timestamp.

Error responses

Status	Condition
`400 Bad Request`	`agencyId` or `name` is missing, or the request body is malformed.

Examples

curl -X POST http://localhost:3000/api/v1/zones \
  -H "Content-Type: application/json" \
  -d '{
    "agencyId": "507f1f77bcf86cd799439011",
    "name": "ZONA 3",
    "provinces": ["ES-AV", "ES-GU", "ES-SG", "ES-VA"],
    "calculationMode": "pallet"
  }'

GET /api/v1/zones

Return all zones across all agencies. The agencyId field is populated with the agency’s name and code for convenience. Returns 404 when no zone documents exist in the collection.

Response — 200 OK

An array of zone objects. Each object matches the POST 201 response shape above, with agencyId expanded to include name and code.

Example

curl -X GET http://localhost:3000/api/v1/zones

GET /api/v1/zones/:zoneId

Retrieve the details of a single zone by its MongoDB ObjectId. The agencyId field is populated with the agency’s name and code.

Path parameters

zoneId

string

required

MongoDB ObjectId of the zone to retrieve.

Response — 200 OK

A single zone object (same shape as the POST 201 response, with agencyId populated).

Error responses

Status	Condition
`404 Not Found`	No zone document exists with the given `zoneId`.

Example

curl -X GET http://localhost:3000/api/v1/zones/684b3a1cbe9876543210dcba

Bootstrap reference — real zone definitions

The tables below show the zones loaded by the built-in seed data for Cayco and Tecum, giving concrete examples of how province admin codes are grouped into pricing tiers.

Cayco zones

Zone	Provinces	Pricing mode
ZONA 1	ES-M	weight
ZONA 2	ES-TO	weight
ZONA 3	ES-AV, ES-GU, ES-SG, ES-VA	weight
ZONA 4	ES-VI, ES-A, ES-BU, ES-CS, ES-LE, ES-LO, ES-MU, ES-SA, ES-SO, ES-TE, ES-V, ES-Z, ES-CR	weight
ZONA 5	ES-O, ES-S, ES-CU, ES-SS, ES-NA, ES-BI, ES-P, ES-AB, ES-ZA	weight
ZONA 6	ES-B, ES-HU, ES-T	weight
ZONA 7	ES-C, ES-GI, ES-LU, ES-OR, ES-PO, ES-CC, ES-BA, ES-L	weight
ZONA 11	ES-AL, ES-J, ES-MA	weight_volume (Andalucia)
ZONA 12	ES-SE, ES-CO	weight_volume (Andalucia)

Cayco’s ZONA 11 and ZONA 12 cover Andalucia and use pricingMode.type = "weight_volume" with volumetric.enabled = true and a tonnage threshold of 1 001 kg. Shipments to these zones are priced using a per-kilogram rate table rather than the standard pallet tier table.

Tecum zones

Zone	Provinces
ZONA 1	ES-GU, ES-M
ZONA 2	ES-SO, ES-TO
ZONA 3	ES-AV, ES-BU, ES-LO, ES-SG, ES-VA, ES-Z
ZONA 4	ES-VI, ES-HU, ES-LE, ES-NA, ES-P, ES-SA, ES-TE, ES-V, ES-ZA
ZONA 5	ES-CS, ES-SS, ES-L, ES-O, ES-S, ES-T, ES-BI
ZONA 6	ES-B, ES-CC
ZONA 7	ES-C, ES-GI, ES-LU, ES-OR, ES-PO
ZONA 8	(empty — reserved tier)
ZONA 9	ES-IB-ML
ZONA 10	ES-IB-IB, ES-IB-MN
ZONA 11	ES-GC-GC, ES-TF-TE
ZONA 12	ES-GC-FU, ES-GC-LA, ES-TF-LP, ES-TF-LG, ES-TF-EH
ZONA 13	PT-Madeira
ZONA 14	PT-São Miguel
ZONA 16	ES-GR
ZONA 17	ES-GR
ZONA 21	ES-J
ZONA 22	ES-CO
ZONA 23	ES-AB, ES-AL, ES-CR, ES-SE, ES-MA
ZONA 24	ES-BA, ES-CU, ES-H, ES-MU
ZONA 25	ES-A, ES-CA

ZONA 16 and ZONA 17 both list ES-GR (Granada) as their province. The engine uses ZoneRules postal code range records to decide which of the two zones applies to a given Granada postal code — postal codes 18001–18330 route to ZONA 16; all other Granada addresses resolve to ZONA 17.

Tecum ZoneRules — postal code range overrides (sample)

Postal code exceptions are stored in the ZoneRules collection, not on the zone document. Each ZoneRules record links a province, a target zone, and an array of postal code ranges. The sample below shows the Guadalajara (ES-GU) and León (ES-LE) overrides loaded by the Tecum bootstrap.

[
  { "province": "ES-GU", "zoneName": "ZONA 2", "postalCodeRanges": [
    { "from": "19261", "to": "19261" },
    { "from": "19280", "to": "19287" },
    { "from": "19300", "to": "19392" },
    { "from": "19432", "to": "19445" },
    { "from": "19460", "to": "19463" },
    { "from": "19492", "to": "19492" },
    { "from": "19495", "to": "19495" }
  ]},
  { "province": "ES-LE", "zoneName": "ZONA 6", "postalCodeRanges": [
    { "from": "24100", "to": "24114" },
    { "from": "24300", "to": "24319" },
    { "from": "24360", "to": "24380" }
  ]},
  { "province": "ES-GR", "zoneName": "ZONA 16", "postalCodeRanges": [
    { "from": "18001", "to": "18015" },
    { "from": "18100", "to": "18199" },
    { "from": "18200", "to": "18330" }
  ]}
]

Rates

Agencies

Locations

Pallets & Zones

Shipping Zones API — Create, List & Retrieve Zones

POST /api/v1/zones

Request body

Response — 201 Created

Error responses

Examples

GET /api/v1/zones

Response — 200 OK

Example

GET /api/v1/zones/:zoneId

Path parameters

Response — 200 OK

Error responses

Example

Bootstrap reference — real zone definitions

Cayco zones

Tecum zones

Tecum ZoneRules — postal code range overrides (sample)

Build docs developers (and LLMs) love

Rates

Agencies

Locations

Pallets & Zones

Documentation Index

​POST /api/v1/zones

​Request body

​Response — 201 Created

​Error responses

​Examples

​GET /api/v1/zones

​Response — 200 OK

​Example

​GET /api/v1/zones/:zoneId

​Path parameters

​Response — 200 OK

​Error responses

​Example

​Bootstrap reference — real zone definitions

​Cayco zones

​Tecum zones

​Tecum ZoneRules — postal code range overrides (sample)

Build docs developers (and LLMs) love

POST /api/v1/zones

Request body

Response — 201 Created

Error responses

Examples

GET /api/v1/zones

Response — 200 OK

Example

GET /api/v1/zones/:zoneId

Path parameters

Response — 200 OK

Error responses

Example

Bootstrap reference — real zone definitions

Cayco zones

Tecum zones

Tecum ZoneRules — postal code range overrides (sample)