Order API

The Order API handles the complete order lifecycle from creation through fulfillment, including status transitions, payment capture, cancellation, and refund processing.

Order Structure

{
  "id": "order_abc123",
  "displayId": "#1042",
  "status": "confirmed",
  "paymentStatus": "captured",
  "fulfillmentStatus": "unfulfilled",
  "email": "[email protected]",
  "currency": "USD",
  "items": [
    {
      "id": "oitem_001",
      "variantId": "var_xyz789",
      "productId": "prod_abc123",
      "title": "Premium T-Shirt - Black / M",
      "sku": "SHIRT-BLK-M",
      "quantity": 2,
      "unitPrice": 2999,
      "subtotal": 5998,
      "fulfilledQuantity": 0
    }
  ],
  "subtotal": 5998,
  "discount": 1499,
  "shippingTotal": 599,
  "taxTotal": 540,
  "total": 5638,
  "shippingAddress": {
    "firstName": "Jane",
    "lastName": "Doe",
    "line1": "456 Oak Ave",
    "city": "Portland",
    "state": "OR",
    "postalCode": "97201",
    "country": "US"
  },
  "payments": [
    {
      "id": "pay_xyz789",
      "provider": "stripe",
      "amount": 5638,
      "status": "captured",
      "capturedAt": "2024-06-15T10:05:00Z"
    }
  ],
  "metadata": {},
  "createdAt": "2024-06-15T10:00:00Z",
  "updatedAt": "2024-06-15T10:05:00Z"
}

Order Status Flow

Status	Description
`pending`	Order created, awaiting payment
`confirmed`	Payment authorized or captured
`processing`	Being prepared for fulfillment
`shipped`	Shipped to customer
`delivered`	Delivered to customer
`cancelled`	Order cancelled
`refunded`	Payment fully refunded

Endpoints

List Orders

GET /order

Query Parameters:

Parameter	Type	Description
`page`	number	Page number (default: 1)
`display`	number	Items per page (default: 20, max: 100)
`sort`	string	Sort field (e.g. `createdAt:desc`)
`status`	string	Filter by order status
`paymentStatus`	string	`pending`, `authorized`, `captured`, `refunded`
`fulfillmentStatus`	string	`unfulfilled`, `partial`, `fulfilled`
`customerId`	string	Filter by customer
`since`	string	Created after ISO date
`until`	string	Created before ISO date
`q`	string	Search by order ID or email

curl "https://api.hanzo.ai/order?status=confirmed&fulfillmentStatus=unfulfilled&sort=createdAt:desc" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "count": 342,
  "models": [
    {
      "id": "order_abc123",
      "displayId": "#1042",
      "status": "confirmed",
      "paymentStatus": "captured",
      "fulfillmentStatus": "unfulfilled",
      "email": "[email protected]",
      "total": 5638,
      "createdAt": "2024-06-15T10:00:00Z"
    }
  ]
}

Get Order

GET /order/:id

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

Create Order

POST /order

Create an order directly (bypassing the cart flow). Typically used for backend integrations and imports.

curl -X POST https://api.hanzo.ai/order \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "currency": "USD",
    "items": [
      {
        "variantId": "var_xyz789",
        "quantity": 2,
        "unitPrice": 2999
      }
    ],
    "shippingAddress": {
      "firstName": "Jane",
      "lastName": "Doe",
      "line1": "456 Oak Ave",
      "city": "Portland",
      "state": "OR",
      "postalCode": "97201",
      "country": "US"
    },
    "shippingMethodId": "ship_standard"
  }'

Response: 201 Created

Update Order

PATCH /order/:id

Update order metadata, notes, or shipping address before fulfillment.

curl -X PATCH https://api.hanzo.ai/order/order_abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "internalNote": "Priority shipment requested"
    }
  }'

Order Actions

Cancel Order

POST /order/:id/cancel

Cancel an order. If payment was captured, a refund is initiated automatically.

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",
    "note": "Customer changed their mind"
  }'

Response:

{
  "id": "order_abc123",
  "status": "cancelled",
  "paymentStatus": "refunded",
  "cancelledAt": "2024-06-16T09:00:00Z",
  "cancelReason": "customer_request"
}

Cancel Reasons:

Reason	Description
`customer_request`	Customer asked to cancel
`out_of_stock`	Item no longer available
`fraud`	Suspected fraudulent order
`duplicate`	Duplicate order
`other`	Other reason (specify in note)

Orders that have been partially or fully fulfilled cannot be cancelled. Use the refund endpoint instead.

Refund Order

POST /order/:id/refund

Issue a partial or full refund for an order.

curl -X POST https://api.hanzo.ai/order/order_abc123/refund \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2999,
    "reason": "Item arrived damaged",
    "items": [
      { "itemId": "oitem_001", "quantity": 1 }
    ]
  }'

Response:

{
  "id": "refund_xyz789",
  "orderId": "order_abc123",
  "amount": 2999,
  "status": "processed",
  "reason": "Item arrived damaged",
  "createdAt": "2024-06-20T14:00:00Z"
}

Fulfill Order

POST /order/:id/fulfill

Create a fulfillment for some or all items in the order.

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": "oitem_001", "quantity": 2 }
    ],
    "trackingNumber": "1Z999AA10123456784",
    "trackingCompany": "UPS",
    "trackingUrl": "https://track.ups.com/1Z999AA10123456784",
    "notifyCustomer": true
  }'

Response:

{
  "id": "ful_abc789",
  "orderId": "order_abc123",
  "status": "shipped",
  "items": [
    { "itemId": "oitem_001", "quantity": 2 }
  ],
  "tracking": {
    "number": "1Z999AA10123456784",
    "company": "UPS",
    "url": "https://track.ups.com/1Z999AA10123456784"
  },
  "shippedAt": "2024-06-17T08:00:00Z"
}

SDK Examples

JavaScript

import { Commerce } from '@hanzo/commerce'

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

// List unfulfilled orders
const orders = await commerce.orders.list({
  status: 'confirmed',
  fulfillmentStatus: 'unfulfilled',
  sort: 'createdAt:desc'
})

// Get order details
const order = await commerce.orders.get('order_abc123', {
  expand: ['items.product', 'payments']
})

// Fulfill order
await commerce.orders.fulfill('order_abc123', {
  items: [{ itemId: 'oitem_001', quantity: 2 }],
  trackingNumber: '1Z999AA10123456784',
  trackingCompany: 'UPS',
  notifyCustomer: true
})

// Cancel order
await commerce.orders.cancel('order_abc123', {
  reason: 'customer_request'
})

// Partial refund
await commerce.orders.refund('order_abc123', {
  amount: 2999,
  reason: 'Item arrived damaged',
  items: [{ itemId: 'oitem_001', quantity: 1 }]
})

Go

orders, err := client.Orders.List(ctx, &sdk.OrderListParams{
    Status:            "confirmed",
    FulfillmentStatus: "unfulfilled",
    Sort:              "createdAt:desc",
})

order, err := client.Orders.Get(ctx, "order_abc123")

ful, err := client.Orders.Fulfill(ctx, "order_abc123", &sdk.FulfillmentInput{
    Items: []sdk.FulfillmentItem{
        {ItemID: "oitem_001", Quantity: 2},
    },
    TrackingNumber:  "1Z999AA10123456784",
    TrackingCompany: "UPS",
    NotifyCustomer:  true,
})

err = client.Orders.Cancel(ctx, "order_abc123", &sdk.CancelInput{
    Reason: "customer_request",
})

refund, err := client.Orders.Refund(ctx, "order_abc123", &sdk.RefundInput{
    Amount: 2999,
    Reason: "Item arrived damaged",
})

On this page