Create Order

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": "#12345",
    "transaction_id": "01J9Z3NDF0RXKQ5V3Q8M2B7C1D",
    "fulfillment_status": "processing",
    "payment_status": "completed",
    "subtotal": {
      "amount": "4426",
      "currency": "USD",
      "formatted": "$44.26",
      "decimal": "44.26",
      "localized_decimal": "44.26"
    },
    "conversion_fees": {
      "amount": "0",
      "currency": "USD",
      "formatted": "$0.00",
      "decimal": "0.00",
      "localized_decimal": "0.00"
    },
    "total": {
      "amount": "4426",
      "currency": "USD",
      "formatted": "$44.26",
      "decimal": "44.26",
      "localized_decimal": "44.26"
    },
    "currency": "USD",
    "items": [
      {
        "id": 67890,
        "quantity": 2,
        "variant_name": "PlayStation Network Card $25 USA",
        "product_name": "PlayStation Network Card $25 USA",
        "unit_price": {
          "amount": "2213",
          "currency": "USD",
          "formatted": "$22.13",
          "decimal": "22.13",
          "localized_decimal": "22.13"
        },
        "total_price": {
          "amount": "4426",
          "currency": "USD",
          "formatted": "$44.26",
          "decimal": "44.26",
          "localized_decimal": "44.26"
        },
        "product_id": 1042,
        "product_variant_id": 1042,
        "sku": "1042",
        "status": "pending",
        "currency": "USD",
        "face_value": {
          "amount": "2500",
          "currency": "USD",
          "formatted": "$25.00",
          "decimal": "25.00",
          "localized_decimal": "25.00"
        },
        "created_at": "2026-10-01T12:00:00+00:00",
        "updated_at": "2026-10-01T12:00:45+00:00"
      }
    ],
    "created_at": "2026-10-01T12:00:00+00:00",
    "updated_at": "2026-10-01T12:00:45+00:00"
  }
}

422 — Validation / Business Rule Error

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

500 — Server Error

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

Overview

Orders

Products

Wallets

Transactions

Webhooks

Other

Create a Direct Purchase Order

Authentication

Idempotent Retries

Request Body

Example Request

Responses

201 — Order Created

422 — Validation / Business Rule Error

500 — Server Error

​Create a Direct Purchase Order

​Authentication

​Idempotent Retries

​Request Body

​Example Request

​Responses

​201 — Order Created

​422 — Validation / Business Rule Error

​500 — Server Error

Create a Direct Purchase Order

Authentication

Idempotent Retries

Request Body

Example Request

Responses

201 — Order Created

422 — Validation / Business Rule Error

500 — Server Error