--- title: "Orders" canonical: "https://red-ant-documentation.refined.site/space/RDD/643760156/Orders" format: markdown --- > Macro (toc) ## Summary The RetailOS Orders API supports the standard CRUD interface similar to other RetailOS resources, however additional actions may be performed in addition to this. See below for more information. ## Creating vs Updating Orders Typically when an order is created in RetailOS a new order object is created to represent the order. ![Order Creation Flow Diagram](media://4ad2df23-ebac-48cf-820d-6bee3613b389) In the case of updates usually the original order is voided and a new order is created. The status of the original order, and new order will vary based on the action performed on the order. These changes are detailed further below. ![Order Edit Flow Diagram](media://21341437-a84d-4bad-8902-e6bb7ae5b5f5) ## Endpoints ### API Reference [https://digital-store-api-qa.redant.cloud/v2/docs/#/Orders](https://digital-store-api-qa.redant.cloud/v2/docs/#/Orders) ### Reassign an order ***URL:*** `POST /v2/orders/{id}/reassign` ***Summary:*** Updates the current order to void, creates a new order with a reassigned user. ***Reference and examples: ***[https://digital-store-api-qa.redant.cloud/v2/docs/#/Orders/post_orders__id__reassign](https://digital-store-api-qa.redant.cloud/v2/docs/#/Orders/post_orders__id__reassign) #### Example: Reassigning a customer This example illustrates the reassigning of a Customer to an Order with an Order Number of `0726-324533-6059`. When this happens, the following changes occur: Original order: - `status` set to `void` New order: - `id` - Auto-generated uuid - `orderNumber` - Same as original order - `status` - Same as original order - `customerId` - Reassigned customer (if reassign is a customer reassignment) - `userId` - Reassigned user (if reassign is a user reassignment) #### Before reassignment: ``` { "id": "f084edfe-0778-435c-89c5-1d7245befc40", "status": "complete", "total": { "code": "GBP", "value": 28 }, "orderNumber": "0726-324533-6059", "products": [...], "customerId": "f3aa9c6c-9792-4872-9219-f42f98b090b8", "...other order fields" } ``` #### After reassignment (Original Record): ``` { "id": "f084edfe-0778-435c-89c5-1d7245befc40", "status": "void", "total": { "code": "GBP", "value": 28 }, "orderNumber": "0726-324533-6059", "products": [...], "customerId": "f3aa9c6c-9792-4872-9219-f42f98b090b8", "...other order fields" } ``` #### After reassignment (Original Record): ``` { "id": "06770574-0c6d-4b5e-885f-59a9b821c636", "status": "complete", "total": { "code": "GBP", "value": 28 }, "orderNumber": "0726-324533-6059", "products": [...], "customerId": "11e5e463-680a-4706-be05-0d251aecf358", "...other order fields" } ``` ### Refund an order ***URL:*** `POST /v2/orders/{id}/refund` ***Summary:*** Refund some or all (partial/full refund) products in an order. Sets `refund=true` to products being refunded and creates a new order to refund corresponding products. ***Reference and examples: ***[https://digital-store-api-qa.redant.cloud/v2/docs/#/Orders/post_orders__id__refund](https://digital-store-api-qa.redant.cloud/v2/docs/#/Orders/post_orders__id__refund) #### Example: Refunding an Order This example illustrates the reassigning of a Customer to an Order with an Order Number of `0726-324416-9582`. When this happens, the following changes occur: Current order: - `products[].total.value` set to the negative value of the item - `products[].hasBeenRefunded` set to `true` for refunded products New order: - `id` - Auto-generated uuid - `previousOrderId` - uuid of the previous order - `orderNumber` - Auto-generated number - `status` - set to `partial_refund` or `full_refund` - `products` - refunded products with negative price values - `products[].refund` set to `true` for refunded products #### After refund (Original Order) ```json { "id": "1f95ccd6-a552-418a-88c9-a51bc169ab32", "status": "complete", "total": { "code": "GBP", "value": 68 }, "orderNumber": "0726-324416-9582", "...other order fields" "products": [ { "id": "4ff6a891-78d3-4b9d-98fe-42614744b260", "name": "LE VERNIS\n917 OPULENCE 13ML", "total": { "code": "GBP", "value": -22 }, "productId": "53e6934e-bc42-462a-9467-04825ab7404f", "hasBeenRefunded": true, "...other product fields" }, { "id": "63a49f8f-42b2-4a98-8f57-574f130d51e3", "name": "LE BLANC\n20 MIMOSA 30ML", "total": { "code": "GBP", "value": 46 }, "productId": "9fddc002-c79b-4ede-b644-6c41b6107a46", "...other product fields" } ], "customerId": null } ``` #### After refund (New Order) ```json { "id": "4f2a9702-2ed2-4a0c-9b21-2fe4c664cbb0", "status": "partial_refund", "total": { "code": "GBP", "value": -22 }, "orderNumber": "0726-324490-2195", "...other order fields" "products": [ { "id": "4ff6a891-78d3-4b9d-98fe-42614744b260", "name": "LE VERNIS\n917 OPULENCE 13ML", "total": { "code": "GBP", "value": -22 }, "productId": "53e6934e-bc42-462a-9467-04825ab7404f", "refund": true, "...other product fields" } ], "customerId": null } ``` ### Exchange an order ***URL:*** `POST /v2/orders/{id}/exchange` ***Summary:*** Exchange a set of products for an order. Sets `hasBeenRefunded=true` to refunded products in the current order, creates a new order with the exchanged products. Current order updates: - `products[].hasBeenRefunded` set to `true` for refunded products New order values: - `id` - Auto-generated uuid - `previousOrderId` - uuid of the previous order - `orderNumber` - Auto-generated number - `status` - set to `exchange` - `products` - refunded products with negative price values, and exchanged products - `products[].refund` set to `true` for refunded products Try it [here](https://digital-store-api-qa.redant.cloud/v2/docs/#/Orders/post_orders__id__exchange) **Example:** Creating a new order with two products, Exchange one product for two other products ``` [ { "id": "31951a8b-4cc2-405b-9159-45b7eeab92b9", "status": "complete", "total": { "code": "GBP", "value": 92 }, "orderNumber": "0726-324888-6027", "...other order fields" "products": [ { "id": "9e8851bc-237c-4bae-897e-999cc1f99a37", "name": "CRISTALLE\nEAU DE PARFUM SPRAY 50ML", "total": { "code": "GBP", "value": 62 }, "productId": "774499b7-49bb-4435-8843-224751094984", "hasBeenRefunded": true, "...other product fields" }, { "id": "2753a961-cf49-419b-91a7-572c902b326e", "name": "PINCEAU OMBREUR ROND\nPINCEAU OMBREUR ROND 1PCE", "total": { "code": "GBP", "value": 30 }, "productId": "b8a7c1f6-8350-42fc-b7bd-fd6830f9e6da", "...other product fields" } ], "customerId": null }, { "id": "14d7ac52-98ed-42dc-b5f3-214eebd35d9c", "status": "exchange", "total": { "code": "GBP", "value": 149 }, "orderNumber": "0726-324207-6123", "...other order fields" "products": [ { "id": "9fa59751-f6ae-41c1-a1cd-8694e3c53c02", "name": "CRISTALLE\nEAU DE PARFUM SPRAY 50ML", "total": { "code": "GBP", "value": -62 }, "productId": "774499b7-49bb-4435-8843-224751094984", "refund": true, "...other product fields" }, { "id": "11e62ea2-e355-44c0-8cd3-f6ae38219ace", "name": "CC CREAM\n10 BEIGE TUBE 30ML", "total": { "code": "GBP", "value": 46 }, "productId": "25bf1a19-d8b6-4ede-86a1-7f3bfe2bdd6e", "...other product fields" }, { "id": "5a1b96e8-2c14-40c3-90f9-f78817593552", "name": "SUBLIMAGE MASQUE\nREVITALISING MASK JAR 50G", "total": { "code": "GBP", "value": 165 }, "productId": "9b19dade-2362-45c6-9a70-0704e449bd9f", "...other product fields" } ], "customerId": null } ]Copy to clipboardErrorCopied ``` ### Fetch Order Resource Config ***URL:*** `get /v2/orders/config` ***Summary:*** Fetch order configuration, currently only orderTypes are returned. Try it [here](https://digital-store-api-qa.redant.cloud/v2/docs/#/Orders/get_orders_config) ### Cancelling An Order ***URL:*** `POST /v2/orders/{id}/cancel` ***Summary:*** Sets the status of an order to cancelled. Try it [here](https://digital-store-api-qa.redant.cloud/v2/docs/#/Orders/post_orders__id__cancel) ## Advanced Usages ### Adding Order Notes Notes can be added to orders using the `details.notes` field. Available in `POST` , `PUT`, `PATCH` requests. **URL:** `PATCH /v2/orders/{id}` **Example Payload:** ``` { "details": { "notes": "This is a note" }, "updateSource": "RetailOS" } ``` ### Viewing previous order details in refunded orders Refunded orders in RetailOS include reference to their previous order via the `previousOrderId` field. If you wish to include that previous order in your GET requests, you can do so using the `includes` query parameter. This will return the full previous order in the the `previousOrder` field. **URL:** `GET /v2/orders/{id}?includes=previousOrder` **Example Response:** ``` { ... "previousOrderId": "25ed4abd-711a-43a3-86fc-5224270d4a5d" "previousOrder": { "id": "25ed4abd-711a-43a3-86fc-5224270d4a5d", "orderNumber": "1234567", ... } } ``` ## Order Payments This documentation provides an overview of the available APIs for managing payment options and payment states for orders. Each endpoint is defined with a summary, method, and URL. --- #### **1. Retrieve Payment Options for an Order (only used internally by RetailOS)** - **Endpoint:** `GET /v2/orders/{id}/payment-options` - **Description:** Returns a list of available payment options for the specified order. - *Note:* Initially sourced from a JSON file; consider expanding to a managed API in future iterations. - **Try it:** Try it here --- #### **2. Create Payment for an Order** - **Endpoint:** `POST /v2/orders/{id}/payment` - **Description:** Creates a new payment entry for the specified order, updating the payment state to reflect the remaining balance, among other details. - **Try it:** Try it here --- #### **3. Delete Payment for an Order** - **Endpoint:** `DELETE /v2/orders/{order_id}/payment/{payment_id}` - **Description:** Deletes an existing payment from the specified order, updating the payment state to reflect the remaining balance and other related details. - **Try it:** Try it here --- ### Example create payment payload (Used internally by RetailOS) Below is an example of the data model representing an order and its associated payment details. ```json { "orderPayment": { "card": { "type": "AMEX/VISA", "holderName": "John Doe", "expiryMonth": 6, "expiryYear": 24, "maskedNumber": "**** **** **** 0000", "lastDigits": 444 }, "cash": { "amountTaken": { "code": "GBP", "value": "00.00" } }, "voucher": { // voucher payment details }, "paymentMethodType": "", "amount": { "code": "GBP", "value": "00.00" }, "canBeRemoved": true }, // presentational info "paymentLines": { "name": "Manual Cash Payment", "lines": [ "Cash" ] } } ``` | Field | Type | Description | | --- | --- | --- | | **id?** | `string` | UUID of the order. This is not required for POST requests but is saved against the data model. | | **orderPayment** | `object` | Object containing payment details. | | **orderPayment.card** | `object` | Object containing card payment details. | | **orderPayment.cash** | `object` | Object for cash payment details. | | **orderPayment.voucher** | `object` | Placeholder for voucher payment information. | | **paymentMethodType** | `string` | Indicates payment method type (`MANUAL_CARD`, `MANUAL_CASH`, or `VOUCHER`). | | **amount** | `object` | Object containing currency code and value. | | **canBeRemoved** | `boolean` | Boolean indicating if the payment is eligible for a refund directly without a seperare “refund” transaction. | | **paymentLines** | `object` | Presentational information for the payment. | | **paymentLines.name** | `string` | Display name of the payment type (e.g., "Manual Cash Payment"). Used only in RetailOS app | | **paymentLines.lines** | `array` | List of payment types (e.g., `["Cash"]`). Used only in RetailOS app | ### Example order with payments ```json { "id": "2e3e6549-ed13-456a-b858-358549f7013c", "tax": { "code": "GBP", "value": 0 }, "total": { "code": "GBP", "value": 33000 }, "subTotal": { "code": "GBP", "value": 33000 }, "totalDiscount": { "code": "GBP", "value": 0 }, "status": "complete", "orderNumber": "9088-856357-8168", "updateSource": "RetailOS", "externalOrderId": null, "salesChannel": "Store", "orderDate": "2024-12-05T09:18:18.246Z", "products": [ { "id": "fded25ee-26e6-4bbd-bbca-3745c946c7fd", "tax": { "code": "GBP", "value": 0 }, "link": null, "name": "015099", "brand": "Your Brand", "price": { "code": "GBP", "value": 33000 }, "total": { "code": "GBP", "value": 33000 }, "images": [ "" ], "itemId": "7784a50d-7bfd-492f-a01e-b073e7735536_d0c27e48-6c06-483e-9991-fcf8e338211a", "unsold": false, "details": { "rrpPrice": { "code": "GBP", "value": "33000.00" }, "isSerialized": false, "isMadeToOrder": false, "decrementStock": true }, "isLoved": false, "preview": false, "service": false, "variant": { "id": "d0c27e48-6c06-483e-9991-fcf8e338211a", "name": "medium", . "ean": "1234567899999", "externalVariantId": "1234567" "price": { "code": "GBP", "value": 45 }, "discount": { "code": "GBP", "value": 0 }, }, "category": { "id": "4928dce7-c11a-4748-beac-53b843186d35", "name": "Your Category Name", "image": null, "order": 0, "parentId": null, "createdAt": "2024-07-15T08:12:31.230Z", "deletedAt": null, "updatedAt": "2024-07-15T08:12:31.230Z", "updateSource": null, "externalCategoryId": "your_category_name" }, "clientId": null, "discount": { "code": "GBP", "value": 0 }, "imageUrl": "", "quantity": 1, "regionId": "cebdbd03-e323-4ac4-a4ce-35ec330590b0", "subTotal": { "code": "GBP", "value": 33000 }, "catalogue": "Your Catalogue", "createdAt": "2024-09-26T21:54:14.044Z", "deletedAt": null, "productId": "7784a50d-7bfd-492f-a01e-b073e7735536", "reporting": {}, "updatedAt": "2024-12-05T09:07:30.476Z", "categoryId": "4928dce7-c11a-4748-beac-53b843186d35", "vatPercent": 15, "isAutoAddon": false, "productGroup": null, "updateSource": "Your-System", "secondaryName": null, "storeroomOnly": false, "embeddedVideos": null, "manualDiscount": { "code": "GBP", "value": 0 }, "stockAllocated": true, "promotionalText": null, "stockAdjustable": true, "videoThumbnails": null, "priceAdjustments": [], "externalProductId": "527" } ], "orderType": "standard", "paymentToken": null, "deliveryType": "store", "deliveryOption": { "id": "cf3fdf37-4baa-426e-a5d9-6999f738a875", "name": "Standard", "price": { "code": "GBP", "value": 0 }, "active": true, "details": null, "regionId": null, "createdAt": "2024-07-11T09:51:14.691Z", "deletedAt": null, "updatedAt": "2024-07-11T09:51:14.692Z", "deliveryType": "store" }, "deliveryAddress": null, "deliveryDetails": null, "details": {}, "returningCustomer": true, "previousOrderId": null, "orderPriceAdjustments": [], "orderPayments": [ { "id": "c13fb61d-227e-4098-b766-3837b7165707", "createdAt": "2024-12-05T09:18:28.169Z", "orderPayment": { "card": { "type": "MasterCard" }, "amount": { "code": "GBP", "value": 1100 }, "canBeRemoved": true, "paymentMethodType": "MANUAL_CARD" }, "paymentLines": { "name": "Manual Card Payment", "lines": [ "Card - MasterCard" ] } }, { "id": "7da31cb5-993a-4c37-80d3-3c63321a7873", "createdAt": "2024-12-05T09:18:38.562Z", "orderPayment": { "amount": { "code": "GBP", "value": 4200 }, "canBeRemoved": true, "digitalWallet": { "type": "WeChat Pay" }, "paymentMethodType": "DIGITAL_WALLET" }, "paymentLines": { "name": "Digital Wallet Payment", "lines": [ "WeChat Pay" ] } }, { "id": "fd628230-6190-45f8-b71d-f21c509504ef", "createdAt": "2024-12-05T09:18:48.517Z", "orderPayment": { "amount": { "code": "GBP", "value": 5000 }, "canBeRemoved": true, "paymentMethodType": "DIRECT_BANK_DEPOSIT" }, "paymentLines": { "name": "Direct Bank Deposit Payment", "lines": [ "Direct Bank Deposit" ] } }, { "id": "fb7b21d9-d84a-428d-95b6-39d5e89b7a76", "createdAt": "2024-12-05T09:18:55.358Z", "orderPayment": { "amount": { "code": "GBP", "value": 22700 }, "canBeRemoved": true, "paymentMethodType": "GIFT_CARD" }, "paymentLines": { "name": "Gift Card Payment", "lines": [ "Gift Card" ] } } ], "createdAt": "2024-12-05T09:18:14.382Z", "updatedAt": "2024-12-05T09:18:58.289Z", "deletedAt": null, "customerId": "", "storeId": "", "userId": "", "createdByUserId": "" } ```