POST /api/v1/orders

Description

Create a reward redemption order. Allows customers to redeem their wallet points for available rewards from the catalog.

Headers

Authorization

Bearer token received after successful OTP verification.

Content-Type

application/json

Parameters

order_timestamp required, type: datetime

ISO 8601 timestamp when the order was placed.

order_total required, type: number

Total value of the order in points.

order_items required, type: number

Total number of unique items in the order.

line_items required, type: array

Array of order line items.

line_items[].order_id required, type: string

Client-generated order reference ID.

line_items[].SKU required, type: string

Stock Keeping Unit of the product to redeem.

line_items[].qty required, type: number

Quantity of units to redeem.

Example Request

{
  "order_timestamp": "2021-03-26T15:42:36-04:00",
  "order_total": 1500,
  "order_items": 3,
  "line_items": [
    {
      "order_id": "asdsa3432",
      "SKU": "SKU1",
      "qty": 1
    }
  ]
}

Example Response

{
  "id": 45654654654,
  "order_id": "asdsa3432",
  "state": "success",
  "vouchers": [
    {
      "voucher_code": "BCP123456",
      "pin": "4 characters / optional*",
      "validity": "2024-03-26"
    }
  ],
  "redemption_url": "bigcity.in",
  "how_to_avail": "",
  "terms": "",
  "note": "Order created successfully.",
  "created_at": "2021-03-26T15:42:36-04:00",
  "updated_at": "2021-03-26T15:42:36-04:00"
}

Example of Error Response

{
  "name": "Unprocessable entity",
  "message": "Validation Failed",
  "code": 37,
  "status": 422,
  "type": "yii\\web\\HttpException"
}

Response Fields

id type: number

Bigcity system order ID.

order_id type: string

Client-provided order reference ID.

state type: string

Order status (e.g., "success").

vouchers type: array

Array of generated voucher details.

vouchers[].voucher_code type: string

Generated voucher code for redemption.

vouchers[].pin type: string

PIN code (optional, if applicable).

vouchers[].validity type: string

Voucher expiry date (YYYY-MM-DD).

redemption_url type: string

URL where voucher can be redeemed.

how_to_avail type: string

Instructions for availing the voucher.

terms type: string

Terms and conditions.

note type: string

Additional notes or status message.

created_at type: datetime

Order creation timestamp.

updated_at type: datetime

Order last update timestamp.

Redemption Rules

  • Points are deducted immediately after successful redemption
  • Customer cannot redeem beyond available wallet balance
  • Redemption requests are subject to product availability