Region API

The Region API manages geographic sales regions that control currency, tax configuration, payment providers, and fulfillment options for different markets.

Region Structure

{
  "id": "reg_north_america",
  "name": "North America",
  "currency": "USD",
  "taxIncluded": false,
  "taxProviderId": "txprov_auto",
  "countries": [
    {"code": "US", "name": "United States"},
    {"code": "CA", "name": "Canada"}
  ],
  "paymentProviders": ["stripe", "paypal"],
  "fulfillmentProviders": ["manual", "fedex"],
  "metadata": {},
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-15T08:00:00Z"
}

Endpoints

List Regions

GET /region

Query Parameters:

Parameter	Type	Description
`page`	number	Page number
`display`	number	Items per page
`sort`	string	Sort field
`currency`	string	Filter by currency code

curl "https://api.hanzo.ai/region" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "count": 3,
  "models": [
    {
      "id": "reg_north_america",
      "name": "North America",
      "currency": "USD",
      "countryCount": 2
    },
    {
      "id": "reg_europe",
      "name": "Europe",
      "currency": "EUR",
      "countryCount": 27
    }
  ]
}

Get Region

GET /region/:id

curl https://api.hanzo.ai/region/reg_north_america \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Create Region

POST /region

curl -X POST https://api.hanzo.ai/region \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Europe",
    "currency": "EUR",
    "taxIncluded": true,
    "taxProviderId": "txprov_auto",
    "paymentProviders": ["stripe"],
    "fulfillmentProviders": ["manual", "dhl"],
    "countries": [
      {"code": "DE"},
      {"code": "FR"},
      {"code": "IT"},
      {"code": "ES"}
    ]
  }'

Update Region

PUT /region/:id

curl -X PUT https://api.hanzo.ai/region/reg_europe \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "European Union",
    "taxIncluded": true
  }'

Delete Region

DELETE /region/:id

curl -X DELETE https://api.hanzo.ai/region/reg_europe \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Country Management

List Region Countries

GET /region/:id/countries

curl https://api.hanzo.ai/region/reg_europe/countries \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "count": 27,
  "models": [
    {"code": "DE", "name": "Germany"},
    {"code": "FR", "name": "France"},
    {"code": "IT", "name": "Italy"}
  ]
}

Add Countries to Region

POST /region/:id/countries

curl -X POST https://api.hanzo.ai/region/reg_europe/countries \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "countries": [
      {"code": "NL"},
      {"code": "BE"},
      {"code": "AT"}
    ]
  }'

Remove Country from Region

DELETE /region/:id/countries/:code

curl -X DELETE https://api.hanzo.ai/region/reg_europe/countries/AT \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Sales Channels

Regions can be associated with sales channels to control product visibility:

curl -X POST https://api.hanzo.ai/region/reg_europe/saleschannel \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "salesChannelIds": ["sc_web_eu", "sc_mobile_eu"]
  }'

Stock Locations

Link regions to stock locations for fulfillment routing:

curl -X POST https://api.hanzo.ai/region/reg_europe/stocklocation \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stockLocationIds": ["sloc_berlin", "sloc_paris"]
  }'

A country can only belong to one region at a time. Attempting to add a country that already exists in another region returns a 409 Conflict error.

SDK Examples

JavaScript

import { Commerce } from '@hanzo/commerce'

const commerce = new Commerce({ apiKey: 'your_key' })

// Create region
const region = await commerce.regions.create({
  name: 'Europe',
  currency: 'EUR',
  taxIncluded: true,
  countries: [{ code: 'DE' }, { code: 'FR' }]
})

// Add countries
await commerce.regions.addCountries(region.id, {
  countries: [{ code: 'NL' }, { code: 'BE' }]
})

// Remove country
await commerce.regions.removeCountry(region.id, 'BE')

Go

region, err := client.Regions.Create(ctx, &sdk.RegionInput{
    Name:     "Europe",
    Currency: "EUR",
    TaxIncluded: true,
    Countries: []sdk.CountryInput{
        {Code: "DE"},
        {Code: "FR"},
    },
})

err = client.Regions.AddCountries(ctx, region.ID, []sdk.CountryInput{
    {Code: "NL"},
    {Code: "BE"},
})

On this page