Fulfillment

This guide walks through configuring the fulfillment pipeline in Hanzo Commerce, from creating shipping profiles and zones to processing shipments and tracking deliveries.

Overview

The fulfillment system has four layers:

Shipping Profile → Fulfillment Set → Service Zone → Shipping Option

Shipping Profile: Groups products with similar shipping requirements

Fulfillment Set: Represents a warehouse or distribution center

Service Zone: Defines geographic delivery areas

Shipping Option: Pricing and delivery estimates for a zone

Step 1: Create a Shipping Profile

Shipping profiles let you apply different shipping rules to different product groups (e.g., heavy items, fragile goods).

curl -X POST https://api.hanzo.ai/shippingprofile \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Standard Items",
    "type": "default"
  }'

const profile = await commerce.fulfillment.createProfile({
  name: 'Standard Items',
  type: 'default'
})

Step 2: Create a Fulfillment Set

Link a fulfillment set to a stock location (warehouse):

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

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

Step 3: Configure Service Zones

Define where each fulfillment set can deliver. Use geo zones to specify coverage:

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

const zone = await commerce.fulfillment.createServiceZone({
  name: 'US West Coast',
  fulfillmentSetId: fset.id,
  geoZones: [{
    type: 'state',
    country: 'US',
    states: ['CA', 'OR', 'WA', 'NV']
  }]
})

Step 4: Add Shipping Options

Create shipping options with pricing for each service zone:

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"
  }'

For weight-based pricing, use rules:

curl -X POST https://api.hanzo.ai/shippingoption \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Heavy Items Ground",
    "serviceZoneId": "sz_west01",
    "priceType": "calculated",
    "rules": [
      {"attribute": "weight", "operator": "lte", "value": 10, "price": 999},
      {"attribute": "weight", "operator": "lte", "value": 30, "price": 1999},
      {"attribute": "weight", "operator": "lte", "value": 50, "price": 2999}
    ],
    "currency": "USD",
    "estimatedDays": "7-10"
  }'

Step 5: Process Fulfillments

When an order is ready to ship, create a fulfillment:

curl -X POST https://api.hanzo.ai/order/order_abc123/fulfill \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"itemId": "item_001", "quantity": 2}
    ],
    "tracking": {
      "carrier": "ups",
      "number": "1Z999AA10123456784",
      "url": "https://ups.com/track?num=1Z999AA10123456784"
    },
    "notifyCustomer": true
  }'

await commerce.orders.fulfill(order.id, {
  items: [{ itemId: 'item_001', quantity: 2 }],
  tracking: {
    carrier: 'ups',
    number: '1Z999AA10123456784'
  },
  notifyCustomer: true
})

Tracking Shipments

Query fulfillment status for an order:

curl "https://api.hanzo.ai/order/order_abc123?expand=fulfillments" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The response includes all fulfillments with tracking details:

{
  "fulfillments": [
    {
      "id": "ful_abc123",
      "status": "shipped",
      "tracking": {
        "carrier": "ups",
        "number": "1Z999AA10123456784",
        "url": "https://ups.com/track?num=1Z999AA10123456784"
      },
      "shippedAt": "2024-01-16T09:00:00Z"
    }
  ]
}

For partial fulfillments, ship items as they become available. Each fulfillment tracks its own items and carrier. The order's fulfillmentStatus updates to partially_fulfilled until all items are shipped.

Cancelling a Fulfillment

If a shipment needs to be cancelled before delivery:

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

This restocks the inventory and notifies the customer automatically.

On this page