Orders API

The Orders API provides comprehensive order management functionality, including cart operations, checkout processing, order tracking, and fulfillment management for the OSUS.AI platform.

Base URL: https://api.osus.ai/v1/orders

Order Lifecycle

pending

confirmed

processing

shipped

delivered

Create Order

Create a new order from cart items or direct product selection.

POST /orders

Request Body

Parameter	Type	Required	Description
`items`	array	Yes	Array of order items
`shippingAddressId`	string	Yes	Shipping address UUID
`billingAddressId`	string	No	Billing address UUID (defaults to shipping)
`paymentMethodId`	string	Yes	Payment method UUID
`deliveryDate`	string	No	Preferred delivery date (ISO 8601)
`installationDate`	string	No	Installation appointment date
`specialInstructions`	string	No	Special delivery/installation instructions
`couponCode`	string	No	Discount coupon code
`loyaltyPointsToUse`	integer	No	Number of loyalty points to redeem

Order Item Structure

Field	Type	Description
`productId`	string	Product UUID
`variantId`	string	Product variant UUID (optional)
`quantity`	integer	Quantity to order
`designProjectId`	string	3D design project UUID (optional)
`customizations`	object	Product customization options

Example Request

curl -X POST https://api.osus.ai/v1/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "productId": "550e8400-e29b-41d4-a716-446655440000",
        "variantId": "var-001",
        "quantity": 1,
        "customizations": {
          "color": "blue",
          "fabric": "leather"
        }
      },
      {
        "productId": "550e8400-e29b-41d4-a716-446655440001",
        "quantity": 2
      }
    ],
    "shippingAddressId": "addr-001",
    "paymentMethodId": "pm-001",
    "deliveryDate": "2025-01-20T10:00:00Z",
    "specialInstructions": "Please call before delivery",
    "couponCode": "WELCOME10",
    "loyaltyPointsToUse": 500
  }'

Response

{
  "success": true,
  "data": {
    "order": {
      "id": "ord-123456",
      "orderNumber": "OSUS-2025-000001",
      "status": "pending",
      "items": [
        {
          "id": "item-001",
          "productId": "550e8400-e29b-41d4-a716-446655440000",
          "productName": "Modern 3-Seat Sofa",
          "productSku": "IKEA-SOFA-001",
          "variantId": "var-001",
          "variantName": "Blue Leather",
          "quantity": 1,
          "unitPrice": 2500,
          "totalPrice": 2500,
          "requiresInstallation": true,
          "installationPrice": 200
        }
      ],
      "customer": {
        "id": "user-001",
        "name": "Ahmed Mohamed",
        "email": "ahmed@example.com",
        "phone": "+201234567890"
      },
      "addresses": {
        "shipping": {
          "id": "addr-001",
          "name": "Ahmed Mohamed",
          "address": "123 Tahrir Square, Cairo",
          "city": "Cairo",
          "governorate": "Cairo",
          "phone": "+201234567890"
        }
      },
      "pricing": {
        "subtotal": 2500,
        "taxAmount": 375,
        "shippingAmount": 50,
        "discountAmount": 250,
        "installationAmount": 200,
        "totalAmount": 2875,
        "currency": "EGP",
        "appliedCoupons": [
          {
            "code": "WELCOME10",
            "discount": 250,
            "type": "percentage"
          }
        ],
        "loyaltyPointsUsed": 500,
        "loyaltyPointsEarned": 144
      },
      "delivery": {
        "estimatedDate": "2025-01-20T10:00:00Z",
        "deliveryMethod": "standard",
        "trackingNumber": null
      },
      "installation": {
        "required": true,
        "scheduledDate": "2025-01-21T14:00:00Z",
        "timeSlot": "afternoon"
      },
      "timeline": {
        "createdAt": "2025-01-15T10:30:00Z",
        "estimatedShipping": "2025-01-18T08:00:00Z",
        "estimatedDelivery": "2025-01-20T10:00:00Z"
      }
    },
    "paymentIntent": {
      "id": "pi_1234567890",
      "clientSecret": "pi_1234567890_secret_xyz",
      "status": "requires_payment_method"
    },
    "estimatedDelivery": {
      "date": "2025-01-20T10:00:00Z",
      "timeSlot": "10:00-14:00",
      "method": "standard"
    }
  },
  "timestamp": "2025-01-15T10:30:00Z",
  "requestId": "req_123456"
}

Get Order Details

Retrieve detailed information about a specific order.

GET /orders/{orderId}

Path Parameters

Parameter	Type	Description
`orderId`	string	Order UUID or order number

Example Request

curl -X GET https://api.osus.ai/v1/orders/ord-123456 \
  -H "Authorization: Bearer YOUR_API_KEY"

List Orders

Retrieve a paginated list of orders for the authenticated user.

GET /orders

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20, max: 100)
`status`	string	Filter by order status
`fromDate`	string	Filter orders from date (ISO 8601)
`toDate`	string	Filter orders to date (ISO 8601)
`sortBy`	string	Sort field: createdAt, totalAmount
`sortOrder`	string	Sort order: asc, desc

Cart Management

Manage shopping cart contents before checkout.

GET /cart

Get current cart contents

POST /cart/items

Add item to cart

PUT /cart/items/{itemId}

Update cart item quantity

DELETE /cart/items/{itemId}

Remove item from cart

DELETE /cart

Clear entire cart

Add to Cart Example

curl -X POST https://api.osus.ai/v1/cart/items \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "550e8400-e29b-41d4-a716-446655440000",
    "variantId": "var-001",
    "quantity": 1,
    "customizations": {
      "color": "blue"
    }
  }'

Cart Response

{
  "success": true,
  "data": {
    "cart": {
      "id": "cart-123",
      "items": [
        {
          "id": "item-001",
          "productId": "550e8400-e29b-41d4-a716-446655440000",
          "product": {
            "name": "Modern 3-Seat Sofa",
            "image": "https://cdn.osus.ai/products/sofa-001-main.jpg",
            "price": 2500
          },
          "variantId": "var-001",
          "variant": {
            "name": "Blue",
            "color": "Blue"
          },
          "quantity": 1,
          "unitPrice": 2500,
          "totalPrice": 2500,
          "addedAt": "2025-01-15T10:30:00Z"
        }
      ],
      "totalItems": 1,
      "subtotal": 2500,
      "estimatedTax": 375,
      "estimatedShipping": 50,
      "estimatedTotal": 2925,
      "currency": "EGP"
    }
  }
}

Order Tracking

Track order progress and delivery status.

GET /orders/{orderId}/tracking

Tracking Response

{
  "success": true,
  "data": {
    "tracking": {
      "orderId": "ord-123456",
      "trackingNumber": "TRK-789012345",
      "carrier": "OSUS Logistics",
      "status": "in_transit",
      "estimatedDelivery": "2025-01-20T10:00:00Z",
      "currentLocation": {
        "city": "Giza",
        "country": "Egypt",
        "timestamp": "2025-01-18T14:30:00Z"
      },
      "events": [
        {
          "status": "order_confirmed",
          "description": "Order confirmed and payment received",
          "timestamp": "2025-01-15T10:30:00Z",
          "location": "Cairo, Egypt"
        },
        {
          "status": "processing",
          "description": "Order is being prepared for shipment",
          "timestamp": "2025-01-16T08:00:00Z",
          "location": "Cairo Warehouse"
        },
        {
          "status": "shipped",
          "description": "Package has been shipped",
          "timestamp": "2025-01-18T09:00:00Z",
          "location": "Cairo Warehouse"
        },
        {
          "status": "in_transit",
          "description": "Package is on the way to destination",
          "timestamp": "2025-01-18T14:30:00Z",
          "location": "Giza Distribution Center"
        }
      ]
    }
  }
}

Order Status Values

Status	Description	Customer Actions
pending	Order created, awaiting payment confirmation	Complete payment, cancel order
confirmed	Payment confirmed, order being prepared	View details, contact support
processing	Items being picked and packed	Track progress, modify delivery details
shipped	Order dispatched from warehouse	Track shipment, prepare for delivery
delivered	Order successfully delivered	Rate items, request installation
cancelled	Order cancelled by customer or system	View refund status, reorder items

Error Codes

HTTP Status	Error Code	Description
400	`INVALID_ORDER_DATA`	Invalid order data provided
400	`INSUFFICIENT_STOCK`	Not enough inventory for requested quantity
400	`INVALID_COUPON`	Coupon code is invalid or expired
400	`PAYMENT_FAILED`	Payment processing failed
403	`ORDER_ACCESS_DENIED`	Cannot access order (not owner)
404	`ORDER_NOT_FOUND`	Order with specified ID not found
409	`ORDER_ALREADY_CANCELLED`	Cannot modify cancelled order
422	`DELIVERY_NOT_AVAILABLE`	Delivery not available to specified address