Create Order

Create a new order from the customer’s shopping cart

POST /api/v1/i/orders

Checkout with New Address

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

201 Created (save_order)

{
  "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.

Show Address Fields

street_address · string · required

Street address (max 30 characters)

postal_code · integer · required

Postal or ZIP code

city · string · required

City name (max 50 characters)

state · string · required

State or province name (max 50 characters)

country · string · required

Full country name (not code). Must be more than 3 characters.

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 Empty

The customer’s cart must contain at least one item to create an order.

Billing Address Required

Either provide a billing_address in the request or the customer must have a saved address.

Valid Action

The action field must be either “checkout” or “save_order”.

Checkout with New Address

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

201 Created (save_order)

{
  "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