Orders API

The Orders API provides endpoints for managing orders, cart operations, and payment processing.

Cart Management

Get Cart

GET /api/v1/cart/

Add Item to Cart

POST /api/v1/cart/items/

Request Body:

{
    "product_id": 1,
    "variant_id": 2,
    "quantity": 1
}

Update Cart Item

PATCH /api/v1/cart/items/{item_id}/

Request Body:

{
    "quantity": 2
}

Remove Cart Item

DELETE /api/v1/cart/items/{item_id}/

Clear Cart

DELETE /api/v1/cart/

Orders

Create Order

POST /api/v1/orders/

Request Body:

{
    "shipping_address_id": 1,
    "billing_address_id": 1,
    "payment_method": "stripe",
    "notes": "Please deliver during business hours"
}

List Orders

GET /api/v1/orders/

Query Parameters:

Parameter Type Description
status string Filter by order status
from_date date Filter orders from date
to_date date Filter orders to date
ordering string Order results (e.g., -created_at)

Get Order Details

GET /api/v1/orders/{order_id}/

Cancel Order

POST /api/v1/orders/{order_id}/cancel/

Request Body:

{
    "reason": "Changed my mind",
    "notes": "Optional cancellation notes"
}

Payment Processing

Create Payment Intent

POST /api/v1/orders/{order_id}/payment/intent/

Response:

{
    "client_secret": "pi_3NqX..._secret_K...",
    "amount": 9999,
    "currency": "usd"
}

Confirm Payment

POST /api/v1/orders/{order_id}/payment/confirm/

Request Body:

{
    "payment_intent_id": "pi_3NqX..."
}

Order Status Webhook

POST /api/v1/orders/webhook/

The webhook endpoint receives updates about order status changes, payment confirmations, and shipping updates.

Order Statuses

  • pending: Order created but not paid
  • paid: Payment received
  • processing: Order is being processed
  • shipped: Order has been shipped
  • delivered: Order has been delivered
  • cancelled: Order was cancelled
  • refunded: Order has been refunded

Rate Limiting

  • Cart operations: 60 requests per minute
  • Order creation: 10 requests per minute
  • Order listing: 30 requests per minute
  • Payment operations: 10 requests per minute

Error Responses

The API uses standard HTTP status codes and returns error messages in the following format:

{
    "detail": "Error message",
    "code": "error_code"
}

Common error codes:

  • insufficient_stock: Product is out of stock
  • invalid_payment: Payment processing failed
  • order_not_found: Order does not exist
  • invalid_status: Invalid order status transition
  • cart_empty: Cannot create order with empty cart