BigCity Order Processing

Order Creation Workflow

Customer Purchase

[SKU, Qty]

Order Data

[JSON Payload]

API Call

[POST API]

Voucher Generation

[Voucher Codes]

Customer Notification

[Redemption Info]

API Endpoint

POST /v1/bigcity/redeemptiononskus

Create a new rewards redemption order based on customer purchases. The system analyzes the purchase data against available rewards and generates appropriate vouchers.

Authentication

Requires customer authentication token obtained from the customer auth endpoint.

Required Headers

Authorization: Bearer {customer_auth_token}

Content-Type: application/json

Request Parameters

Parameter	Type	Required	Description
`order_timestamp`	datetime	Yes	ISO 8601 timestamp when order was placed
`order_total`	numeric	Yes	Total monetary value of the order
`order_items`	numeric	Yes	Total number of unique items in the order
`line_items`	array	Yes	Array of order line items with SKU details

Line Item Object

Field	Type	Required	Description
`order_id`	string	Yes	Unique identifier for the order
`SKU`	string	Yes	Product SKU code
`qty`	integer	Yes	Quantity of the item purchased

Request & Response Examples

{
  "order_timestamp": "2025-10-13T15:42:36-04:00",
  "order_total": 1500,
  "order_items": 3,
  "line_items": [
    {
      "order_id": "ORD-2025-001234",
      "SKU": "NUTRI-SEEDS-1200",
      "qty": 2
    },
    {
      "order_id": "ORD-2025-001234", 
      "SKU": "NUTRI-OATS-MULTI",
      "qty": 1
    },
    {
      "order_id": "ORD-2025-001234",
      "SKU": "NUTRI-HERBS-800",
      "qty": 1
    }
  ]
}

200 OK

{
  "id": 45654654654,
  "order_id": "ORD-2025-001234",
  "state": "success",
  "vouchers": [
    {
      "voucher_code": "BCP123456",
      "pin": "1234",
      "validity": "2024-03-26"
    },
    {
      "voucher_code": "BCP789012",
      "pin": "5678", 
      "validity": "2024-03-26"
    }
  ],
  "redemption_url": "https://bigcity.in/redeem",
  "how_to_avail": "Visit our redemption portal and enter your voucher code...",
  "terms": "Terms and conditions: 1. Valid for 90 days...",
  "note": "Order created successfully.",
  "created_at": "2025-10-13T15:42:36-04:00",
  "updated_at": "2025-10-13T15:42:36-04:00"
}

422 Unprocessable Entity

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

Response Schema

Order Response Object

Field	Type	Description
`id`	integer	Unique redemption order identifier
`order_id`	string	Original order reference ID
`state`	string	Order processing state (success/failed/pending)
`vouchers`	array	Generated voucher codes
`redemption_url`	string	URL for voucher redemption
`how_to_avail`	string	HTML instructions for using vouchers
`terms`	string	HTML terms and conditions
`note`	string	Status message or additional information

Voucher Object

Field	Type	Description
`voucher_code`	string	Unique voucher code for redemption
`pin`	string	Optional security PIN (4 characters)
`validity`	string	Expiration date (YYYY-MM-DD format)

Order States

success

Order processed successfully

Deliver vouchers to customer

failed

Order processing failed

Review error details

pending

Order awaiting processing

Monitor for state changes

expired

Order has expired

Create new order if needed

BigCity Rewards