> ## 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 mobile top-up order. `userMeta` with recipient phone details is required. Set `performOperatorValidation: 1` to validate the operator before placing the 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 | **Path** | **Type** | **Description** | | ------------------------------- | -------- | ------------------------------------------------------- | | data | object | Root request object. | | data.productId | number | Product ID for the top-up plan. | | data.quantity | number | Quantity of the top-up purchase (always `1` typically). | | data.denomination | number | Recharge/top-up amount. | | data.email | string | Customer email for notifications. | | data.tag | string | Optional tracking tag. | | data.poNumber | string | Client-provided PO number (idempotency key). | | data.notifyReceiverEmail | number | Whether user gets email notification (`1` = yes). | | data.performOperatorValidation | boolean | Performs operator validation. | | data.notifyAdminEmail | number | Whether admin receives notification (`1` = yes). | | data.userMeta | object | Mobile top-up specific parameters. | | data.topupData.topupPhoneCode | string | Country code prefix (e.g., `+91`). | | data.topupData.topupPhoneNumber | string | Mobile number to be recharged. | ## Response Schema | **Path** | **Type** | **Description** | | ---------------------------------------------------- | -------- | -------------------------------------- | | data | object | Root response object. | | data.placeOrder | object | Place order result. | | data.placeOrder.status | number | API execution status (`1` = success). | | data.placeOrder.data | object | Complete order details. | | data.placeOrder.data.orderId | number | Unique order ID. | | data.placeOrder.data.orderTotal | number | Order total (rounded). | | data.placeOrder.data.rawOrderTotal | number | Exact unrounded order amount. | | data.placeOrder.data.orderDiscount | string | Discount amount applied. | | data.placeOrder.data.rawOrderDiscount | string | Precise unrounded discount. | | data.placeOrder.data.discountPercent | string | Discount percent. | | data.placeOrder.data.currencyCode | string | Currency code. | | data.placeOrder.data.currencyValue | number | Currency conversion multiplier. | | data.placeOrder.data.amountCharged | number | Final charged amount. | | data.placeOrder.data.orderStatus | string | Order lifecycle status. | | data.placeOrder.data.deliveryStatus | string | Delivery status (`pending`, etc.). | | data.placeOrder.data.tag | string | Tag from request. | | data.placeOrder.data.quantity | number | Quantity ordered. | | data.placeOrder.data.vouchers | array | Always empty for top-up. | | data.placeOrder.data.voucherDetails | array | Summary of top-up item(s). | | data.placeOrder.data.voucherDetails\[].orderId | number | Order ID. | | data.placeOrder.data.voucherDetails\[].productId | number | Product ID. | | data.placeOrder.data.voucherDetails\[].productName | string | Name of the telecom/data top-up. | | data.placeOrder.data.voucherDetails\[].currencyCode | string | Currency code for the product. | | data.placeOrder.data.voucherDetails\[].productStatus | string | Status (`pending`). | | data.placeOrder.data.voucherDetails\[].denomination | number | Recharge amount. | | data.placeOrder.data.voucherDetails\[].vendorLogo | string | Logo of telecom vendor (may be empty). | | data.placeOrder.data.orderMeta | object | Metadata passed in request. | | data.placeOrder.data.orderMeta.email | string | Email submitted during request. | ## 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 products is 1 as mentioned 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. A new boolean parameter, **performOperatorValidation**, has been introduced. When set to **0,** no operator validation is performed and the order is attempted directly using the operator provided in the request. When set to 1, the system validates the requested operator against the operator identified from the vendor; if both match, the order proceeds successfully, and if they do not match, the order is rejected with an operator validation error. 6. Should you get a 5xx error from the PlaceOrderAPI, please call [GetOrderDetails](https://developers.xoxoday.com/v1.2/reference/get-order-details-api-4) 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-mobile-top-up.yaml POST /placeOrder openapi: 3.0.3 info: title: Xoxoday Rewards API – Mobile Top-Up version: '1.2' description: > Mobile Top-Up API endpoints for browsing the catalog, looking up operators, 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` - `getMobileTopUpCatalog`, `getMobileOperator`, `placeOrder`, `getOrderDetails`, `getOrderHistory` → `accounts.xoxoday.com` **Get Balance** sends parameters as URL query string (not request body). 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 mobile top-up order. `userMeta` with recipient phone details is required. Set `performOperatorValidation: 1` to validate the operator before placing the order. **Real URL:** `POST https://accounts.xoxoday.com/chef/v1/oauth/api` operationId: topupPlaceOrder 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 - userMeta properties: productId: type: integer description: Top-up product ID to order. example: 15365 quantity: type: integer example: 1 denomination: type: number description: Top-up amount. example: 20 email: type: string format: email example: your.email@example.com tag: type: string example: Rewarding poNumber: type: string description: Must be unique per order. example: PO12662 notifyReceiverEmail: type: integer enum: - 0 - 1 example: 1 notifyAdminEmail: type: integer enum: - 0 - 1 example: 0 performOperatorValidation: type: integer enum: - 0 - 1 description: >- `1` = validate the operator before placing the order. example: 0 userMeta: type: object required: - topupPhoneCode - topupPhoneNumber description: Recipient phone details for the top-up. properties: topupPhoneCode: type: string description: Country calling code for the recipient's number. example: '+91' topupPhoneNumber: type: string description: Recipient's phone number (without country code). example: '9857535678' example: query: plumProAPI.mutation.placeOrder tag: plumProAPI variables: data: productId: 15365 quantity: 1 denomination: 20 email: your.email@example.com tag: Rewarding poNumber: PO12662 notifyReceiverEmail: 1 notifyAdminEmail: 0 performOperatorValidation: 0 userMeta: topupPhoneCode: '+91' topupPhoneNumber: '9857535678' responses: '200': description: Top-up 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 currencyCode: type: string amountCharged: type: number orderStatus: type: string deliveryStatus: 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 `' ````