> ## 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 a charity donation order. A unique `poNumber` must be sent per order. **Real URL:** `POST https://accounts.xoxoday.com/chef/v1/oauth/api` > 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. Should you wish to notify the recipient via email, please pass "1" in the **"notifyReceiverEmail"** parameter 4. We recommend you store the "poNumber" that you pass in the request and the\*\*"orderID"\*\* you receive in the response. 5. Should you get a 5xx error from the PlaceOrderAPI, please call [GetOrderDetails](https://developers.xoxoday.com/v1.2/reference/get-order-details-api-2) 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-charity.yaml POST /placeOrder openapi: 3.0.3 info: title: Xoxoday Rewards API – Charity version: '1.2' description: > Charity API endpoints for browsing the charity catalog, placing orders, and reporting. All operations dispatch to `POST /v1/oauth/api`. Virtual path suffixes are used for playground differentiation since OpenAPI does not allow multiple POST operations on the same path. **Host split:** - `getFilters`, `getBalance`, `paymentHistory` → `stagingstores.xoxoday.com` - `getCharity`, `placeOrder`, `getOrderDetails`, `getOrderHistory` → `accounts.xoxoday.com` 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 a charity donation order. A unique `poNumber` must be sent per order. **Real URL:** `POST https://accounts.xoxoday.com/chef/v1/oauth/api` operationId: charityPlaceOrder 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: Charity product ID to order. example: 15365 quantity: type: integer description: Number of units to order. example: 1 denomination: type: number description: Donation amount. example: 20 email: type: string format: email description: Donor's email address. example: your.email@example.com contact: type: string description: Donor's contact number. example: +1-4705000000 tag: type: string description: Optional tag for internal tracking. example: Rewarding poNumber: type: string description: >- Client-generated PO 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: Charity 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 voucherDetails: type: array items: type: object properties: orderId: type: number productId: type: number productName: type: string currencyCode: type: string productStatus: type: string denomination: type: number '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '502': $ref: '#/components/responses/BadGateway' 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 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 `' ````