Orders

Create orders through the public checkout and manage tenant orders with full status lifecycle.

POST /api/v1/orders

Create a new order through the public storefront checkout. Does not require authentication.

Middleware: throttle:api.transactions
Authentication: Not required

Request body

customer_name · string · required

Full name of the customer. Maximum 255 characters.

customer_phone · string · required

Customer phone number. Maximum 20 characters.

customer_email · string

Customer email address.

customer_address · string

Delivery address. Maximum 500 characters.

customer_notes · string

Special instructions. Maximum 1000 characters.

delivery_type · string · required

Must be pickup or delivery.

payment_method · string

One of: cash, bank_transfer, card, pending. Defaults to pending.

coupon_code · string

Optional discount code. Normalized to uppercase before validation.

location_id · string

UUID of the pickup/delivery location. Defaults to the tenant’s primary active location.

items · object[] · required

Array of order line items. Minimum 1 item required.

Show item properties

product_id · integer · required

Must exist in the products table.

name · string · required

Product display name at time of order.

price · number · required

Unit price. Must be ≥ 0.

quantity · integer · required

Quantity. Must be ≥ 1.

options · object

Key-value map of selected product options.

notes · string

Line item notes. Maximum 500 characters.

Response 201 Created

data · object

Show properties

id · integer

Order ID.

code · string

Tracking UUID for the customer.

status_label · string

Human-readable status (e.g. Pendiente).

total · number

Order total as a float.

formatted_total · string

Total with currency symbol (e.g. L. 150.00).

items_count · integer

Number of line items.

payment_instructions · object

Dynamic payment instructions based on payment method. null for card payments.

cURL

curl -X POST https://yourdomain.com/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "customer_name": "Carlos López",
    "customer_phone": "[phone]",
    "delivery_type": "pickup",
    "payment_method": "cash",
    "items": [
      {"product_id": 101, "name": "Pupusas de Queso", "price": 25.00, "quantity": 2}
    ]
  }'

Error responses

Status	Cause
422	Validation failure (missing fields, invalid product_id, invalid delivery_type)
429	Transaction rate limit exceeded

---

GET /api/v1/orders

List orders for the authenticated user’s tenant. Supports filtering by status.

Middleware: auth:sanctum, tenant.ownership, throttle:api
Authentication: Required

Query parameters

status · string

Filter by order status. One of: pending, confirmed, processing, ready, delivered, cancelled.

Response 200 OK

Paginated collection of order objects (20 per page) scoped to the authenticated tenant.

cURL

curl "https://yourdomain.com/api/v1/orders?status=pending" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"

---

GET /api/v1/orders/

Fetch a single order by ID. The order must belong to the authenticated tenant.

Middleware: auth:sanctum, tenant.ownership, throttle:api
Authentication: Required

Path parameters

order · integer · required

Numeric order ID.

Error responses

Status	Cause
404	Order not found or does not belong to authenticated tenant

---

PATCH /api/v1/orders//status

Transition an order to a new status.

Middleware: auth:sanctum, tenant.ownership, throttle:api
Authentication: Required

Path parameters

order · integer · required

Numeric order ID.

Request body

status · string · required

Target status. Must be one of the allowed order statuses: pending, confirmed, processing, ready, delivered, cancelled.

Response 200 OK

Updated order resource with the same shape as the list endpoint.

Error responses

Status	Cause
404	Order not found
422	Invalid or disallowed status value

---

DELETE /api/v1/orders/

Cancel an order. Internally transitions the status to cancelled.

Middleware: auth:sanctum, tenant.ownership, throttle:api
Authentication: Required

Path parameters

order · integer · required

Numeric order ID.

Response 204 No Content

Empty body on success.

Error responses

Status	Cause
404	Order not found or not owned by authenticated tenant