Skip to main content
POST
/
api
/
v1
/
i
/
orders
curl -X POST "https://api.example.com/api/v1/i/orders/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "checkout",
    "billing_address": {
      "street_address": "123 Main St",
      "postal_code": 12345,
      "city": "Anytown",
      "state": "CA",
      "country": "Canada"
    }
  }'

{
  "success": "Your Order has been saved"
}

​
Description

Converts the authenticated customer’s cart into an order. This endpoint supports two actions:
  • checkout: Creates an order and redirects to payment
  • save_order: Creates an order for later checkout
All items from the cart are transferred to the order with their current prices and active offers locked in.

​
Authentication

Requires authentication. The order is created for the authenticated customer.

​
Request Body

​
action
string
required
The action to perform:
  • checkout - Create order and redirect to payment
  • save_order - Create order without immediate payment
​
billing_address
object
Billing address for the order. Required if customer doesn’t have a saved address.

​
Response

​
For action: “save_order”

​
success
string
Success message confirming the order was saved

​
For action: “checkout”

Redirects to the payment endpoint for the created order.

​
Request Validation

Cart Must Not Be EmptyThe customer’s cart must contain at least one item to create an order.
Billing Address RequiredEither provide a billing_address in the request or the customer must have a saved address.
Valid ActionThe action field must be either “checkout” or “save_order”.
curl -X POST "https://api.example.com/api/v1/i/orders/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "checkout",
    "billing_address": {
      "street_address": "123 Main St",
      "postal_code": 12345,
      "city": "Anytown",
      "state": "CA",
      "country": "Canada"
    }
  }'

{
  "success": "Your Order has been saved"
}

​
Order Creation Process

When an order is created, the following happens:
1

Cart Validation

The system validates that the cart is not empty and refreshes to get latest prices.
2

Address Assignment

A billing address is assigned from either:
  • The provided billing_address (creates new Address record)
  • The customer’s existing saved address
3

Order Creation

A new order is created with:
  • Status: awaiting_payment
  • Associated billing address
  • Customer reference
4

Transfer Cart Items

All cart items are transferred to order items with:
  • Current unit prices locked in
  • Active offers and discounts preserved
  • Shipping costs captured
  • Applied vouchers transferred
5

Cart Cleared

The customer’s cart is emptied after successful order creation.
6

Action Execution

  • checkout: Redirects to payment endpoint
  • save_order: Returns success message

​
Order Item Preservation

When cart items become order items, the following data is preserved:
  • unit_price: Current price after discounts
  • quantity: Number of units
  • discount_amount: Total discount from offers
  • offer: Reference to the offer that was applied
  • shipping: Per-item shipping cost
  • total_price: Final price (unit_price × quantity)
This ensures that even if product prices or offers change later, the order reflects the pricing at the time of purchase.

​
Voucher Handling

If a voucher was applied to the cart:
  • The voucher is transferred to the order
  • The discount amount is calculated and stored
  • The voucher discount is included in the order’s amount_saved

​
Notes

  • Orders are created in an atomic transaction to ensure data consistency
  • If order creation fails, the cart remains unchanged
  • The cart is forcefully refreshed before order creation to ensure current pricing
  • Country names must be full names (e.g., “Canada” not “CA”)
  • Only one voucher per order is supported
  • New addresses are created if they don’t exist; existing ones are reused if found

Build docs developers (and LLMs) love

Get started for freeTalk to us