Orders API

Create and manage B2B orders with flexible payment terms and AI-generated quotes.

Overview

The Orders API enables:

• Order CRUD — Create, read, update, cancel orders
• AI Quotes — Generate intelligent quotes with optimal pricing
• Payment Terms — Net 30, Net 60, installment plans
• Shopify Integration — Automatic draft order creation

Base URL

https://api.huntrecht.com/api/v1/orders

Required Scopes

Scope	Permission
orders:read	View orders
orders:write	Create/modify orders

Create Order

POST /orders

Create a new B2B order with specified payment terms.

Request Body

Field	Type	Required	Description
customer_id	string	Yes	Customer ID
line_items	array	Yes	Array of product items
payment_terms	string	Yes	net_30, net_60, installments_6, installments_12, installments_24
shipping_address	object	No	Shipping address
notes	string	No	Order notes

Example Request

order = client.orders.create({
    "customer_id": "cust_abc123",
    "line_items": [
        {
            "product_id": "gid://shopify/Product/123",
            "variant_id": "gid://shopify/ProductVariant/456",
            "quantity": 10,
            "unit_price": 150.00
        },
        {
            "product_id": "gid://shopify/Product/124",
            "quantity": 5,
            "unit_price": 75.00
        }
    ],
    "payment_terms": "net_30",
    "shipping_address": {
        "company": "Acme Corporation",
        "address1": "123 Business Ave",
        "city": "Commerce City",
        "state": "CA",
        "postal_code": "90210",
        "country": "US"
    },
    "notes": "Please deliver between 9 AM - 5 PM"
})

Example Response

{
  "id": "ord_xyz789",
  "customer_id": "cust_abc123",
  "status": "pending_approval",
  "payment_terms": "net_30",
  "payment_due_date": "2026-02-10T00:00:00Z",
  "line_items": [
    {
      "product_id": "gid://shopify/Product/123",
      "quantity": 10,
      "unit_price": 150.00,
      "total": 1500.00
    },
    {
      "product_id": "gid://shopify/Product/124",
      "quantity": 5,
      "unit_price": 75.00,
      "total": 375.00
    }
  ],
  "subtotal": 1875.00,
  "tax": 150.00,
  "shipping": 25.00,
  "total": 2050.00,
  "currency": "USD",
  "shopify_order_id": null,
  "created_at": "2026-01-11T10:00:00Z",
  "created_by": "user_abc123"
}

List Orders

GET /orders

Retrieve orders with filtering and pagination.

Query Parameters

Parameter	Type	Description
customer_id	string	Filter by customer
status	string	pending_approval, approved, processing, shipped, delivered, cancelled
payment_terms	string	Filter by payment terms
start_date	string	Filter by created date (ISO 8601)
end_date	string	Filter by created date (ISO 8601)
page	integer	Page number (default: 1)
limit	integer	Results per page (default: 20, max: 100)

Example Request

orders = client.orders.list(
    customer_id="cust_abc123",
    status="pending_approval",
    page=1,
    limit=20
)

Example Response

{
  "data": [
    {
      "id": "ord_xyz789",
      "customer_id": "cust_abc123",
      "status": "pending_approval",
      "payment_terms": "net_30",
      "total": 2050.00,
      "created_at": "2026-01-11T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "has_more": false
  }
}

Get Order

GET /orders/{order_id}

Retrieve a specific order by ID.

order = client.orders.get("ord_xyz789")

Update Order

PUT /orders/{order_id}

Update order status or details.

Allowed Updates

Field	Description
status	Update order status
shipping_address	Update shipping address
notes	Update order notes
line_items	Modify line items (before processing)

order = client.orders.update("ord_xyz789", {
    "status": "approved",
    "notes": "Payment confirmed via bank transfer"
})

Cancel Order

POST /orders/{order_id}/cancel

Cancel an order with optional reason.

order = client.orders.cancel("ord_xyz789", {
    "reason": "Customer requested cancellation"
})

Cancellation Response

{
  "id": "ord_xyz789",
  "status": "cancelled",
  "cancelled_at": "2026-01-11T14:00:00Z",
  "cancellation_reason": "Customer requested cancellation",
  "refund_amount": 2050.00,
  "refund_status": "pending"
}

Payment Terms

Available Payment Terms

Terms	Description	Max Duration
net_30	Net payment within 30 days	30 days
net_60	Net payment within 60 days	60 days
installments_6	6 monthly installments	6 months
installments_12	12 monthly installments	12 months
installments_24	24 monthly installments	24 months

Installment Calculation

# Example: $5500 order with 12 installments
order = client.orders.create({
    "customer_id": "cust_abc123",
    "line_items": [{"product_id": "prod_001", "quantity": 1}],
    "payment_terms": "installments_12"
})

# Response includes installment details
print(order["monthly_amount"])  # 458.33
print(order["total_amount"])    # 5500.00
print(order["interest_rate"])   # 8.5%

Order Status Flow

stateDiagram-v2
    [*] --> pending_approval: Order Created
    pending_approval --> approved: Credit Approved
    pending_approval --> rejected: Credit Denied
    approved --> processing: Payment Confirmed
    processing --> shipped: Products Shipped
    shipped --> delivered: Products Delivered
    delivered --> [*]
    rejected --> cancelled: Auto-cancelled
    processing --> cancelled: Customer Request

AI Quote Generation

Generate Quote

POST /quotes/generate

Generate an AI-powered quote with optimal pricing based on:

• Customer credit score
• Order volume
• Payment terms selected
• Historical purchasing patterns

quote = client.quotes.generate({
    "customer_id": "cust_abc123",
    "product_ids": ["prod_001", "prod_002"],
    "quantities": [10, 5],
    "payment_terms": "net_30"
})

Quote Response

{
  "id": "quote_abc123",
  "customer_id": "cust_abc123",
  "line_items": [
    {
      "product_id": "prod_001",
      "quantity": 10,
      "original_price": 150.00,
      "discounted_price": 142.50,
      "discount_percent": 5
    }
  ],
  "recommended_terms": {
    "payment_terms": "net_30",
    "interest_rate": 0,
    "installments_available": [6, 12, 24]
  },
  "expires_at": "2026-01-18T10:00:00Z",
  "valid_days": 7
}

Webhook Events

Event	Description
order.created	New order created
order.updated	Order status changed
order.cancelled	Order cancelled
order.approved	Order approved for processing
order.shipped	Order shipped
order.delivered	Order delivered

Error Codes

Code	Description
ORDER_NOT_FOUND	Order ID not found
INVALID_PAYMENT_TERMS	Invalid payment terms specified
CREDIT_REQUIRED	Credit check required before approval
ORDER_ALREADY_PROCESSED	Cannot modify processed order
INSUFFICIENT_STOCK	Product stock insufficient

Next Steps

• Subscription Management
• Payment Processing
• Credit Risk Assessment
• Shopify Integration