Skip to main content

Create a Direct Purchase Order

POST /api/v1/orders Creates an order directly without going through the cart flow. This endpoint validates the items, processes payment from the specified wallet, and returns the created order.

Authentication

Requires a Bearer token in the Authorization header.

Request Body

FieldTypeRequiredDescription
wallet_idstring (UUID)The ID of the wallet to use for payment
itemsarrayArray of items to purchase
items[].product_variant_idintegerID of the product variant
items[].quantityintegerQuantity to purchase (minimum: 1)

Example Request

{
  "wallet_id": "123e4567-e89b-12d3-a456-426614174002",
  "items": [
    {
      "product_variant_id": 123,
      "quantity": 1
    }
  ]
}

Responses

StatusDescription
201 CreatedOrder created successfully
401 UnauthorizedMissing or invalid authentication token
403 ForbiddenAccess denied
422 Unprocessable EntityValidation error or business rule violation (e.g. insufficient wallet funds)
500 Internal Server ErrorUnexpected server error

201 — Order Created

{
  "message": "Order created successfully",
  "data": {
    "id": 12345,
    "ulid": "01J9Z3NDEKTSV4RRFFQ69G5FAV",
    "order_number": "#ORD-12345",
    "fulfillment_status": "pending",
    "payment_status": "completed",
    "subtotal": { "amount": 99.99, "formatted": "€99.99" },
    "conversion_fees": { "amount": 2.5, "formatted": "€2.50" },
    "total": { "amount": 102.49, "formatted": "€102.49" },
    "currency": "EUR",
    "items": [
      {
        "id": 67890,
        "product_name": "Digital Game Key",
        "variant_name": "Standard Edition",
        "quantity": 1,
        "unit_price": { "amount": 99.99, "formatted": "€99.99" },
        "total_price": { "amount": 99.99, "formatted": "€99.99" },
        "created_at": "2023-01-01T12:00:00+00:00",
        "updated_at": "2023-01-01T12:00:00+00:00"
      }
    ],
    "created_at": "2023-01-01T12:00:00+00:00",
    "updated_at": "2023-01-01T12:00:00+00:00"
  }
}

422 — Validation / Business Rule Error

{
  "message": "Insufficient funds in wallet"
}

500 — Server Error

{
  "message": "An unexpected error occurred while processing your order."
}