Hanzo
CommerceGuides

Orders

Complete order lifecycle management with fulfillment and returns

The Order API handles the complete order lifecycle from creation through fulfillment, including status tracking, payment processing, and returns.

Order Structure

{
  "id": "order_abc123",
  "number": "HZ-10042",
  "userId": "user_xyz789",
  "status": "confirmed",
  "paymentStatus": "paid",
  "fulfillmentStatus": "unfulfilled",
  "items": [
    {
      "id": "item_001",
      "productId": "prod_abc123",
      "variantId": "var_xyz789",
      "name": "Premium T-Shirt",
      "sku": "SHIRT-BLK-M",
      "quantity": 2,
      "price": 2999,
      "subtotal": 5998
    }
  ],
  "subtotal": 5998,
  "discount": 500,
  "tax": 481,
  "shipping": 599,
  "total": 6578,
  "shippingAddress": {...},
  "billingAddress": {...},
  "payments": [...],
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:35:00Z"
}

Order Status Flow

created -> confirmed -> processing -> shipped -> delivered
                    \-> cancelled
                    \-> returned (partial or full)

Status Descriptions

StatusDescription
createdOrder created, awaiting payment
confirmedPayment received, ready for processing
processingOrder being prepared for shipment
shippedOrder shipped, tracking available
deliveredOrder delivered to customer
cancelledOrder cancelled
returnedOrder returned (partial or full)

Creating Orders

From Cart

curl -X POST https://api.hanzo.ai/order \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cartId": "cart_abc123",
    "shippingAddress": {
      "firstName": "John",
      "lastName": "Doe",
      "line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94102",
      "country": "US"
    },
    "billingAddress": {
      "sameAsShipping": true
    }
  }'

Direct Order

curl -X POST https://api.hanzo.ai/order \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "productId": "prod_abc123",
        "variantId": "var_xyz789",
        "quantity": 2
      }
    ],
    "shippingAddress": {...},
    "shippingMethod": "standard"
  }'

Retrieving Orders

Get Single Order

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

List Orders

# All orders (admin)
curl "https://api.hanzo.ai/order?limit=20&status=confirmed" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# User's orders
curl "https://api.hanzo.ai/account/order" \
  -H "Authorization: Bearer USER_ACCESS_TOKEN"

Query Parameters

ParameterDescription
statusFilter by order status
paymentStatusFilter by payment status
fulfillmentStatusFilter by fulfillment status
sinceOrders created after date
untilOrders created before date
limitResults per page
offsetPagination offset

Updating Orders

Update Status

curl -X PATCH https://api.hanzo.ai/order/order_abc123/status \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "processing",
    "note": "Order picked for packing"
  }'

Add Shipping Information

curl -X POST https://api.hanzo.ai/order/order_abc123/shipment \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "carrier": "fedex",
    "trackingNumber": "794644790138",
    "items": [
      {"itemId": "item_001", "quantity": 2}
    ]
  }'

Fulfillment

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

Partial Fulfillment

Ship items as they become available:

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": 1}
    ]
  }'

Returns and Refunds

Create Return Request

curl -X POST https://api.hanzo.ai/order/order_abc123/return \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "itemId": "item_001",
        "quantity": 1,
        "reason": "wrong_size"
      }
    ],
    "note": "Need larger size"
  }'

Process Return

curl -X POST https://api.hanzo.ai/return/ret_xyz789/receive \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"itemId": "item_001", "quantity": 1, "condition": "resellable"}
    ],
    "refundAmount": 2999,
    "restockItems": true
  }'

Return Reasons

ReasonDescription
wrong_sizeItem doesn't fit
wrong_itemReceived wrong item
defectiveItem is damaged/defective
not_as_describedItem differs from description
changed_mindCustomer changed mind

Cancellation

Cancel Order

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

Orders can only be cancelled before shipment. Once shipped, use the return flow instead.

Order Notes

Add Internal Note

curl -X POST https://api.hanzo.ai/order/order_abc123/note \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Customer requested gift wrapping",
    "internal": true
  }'

Email Notifications

Order events trigger automatic emails:

EventEmail
Order confirmedOrder confirmation
Order shippedShipping notification with tracking
Order deliveredDelivery confirmation
Return approvedReturn instructions
Refund processedRefund confirmation

Resend Email

curl -X POST https://api.hanzo.ai/order/order_abc123/email \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "confirmation"
  }'

SDK Examples

JavaScript

import { Commerce } from '@hanzo/commerce'

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

// Create order from cart
const order = await commerce.orders.create({
  cartId: 'cart_abc123',
  shippingAddress: {
    firstName: 'John',
    lastName: 'Doe',
    line1: '123 Main St',
    city: 'San Francisco',
    state: 'CA',
    postalCode: '94102',
    country: 'US'
  }
})

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

// Process return
const returnRequest = await commerce.orders.createReturn(order.id, {
  items: [{ itemId: 'item_001', quantity: 1, reason: 'wrong_size' }]
})

Go

order, err := client.Orders.Create(ctx, &sdk.OrderInput{
    CartID: "cart_abc123",
    ShippingAddress: &sdk.Address{
        FirstName:  "John",
        LastName:   "Doe",
        Line1:      "123 Main St",
        City:       "San Francisco",
        State:      "CA",
        PostalCode: "94102",
        Country:    "US",
    },
})

err = client.Orders.Fulfill(ctx, order.ID, &sdk.FulfillmentInput{
    Items: []sdk.FulfillmentItem{
        {ItemID: "item_001", Quantity: 2},
    },
    Tracking: &sdk.TrackingInfo{
        Carrier: "ups",
        Number:  "1Z999AA10123456784",
    },
})

How is this guide?

Last updated on

Shopping Cart

Implement persistent shopping carts with discounts and coupons

Payments

Process payments with multiple providers including crypto

On this page

Order Structure
Order Status Flow
Status Descriptions
Creating Orders
From Cart
Direct Order
Retrieving Orders
Get Single Order
List Orders
Query Parameters
Updating Orders
Update Status
Add Shipping Information
Fulfillment
Create Fulfillment
Partial Fulfillment
Returns and Refunds
Create Return Request
Process Return
Return Reasons
Cancellation
Cancel Order
Order Notes
Add Internal Note
Email Notifications
Resend Email
SDK Examples
JavaScript
Go