> ## 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 merchandise order. A unique `poNumber` must be sent per order. Shipping details are required and passed as flat fields directly inside `data`. **Note:** `productId` is a string for this endpoint. **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 Parameter | **Path** | **Type** | **Description** | | ------------------------ | -------- | ----------------------------------------------------- | | data | object | Root request wrapper. | | data.productId | string | Product ID of the merchandise item. | | data.quantity | number | Quantity of the merchandise item. | | data.denomination | number | Denomination/price of the product. | | data.email | string | Customer email for notifications. | | data.contact | string | Customer phone number. | | data.tag | string | Custom tag passed for tracking. | | data.poNumber | string | Client-generated PO number (idempotency key). | | data.notifyReceiverEmail | number | Whether the receiver gets an email (`1` = yes). | | data.notifyAdminEmail | number | Whether admin gets an email notification (`1` = yes). | | data.shippingFirstName | string | Shipping first name. | | data.shippingLastName | string | Shipping last name. | | data.shippingContactNo | string | Shipping contact number. | | data.shippingCompany | string | Company name for shipping. | | data.shippingAddress1 | string | Primary shipping address. | | data.shippingAddress2 | string | Secondary shipping address. | | data.shippingCity | string | Shipping city. | | data.shippingCountry | string | Shipping country. | | data.shippingState | string | Shipping state/province/region. | | data.shippingPostcode | string | Postal/ZIP code for the shipping address. | ## Response Parameter | **Path** | **Type** | **Description** | | ---------------------------------------------------- | -------- | -------------------------------------------------------- | | data | object | Root response object. | | data.placeOrder | object | Container for order response. | | data.placeOrder.status | number | Request status (`1` = success). | | data.placeOrder.data | object | Full order details. | | data.placeOrder.data.orderId | number | Unique order ID. | | data.placeOrder.data.orderTotal | number | Order total (rounded). | | data.placeOrder.data.rawOrderTotal | number | Precise unrounded order amount. | | data.placeOrder.data.orderDiscount | string | Discount amount (blank if none). | | data.placeOrder.data.rawOrderDiscount | string | Unrounded discount (blank if none). | | data.placeOrder.data.discountPercent | string | Discount percent applied. | | data.placeOrder.data.currencyCode | string | Currency code used for pricing. | | data.placeOrder.data.currencyValue | number | Currency conversion multiplier. | | data.placeOrder.data.amountCharged | number | Final amount charged. | | data.placeOrder.data.orderStatus | string | Order lifecycle status (`complete`). | | data.placeOrder.data.deliveryStatus | string | Delivery status (`pending`). | | data.placeOrder.data.tag | string | Tag passed from request. | | data.placeOrder.data.quantity | number | Quantity ordered. | | data.placeOrder.data.vouchers | array | Always empty for merchandise (no instant code delivery). | | data.placeOrder.data.voucherDetails | array | Summary of merchandise items ordered. | | data.placeOrder.data.voucherDetails\[].orderId | number | Order ID. | | data.placeOrder.data.voucherDetails\[].productId | number | Merchandise product ID. | | data.placeOrder.data.voucherDetails\[].productName | string | Product name. | | data.placeOrder.data.voucherDetails\[].currencyCode | string | Currency code of the merchandise. | | data.placeOrder.data.voucherDetails\[].productStatus | string | Status of merchandise fulfillment. | | data.placeOrder.data.voucherDetails\[].denomination | number | Product denomination/price. | ## 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. Should you get a 5xx error from the PlaceOrderAPI, please call [GetOrderDetails](https://developers.xoxoday.com/v1.2/reference/get-order-details-api-3) 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-merchandise.yaml POST /placeOrder openapi: 3.0.3 info: title: Xoxoday Rewards API – Merchandise version: '1.2' description: > Merchandise API endpoints for browsing the 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` - `getMerchandise`, `placeOrder`, `getOrderDetails`, `getOrderHistory` → `accounts.xoxoday.com` **Notable differences from other categories:** - Place Order: `productId` is a string, shipping fields are flat inside `data` - Get Order Details: `variables` fields are flat (no `data` wrapper) 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 merchandise order. A unique `poNumber` must be sent per order. Shipping details are required and passed as flat fields directly inside `data`. **Note:** `productId` is a string for this endpoint. **Real URL:** `POST https://accounts.xoxoday.com/chef/v1/oauth/api` operationId: merchandisePlaceOrder 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: string description: Merchandise product ID (passed as string). example: '15365' quantity: type: integer example: 1 denomination: type: number example: 20 email: type: string format: email example: your.email@example.com contact: type: string example: +1-4705000000 tag: type: string example: Rewarding poNumber: type: string description: Must be unique per order. example: '228291910' notifyReceiverEmail: type: integer enum: - 0 - 1 example: 0 notifyAdminEmail: type: integer enum: - 0 - 1 example: 0 shippingFirstName: type: string description: Recipient first name for shipping. example: John shippingLastName: type: string description: Recipient last name for shipping. example: Doe shippingContactNo: type: string description: Recipient contact number for shipping. example: +1-234567890 shippingCompany: type: string description: Company name for shipping label. example: Acme Inc. shippingAddress1: type: string description: Primary shipping address line. example: 123 Main St shippingAddress2: type: string description: Secondary shipping address line. example: Suite 400 shippingCity: type: string example: New York shippingCountry: type: string example: USA shippingState: type: string example: NY shippingPostcode: type: string example: '10001' 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: '228291910' notifyReceiverEmail: 0 notifyAdminEmail: 0 shippingFirstName: John shippingLastName: Doe shippingContactNo: +1-234567890 shippingCompany: Acme Inc. shippingAddress1: 123 Main St shippingAddress2: Suite 400 shippingCity: New York shippingCountry: USA shippingState: NY shippingPostcode: '10001' responses: '200': description: Merchandise 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 `' ````