Fulfillment API

The Fulfillment API manages the complete shipping and delivery pipeline, including fulfillment sets, service zones, geo zones, shipping options, and shipment tracking.

Fulfillment Structure

{
  "id": "ful_abc123",
  "orderId": "order_xyz789",
  "status": "shipped",
  "items": [
    {
      "itemId": "item_001",
      "quantity": 2
    }
  ],
  "tracking": {
    "carrier": "fedex",
    "number": "794644790138",
    "url": "https://fedex.com/track?num=794644790138"
  },
  "shippedAt": "2024-01-16T09:00:00Z",
  "deliveredAt": null,
  "createdAt": "2024-01-15T10:30:00Z"
}

Fulfillment Sets

A fulfillment set groups service zones and shipping logic for a warehouse or distribution center.

List Fulfillment Sets

GET /fulfillmentset

curl "https://api.hanzo.ai/fulfillmentset?display=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Create Fulfillment Set

POST /fulfillmentset

curl -X POST https://api.hanzo.ai/fulfillmentset \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "US West Coast Warehouse",
    "type": "shipping",
    "stockLocationId": "sloc_wc001"
  }'

Get / Update / Delete Fulfillment Set

GET /fulfillmentset/:id | PUT /fulfillmentset/:id | DELETE /fulfillmentset/:id

Service Zones

Service zones define geographic areas a fulfillment set can deliver to.

Create Service Zone

POST /servicezone

curl -X POST https://api.hanzo.ai/servicezone \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "US West",
    "fulfillmentSetId": "fset_wc001",
    "geoZones": [
      {
        "type": "state",
        "country": "US",
        "states": ["CA", "OR", "WA", "NV", "AZ"]
      }
    ]
  }'

Geo Zones

Geo zones define geographic boundaries by country, state, city, or postal code.

Create Geo Zone

POST /geozone

curl -X POST https://api.hanzo.ai/geozone \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "California Metro",
    "type": "zip",
    "country": "US",
    "postalCodes": ["90*", "91*", "94*", "95*"]
  }'

Geo Zone Types:

Type	Description
`country`	Entire countries
`state`	States or provinces
`city`	Specific cities
`zip`	Postal code patterns (supports wildcards)

Shipping Options

List Shipping Options

GET /shippingoption

curl "https://api.hanzo.ai/shippingoption?serviceZoneId=sz_west01" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Create Shipping Option

POST /shippingoption

curl -X POST https://api.hanzo.ai/shippingoption \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Standard Ground",
    "serviceZoneId": "sz_west01",
    "priceType": "flat",
    "amount": 599,
    "currency": "USD",
    "estimatedDays": "5-7",
    "rules": [
      {
        "attribute": "weight",
        "operator": "lte",
        "value": 50
      }
    ]
  }'

Shipping Option Rules:

Attribute	Operators	Description
`weight`	`lte`, `gte`	Package weight in lbs
`subtotal`	`lte`, `gte`	Cart subtotal in cents
`itemCount`	`lte`, `gte`	Number of items

Update / Delete Shipping Option

PUT /shippingoption/:id | DELETE /shippingoption/:id

Shipping Profiles

Shipping profiles attach shipping rules to product groups.

Create Shipping Profile

POST /shippingprofile

curl -X POST https://api.hanzo.ai/shippingprofile \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Heavy Items",
    "type": "custom",
    "productIds": ["prod_abc123", "prod_def456"]
  }'

Ship a Fulfillment

POST /fulfillment/:id/ship

curl -X POST https://api.hanzo.ai/fulfillment/ful_abc123/ship \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "carrier": "ups",
    "trackingNumber": "1Z999AA10123456784",
    "trackingUrl": "https://ups.com/track?num=1Z999AA10123456784",
    "notifyCustomer": true
  }'

Cancel a Fulfillment

POST /fulfillment/:id/cancel

curl -X POST https://api.hanzo.ai/fulfillment/ful_abc123/cancel \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "out_of_stock",
    "restockItems": true
  }'

Cancelling a fulfillment automatically restocks inventory when restockItems is true and triggers a customer notification.

SDK Examples

JavaScript

import { Commerce } from '@hanzo/commerce'

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

// Create fulfillment set
const fset = await commerce.fulfillment.createSet({
  name: 'US West Coast Warehouse',
  type: 'shipping',
  stockLocationId: 'sloc_wc001'
})

// Ship a fulfillment
await commerce.fulfillment.ship('ful_abc123', {
  carrier: 'ups',
  trackingNumber: '1Z999AA10123456784',
  notifyCustomer: true
})

Go

fset, err := client.Fulfillment.CreateSet(ctx, &sdk.FulfillmentSetInput{
    Name:            "US West Coast Warehouse",
    Type:            "shipping",
    StockLocationID: "sloc_wc001",
})

err = client.Fulfillment.Ship(ctx, "ful_abc123", &sdk.ShipInput{
    Carrier:        "ups",
    TrackingNumber: "1Z999AA10123456784",
    NotifyCustomer: true,
})

On this page