Create Order

Creates an order directly without going through the cart flow

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.

Idempotent Retries

If a request times out or your connection drops before you see the response, it’s safe to retry it as long as you send the same Idempotency-Key header both times. If an order was already created for that key, the retry returns that same order instead of creating a second one, so you won’t be charged twice.

Header	Type	Required	Description
Idempotency-Key	string	Recommended	A key unique to this purchase attempt (a UUID or your own order reference works). Reusing the same key on a retry returns the original order.

Idempotency-Key: 5f8d0d31-6f1a-4e2c-9d3b-2c7a1e9b4f10

Without this header, every request creates a new order, even if it’s an exact duplicate of one you just sent. That’s unchanged from before, so existing integrations aren’t affected if you don’t set it. We recommend adding it to any client that retries automatically.

Request Body

Field	Type	Required	Description
wallet_id	string (UUID)	✅	The ID of the wallet to use for payment
items	array	✅	Array of items to purchase
items[].product_variant_id	integer	✅	ID of the product variant
items[].quantity	integer	✅	Quantity to purchase (minimum: 1)

Example Request

curl -X POST https://api.manastore.com/api/v1/orders \
  -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f8d0d31-6f1a-4e2c-9d3b-2c7a1e9b4f10" \
  -d '{
    "wallet_id": "123e4567-e89b-12d3-a456-426614174002",
    "items": [
      {
        "product_variant_id": 123,
        "quantity": 1
      }
    ]
  }'

Responses

Status	Description
201 Created	Order created successfully
401 Unauthorized	Missing or invalid authentication token
403 Forbidden	Access denied
422 Unprocessable Entity	Validation error or business rule violation (e.g. insufficient wallet funds)
500 Internal Server Error	Unexpected 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."
}