> ## Documentation Index > Fetch the complete documentation index at: https://help-plum.xoxoday.com/llms.txt > Use this file to discover all available pages before exploring further. # Place Order API > Place an order for a voucher. A unique `poNumber` must be sent for every unique order to prevent duplicates. Maximum response time for realtime products is 120 seconds. If you receive a 5xx error, call Get Order Details with the `poNumber` to check if an order was created before retrying. **Real URL:** `POST https://stagingstores.xoxoday.com/chef/v1/oauth/api` > For orders placed with realtime products, the maximum response time is 120 seconds > > A unique reference ID needs to be sent for every unique order in the "poNumber" parameter > > We strongly recommend storing the request and response of every "PlaceOrderAPI" call ## Request Schema | Parameter | Type | Description | | :------------------ | :-------- | :---------------------------------------------------- | | productId | Int | Unique ID of the product to be ordered. | | quantity | Int | Number of units to be ordered. | | denomination | Float | Value/amount of the voucher or reward. | | email | String | Recipient’s email address. | | contact | String | Recipient’s contact number. | | poNumber | String | Purchase Order number to avoid duplicate orders. | | tag | String | Custom tag to identify or categorize the order. | | notifyAdminEmail | Int (0/1) | Flag to notify admin via email (1 = Yes, 0 = No). | | notifyReceiverEmail | Int (0/1) | Flag to notify recipient via email (1 = Yes, 0 = No). | ## Response Schema | **Path** | **Type** | **Description** | | ---------------------------------------------------- | -------- | ----------------------------------------------- | | data | object | Root response object. | | data.placeOrder | object | Container for the place order result. | | data.placeOrder.status | number | API execution status (`1` = success). | | data.placeOrder.data | object | Full order details. | | data.placeOrder.data.orderId | number | Unique order ID generated by Xoxoday. | | data.placeOrder.data.orderTotal | number | Order total before applying discounts. | | data.placeOrder.data.orderDiscount | string | Discount amount | | data.placeOrder.data.discountPercent | string | Discount percentage | | data.placeOrder.data.currencyCode | string | Currency code for the order. | | data.placeOrder.data.currencyValue | number | Currency conversion multiplier (usually `1`). | | data.placeOrder.data.amountCharged | number | Final amount charged to the customer. | | data.placeOrder.data.orderStatus | string | Overall status of the order (e.g., `complete`). | | data.placeOrder.data.deliveryStatus | string | Delivery status (e.g., `delivered`). | | data.placeOrder.data.tag | string | Custom tag passed from the request. | | data.placeOrder.data.quantity | number | Number of vouchers ordered. | | data.placeOrder.data.vouchers | array | List of delivered voucher objects. | | data.placeOrder.data.vouchers\[].productId | number | Product ID for the voucher. | | data.placeOrder.data.vouchers\[].orderId | number | Order ID associated with the voucher. | | data.placeOrder.data.vouchers\[].voucherCode | string | Voucher code delivered. | | data.placeOrder.data.vouchers\[].pin | string | PIN of the voucher. | | data.placeOrder.data.vouchers\[].validity | string | Voucher validity/expiry date. | | data.placeOrder.data.vouchers\[].amount | number | Voucher amount/value. | | data.placeOrder.data.vouchers\[].currency | string | Currency code for the voucher. | | data.placeOrder.data.vouchers\[].country | string | Country code where voucher is valid. | | data.placeOrder.data.vouchers\[].type | string | Voucher type (`codePin`, etc.). | | data.placeOrder.data.vouchers\[].currencyValue | number | FX conversion multiplier for voucher value. | | data.placeOrder.data.voucherDetails | array | Summary of voucher products in the order. | | data.placeOrder.data.voucherDetails\[].orderId | number | Order ID. | | data.placeOrder.data.voucherDetails\[].productId | number | Product ID. | | data.placeOrder.data.voucherDetails\[].productName | string | Product name. | | data.placeOrder.data.voucherDetails\[].currencyCode | string | Product currency code. | | data.placeOrder.data.voucherDetails\[].productStatus | string | Delivery status for this product. | | data.placeOrder.data.voucherDetails\[].denomination | number | Voucher denomination. | ## Implementation Notes 1. To avoid facing an error while placing an order, please pass the valid productID and denomination 2. The maximum order quantity allowed for the majority of the products is 10 unless mentioned otherwise in the **"orderQuantityLimit"** parameter in the GetVouchersAPI 3. Certain brands require a phone number to process the order. You can refer to the **"isPhoneNumberMandatory"** parameter in the GetVouchersAPI to identify the products with this mandate 4. Should you wish to notify the recipient via email, please pass "1" in the **"notifyReceiverEmail"** parameter 5. We recommend you store the **"poNumber"** that you pass in the request and the **"orderID"** you receive in the response 6. The **"type"** parameter indicates the type in which the voucher is delivered. The 4 types are as follows: 1. code 2. codePin 3. url 4. urlPin 7. Should you get a 5xx error from the PlaceOrderAPI, please call [GetOrderDetails](https://developers.xoxoday.com/v1.2/reference/get-order-details-api) and confirm if an order exists using the poNumber. If there's no order against the poNumber, you can go ahead and place another order > Learn how to manage [webhooks](https://developers.xoxoday.com/v1.2/docs/webhooks-1) to receive order status updates for delayed product types. ## OpenAPI ````yaml specs/rewards-giftcard.yaml POST /placeOrder openapi: 3.0.3 info: title: Xoxoday Rewards API – Giftcard version: '1.2' description: > Giftcard API endpoints for browsing the catalog, placing orders, and reporting. All operations dispatch to `POST /v1/oauth/api` on the real server. OpenAPI does not allow multiple POST operations on the same path, so each operation uses a short virtual path suffix under the default server for playground differentiation. **Real URL for all operations:** `POST https://stagingstores.xoxoday.com/chef/v1/oauth/api` servers: - url: https://stagingstores.xoxoday.com/chef/v1/oauth/api description: Sandbox - url: https://accounts.xoxoday.com/chef/v1/oauth/api description: Production - url: https://canvas.xoxoday.com/chef/v1/oauth/api description: Testing security: - BearerAuth: [] tags: - name: Catalog - name: Orders - name: Reporting paths: /placeOrder: post: tags: - Orders summary: Place Order API description: > Place an order for a voucher. A unique `poNumber` must be sent for every unique order to prevent duplicates. Maximum response time for realtime products is 120 seconds. If you receive a 5xx error, call Get Order Details with the `poNumber` to check if an order was created before retrying. **Real URL:** `POST https://stagingstores.xoxoday.com/chef/v1/oauth/api` operationId: giftcardPlaceOrder requestBody: required: true content: application/json: schema: type: object required: - query - tag - variables properties: query: type: string enum: - plumProAPI.mutation.placeOrder default: plumProAPI.mutation.placeOrder tag: type: string enum: - plumProAPI default: plumProAPI variables: type: object required: - data properties: data: type: object required: - productId - quantity - denomination - poNumber properties: productId: type: integer description: Unique ID of the product to order. example: 15365 quantity: type: integer description: Number of units to order. Max 10 for most products. example: 1 denomination: type: number description: Value/amount of the voucher. example: 20 email: type: string format: email description: Recipient's email address. example: your.email@example.com contact: type: string description: Recipient's contact number. example: +1-4705000000 tag: type: string description: Custom tag to identify or categorize the order. example: Rewarding poNumber: type: string description: Purchase Order number — must be unique per order. example: PO12662 notifyReceiverEmail: type: integer enum: - 0 - 1 description: '`1` = notify recipient via email.' example: 0 notifyAdminEmail: type: integer enum: - 0 - 1 description: '`1` = notify admin via email.' example: 0 example: query: plumProAPI.mutation.placeOrder tag: plumProAPI variables: data: productId: 15365 quantity: 1 denomination: 20 email: your.email@example.com contact: +1-4705000000 tag: Rewarding poNumber: PO12662 notifyReceiverEmail: 0 notifyAdminEmail: 0 responses: '200': description: Order placed successfully. content: application/json: schema: type: object properties: data: type: object properties: placeOrder: type: object properties: status: type: number data: type: object properties: orderId: type: number orderTotal: type: number orderDiscount: type: string discountPercent: type: string currencyCode: type: string currencyValue: type: number amountCharged: type: number orderStatus: type: string deliveryStatus: type: string tag: type: string quantity: type: number vouchers: type: array items: type: object properties: productId: type: number orderId: type: number voucherCode: type: string pin: type: string validity: type: string amount: type: number currency: type: string country: type: string type: type: string example: data: placeOrder: status: 1 data: orderId: 98765432 orderTotal: 20 currencyCode: USD amountCharged: 20 orderStatus: complete deliveryStatus: delivered quantity: 1 vouchers: - productId: 15365 orderId: 98765432 voucherCode: ABCD-1234-EFGH pin: '9876' validity: '2027-12-31' amount: 20 currency: USD country: US type: codePin '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '502': $ref: '#/components/responses/BadGateway' components: responses: BadRequest: description: Invalid request body or parameters. content: application/json: schema: type: object properties: error: type: string message: type: string Unauthorized: description: Missing or invalid access token. content: application/json: schema: type: object properties: error: type: string example: Unauthorized BadGateway: description: Upstream service error. securitySchemes: BearerAuth: type: http scheme: bearer description: '`Authorization: Bearer `' ````