Skip to content

Create Delivery Zone ​

Use this endpoint to create a new delivery zone. A delivery zone defines the delivery fee and estimated delivery time for a specific country, states, and coverage areas.

Endpoint ​

POST /v1/delivery-zones

Authentication ​

  • Requires merchant authentication: Authorization: Bearer JWT_TOKEN.
  • Requires X-MerchantApiKey: MERCHANT_API_KEY.

Headers ​

json
{
  "Authorization": "Bearer JWT_TOKEN",
  "X-MerchantApiKey": "MERCHANT_API_KEY",
  "Content-Type": "application/json"
}

Request body ​

ParameterTypeRequiredDescription
namestringYesName of the delivery zone (e.g. "Lagos Mainland").
feenumberYesDelivery fee for this zone. Must be 0 or greater.
stateAreasarrayYesList of states and their corresponding coverage areas.
countrystringNoCountry name. Defaults to "Nigeria" if omitted.
estimatedDeliveryTimestringNoDelivery duration estimate (e.g. "1-2 business days").
activebooleanNoWhether the zone is active immediately. Defaults to true.

stateAreas items ​

ParameterTypeRequiredDescription
statestringYesName of the state (e.g. "Lagos").
areasarray of stringsYesNames of covered areas within the state.

Example request ​

javascript
fetch('https://api.shopsynch.com/v1/delivery-zones', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer JWT_TOKEN',
    'X-MerchantApiKey': 'MERCHANT_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Lagos Mainland",
    country: "Nigeria",
    fee: 1500.0,
    estimatedDeliveryTime: "1-2 business days",
    stateAreas: [
      {
        state: "Lagos",
        areas: ["Ikeja", "Surulere", "Yaba", "Maryland"]
      }
    ],
    active: true
  })
})
  .then(response => response.json())
  .then(data => console.log(data));

Response 200 ​

json
{
  "status": true,
  "message": "Delivery zone created successfully",
  "data": {
    "id": "67a6261a320f3f7368dfec99",
    "name": "Lagos Mainland",
    "country": "Nigeria",
    "fee": 1500.0,
    "estimatedDeliveryTime": "1-2 business days",
    "active": true,
    "stateAreas": [
      {
        "state": "Lagos",
        "areas": ["Ikeja", "Surulere", "Yaba", "Maryland"]
      }
    ],
    "overlappingZones": []
  }
}

Error responses ​

StatusMessage
400Please enter a name for the delivery zone.
400Please specify the delivery fee.
400Please select at least one state and its corresponding coverage areas.
401Unauthorized

Next steps ​

Build with joy