Orders & Dispatch

Bulk Order

Creates multiple orders in one request. Optional Idempotency-Key applies to the bulk operation.

Responses

201 when orders are created synchronously (or idempotent replay), with orders, summary, and optional rejectedOrders.
202 when async processing is enabled (orderRequestId, status: queued); poll GET /api/v1/business/orders/order-requests/{id}.
402 when the wallet balance (after holds) is insufficient for the bulk total.

How to call — POST {server}/api/v1/business/orders/bulk with X-API-Key and JSON body { "orders": [ ... ] } (each item matches CreateOrderRequest).

POST

api

business

orders

bulk

Bulk Order

curl --request POST \
  --url https://api-stage.ugift.me/api/v1/business/orders/bulk \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "orders": [
    {
      "productCode": "<string>",
      "merchant": "<string>",
      "currency": "GBP",
      "valuePurchased": 123,
      "recipientEmail": "jsmith@example.com",
      "recipientName": "<string>",
      "giftMessage": "<string>"
    }
  ]
}
'

{
  "success": true,
  "orders": [
    {
      "_id": "65b0d1e2f3a4b56789012345",
      "productCode": "AMAZON_UK_STD",
      "merchant": {
        "name": "Amazon UK"
      },
      "currency": "GBP",
      "valuePurchased": 25,
      "status": "active",
      "imageUrl": "https://cdn.ugift.me/products/amazon-uk-card.png"
    },
    {
      "_id": "65b0d1e2f3a4b56789012346",
      "productCode": "JL_UK_STD",
      "merchant": {
        "name": "John Lewis"
      },
      "currency": "GBP",
      "valuePurchased": 50,
      "status": "active",
      "imageUrl": "https://cdn.ugift.me/products/johnlewis-card.png"
    }
  ],
  "summary": {
    "totalOrders": 2,
    "totalValue": 75,
    "currency": "GBP",
    "remainingBalance": 1925.5
  },
  "rejectedOrders": [
    {
      "productCode": "UNKNOWN_CODE",
      "reason": "Product not found"
    }
  ]
}

Authorizations

X-API-Key

string

header

required

Your UGiftMe API key for authentication.

Format: Secure API key (e.g., <your-api-key>)

Required: All endpoints require this header

Example: X-API-Key: <your-api-key>

Headers

Idempotency-Key

string

Body

application/json

orders

object[]

required

Show child attributes

Response

Bulk orders created (sync path or idempotent replay)

success

boolean

required

Example:

true

orders

object[]

required

Show child attributes

summary

object

required

Show child attributes

rejectedOrders

object[]

Show child attributes

Order HistoryLists orders associated with your account (paginated). **How to call** — **GET** `{server}/api/v1/business/orders` with `X-API-Key` and optional `page`, `limit`, `sortBy`, `order`.

Bulk Order

curl --request POST \
  --url https://api-stage.ugift.me/api/v1/business/orders/bulk \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "orders": [
    {
      "productCode": "<string>",
      "merchant": "<string>",
      "currency": "GBP",
      "valuePurchased": 123,
      "recipientEmail": "jsmith@example.com",
      "recipientName": "<string>",
      "giftMessage": "<string>"
    }
  ]
}
'

{
  "success": true,
  "orders": [
    {
      "_id": "65b0d1e2f3a4b56789012345",
      "productCode": "AMAZON_UK_STD",
      "merchant": {
        "name": "Amazon UK"
      },
      "currency": "GBP",
      "valuePurchased": 25,
      "status": "active",
      "imageUrl": "https://cdn.ugift.me/products/amazon-uk-card.png"
    },
    {
      "_id": "65b0d1e2f3a4b56789012346",
      "productCode": "JL_UK_STD",
      "merchant": {
        "name": "John Lewis"
      },
      "currency": "GBP",
      "valuePurchased": 50,
      "status": "active",
      "imageUrl": "https://cdn.ugift.me/products/johnlewis-card.png"
    }
  ],
  "summary": {
    "totalOrders": 2,
    "totalValue": 75,
    "currency": "GBP",
    "remainingBalance": 1925.5
  },
  "rejectedOrders": [
    {
      "productCode": "UNKNOWN_CODE",
      "reason": "Product not found"
    }
  ]
}