# Orders

## Get all orders

GET stores/{store\_id}/orders?

This endpoint lets you get all orders for a specific store.

**Headers**

| Header          | Type   | Description   |
| --------------- | ------ | ------------- |
| `Authorization` | string | Bearer token. |

**Query parameters**

| Parameter   | Type    | Description                                                                                              |
| ----------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `page`      | integer | Page number for pagination. Default is 1.                                                                |
| `limit`     | integer | Number of orders per page. Default is 20.                                                                |
| `status`    | string  | Filter orders by status. Options are pending, paid, processing, shipped, delivered, cancelled, refunded. |
| `search`    | string  | Search in orderCode, customerEmail, customerName, items.name. String is case-insensitive.                |
| `startDate` | string  | Filter orders created on or after this date. ISO date string.                                            |
| `endDate`   | string  | Filter orders created on or before this date. ISO date string.                                           |
| `sortBy`    | string  | Field to start sort by. Options are createdAt, updatedAt, totalAmount, status, orderCode.                |
| `sortOrder` | string  | Sort direction. Options are desc, asc. Default is desc.                                                  |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "success": true,
    "message": "Orders retrieved successfully",
    "data": {
        "orders": [
                {
                        "_id": "672355f432116c6197fbf242",
                        "store": "692565f432118c6197abf2ec",
                        "user": "507f191e810c19729de860ea",    
                        "stripeSessionId": "cs_test_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6",
                        "stripePaymentIntentId": "pi_1234567890abcdef",
                        "stripeCustomerId": "cus_1234567890abcdef",
                        "customerEmail": "customer@example.com",
                        "customerPhone": "+1234567890",
                        "customerName": "John Doe",
                        "items": [
                            {
                            "product": "507f1f77bcf86cd799439012",
                            "name": "Premium Wireless Headphones",
                            "description": "High-quality wireless headphones with noise cancellation",
                            "quantity": 1,
                            "unitPrice": 99.99,
                            "totalPrice": 99.99,
                            "sku": "HW-001",
                            "images": [
                                "https://example.com/images/headphones-1.jpg",
                                "https://example.com/images/headphones-2.jpg"
                            ]
                            }
                        ],
                        "subtotal": 99.99,
                        "taxAmount": 2.00,
                        "shippingCost": 5.99,
                        "totalAmount": 107.98,
                        "currency": "usd",
                        "shippingAddress": {
                            "name": "John Doe",
                            "line1": "123 Main Street",
                            "line2": "Apt 4B",
                            "city": "New York",
                            "state": "NY",
                            "postal_code": "10001",
                            "country": "US"
                        },
                        "shippingOption": {
                            "name": "Standard Shipping",
                            "amount": 5.99,
                            "deliveryEstimate": {
                            "minimum": {
                                "unit": "business_day",
                                "value": 3
                            },
                            "maximum": {
                                "unit": "business_day",
                                "value": 5
                            }
                            }
                        },
                        "orderNotes": "Please leave package at front door",
                        "status": "paid",
                        "paymentStatus": "paid",
                        "trackingNumbers": [],
                        "stripeTransferId": "tr_1234567890abcdef",
                        "transferAmount": 102.99,
                        "platformFeeAmount": 5.00,
                        "transferStatus": "transferred",
                        "transferredAt": "2024-01-15T10:30:00.000Z",
                        "paidAt": "2024-01-15T10:00:00.000Z",
                        "createdAt": "2024-01-15T10:00:00.000Z",
                        "updatedAt": "2024-01-15T10:00:00.000Z"
                }
        ],
        "pagination": {
            "currentPage": 1,
            "totalPages": 1,
            "totalOrders": 1,
            "hasNextPage": false,
            "hasPrevPage": false
        }
    }
}
```

## Get order details

GET /stores/{store\_id}/orders/{order\_id}

This endpoint lets you get order details.

**Headers**

| Header          | Type   | Description   |
| --------------- | ------ | ------------- |
| `Authorization` | string | Bearer token. |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "success": true,
    "message": "Order details retrieved successfully",
    "data":  {
                        "_id": "672355f432116c6197fbf242",
                        "store": "692565f432118c6197abf2ec",
                        "user": "507f191e810c19729de860ea",    
                        "stripeSessionId": "cs_test_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6",
                        "stripePaymentIntentId": "pi_1234567890abcdef",
                        "stripeCustomerId": "cus_1234567890abcdef",
                        "customerEmail": "customer@example.com",
                        "customerPhone": "+1234567890",
                        "customerName": "John Doe",
                        "items": [
                            {
                            "product": "507f1f77bcf86cd799439012",
                            "name": "Premium Wireless Headphones",
                            "description": "High-quality wireless headphones with noise cancellation",
                            "quantity": 1,
                            "unitPrice": 99.99,
                            "totalPrice": 99.99,
                            "sku": "HW-001",
                            "images": [
                                "https://example.com/images/headphones-1.jpg",
                                "https://example.com/images/headphones-2.jpg"
                            ]
                            }
                        ],
                        "subtotal": 99.99,
                        "taxAmount": 2.00,
                        "shippingCost": 5.99,
                        "totalAmount": 107.98,
                        "currency": "usd",
                        "shippingAddress": {
                            "name": "John Doe",
                            "line1": "123 Main Street",
                            "line2": "Apt 4B",
                            "city": "New York",
                            "state": "NY",
                            "postal_code": "10001",
                            "country": "US"
                        },
                        "shippingOption": {
                            "name": "Standard Shipping",
                            "amount": 5.99,
                            "deliveryEstimate": {
                            "minimum": {
                                "unit": "business_day",
                                "value": 3
                            },
                            "maximum": {
                                "unit": "business_day",
                                "value": 5
                            }
                            }
                        },
                        "orderNotes": "Please leave package at front door",
                        "status": "paid",
                        "paymentStatus": "paid",
                        "trackingNumbers": [],
                        "stripeTransferId": "tr_1234567890abcdef",
                        "transferAmount": 102.99,
                        "platformFeeAmount": 5.00,
                        "transferStatus": "transferred",
                        "transferredAt": "2024-01-15T10:30:00.000Z",
                        "paidAt": "2024-01-15T10:00:00.000Z",
                        "createdAt": "2024-01-15T10:00:00.000Z",
                        "updatedAt": "2024-01-15T10:00:00.000Z"
    }
}
```

{% endtab %}

{% tab title="404" %}

```json
{
    "success": false,
    "message": "Order not found"
}
```

{% endtab %}
{% endtabs %}

## Update order status

PUT `/stores/{store_id}/orders/{order_id}`

This endpoint lets you update the status of an order.

**Headers**

| Header          | Type   | Description   |
| --------------- | ------ | ------------- |
| `Authorization` | string | Bearer token. |

**Body request**

```json
{
  "status": "shipped", // Optional - Valid values: pending, paid, processing, shipped, delivered, cancelled, refunded
  "trackingNumbers": [ // Optional - Array of tracking number objects
    {
      "carrier": "UPS", // Optional - Shipping carrier name (e.g., UPS, FedEx, USPS, DHL)
      "trackingNumber": "1Z999AA10123456784", // Optional - Tracking number
      "trackingUrl": "https://www.ups.com/track?tracknum=1Z999AA10123456784", // Optional - Tracking URL
      "addedAt": "2024-01-15T10:30:00.000Z" // Optional - Auto-generated if not provided
    }
  ],
  "paymentStatus": "paid", // Optional - Valid values: pending, paid, failed, refunded, partially_refunded
  "orderNotes": "Order shipped via express delivery" // Optional - Additional notes about the order
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "success": true,
    "message": "Order updated successfully",
    "data": {
        "_id": "672355f432116c6197fbf242",
        "store": "692565f432118c6197abf2ec",
        "user": "507f191e810c19729de860ea",
        "stripeSessionId": "cs_test_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6",
        "stripePaymentIntentId": "pi_1234567890abcdef",
        "stripeCustomerId": "cus_1234567890abcdef",
        "customerEmail": "customer@example.com",
        "customerPhone": "+1234567890",
        "customerName": "John Doe",
        "items": [
            {
            "product": "507f1f77bcf86cd799439012",
            "name": "Premium Wireless Headphones",
            "description": "High-quality wireless headphones with noise cancellation",
            "quantity": 1,
            "unitPrice": 99.99,
            "totalPrice": 99.99,
            "sku": "HW-001",
            "images": [
                "https://example.com/images/headphones-1.jpg",
                "https://example.com/images/headphones-2.jpg"
            ]
            }
        ],
        "subtotal": 99.99,
        "taxAmount": 2.00,
        "shippingCost": 5.99,
        "totalAmount": 107.98,
        "currency": "usd",
        "shippingAddress": {
            "name": "John Doe",
            "line1": "123 Main Street",
            "line2": "Apt 4B",
            "city": "New York",
            "state": "NY",
            "postal_code": "10001",
            "country": "US"
        },
        "shippingOption": {
            "name": "Standard Shipping",
            "amount": 5.99,
            "deliveryEstimate": {
            "minimum": {
                "unit": "business_day",
                "value": 3
            },
            "maximum": {
                "unit": "business_day",
                "value": 5
            }
            }
        },
        "orderNotes": "Order shipped via express delivery",
        "status": "shipped",
        "paymentStatus": "paid",
        "trackingNumbers": [
            {
            "carrier": "UPS",
            "trackingNumber": "1Z999AA10123456784",
            "trackingUrl": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
            "addedAt": "2024-01-15T10:30:00.000Z"
            }
        ],
        "stripeTransferId": "tr_1234567890abcdef",
        "transferAmount": 102.99,
        "platformFeeAmount": 5.00,
        "transferStatus": "transferred",
        "transferredAt": "2024-01-15T10:30:00.000Z",
        "paidAt": "2024-01-15T10:00:00.000Z",
        "createdAt": "2024-01-15T10:00:00.000Z",
        "updatedAt": "2024-01-15T10:30:00.000Z"
    }
}
```

{% endtab %}

{% tab title="404" %}

```json
{
    "success": false,
    "message": "Order not found"
}
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}