Get Orders
This REST API is used by Unicommerce to fetch new orders from the marketplace. This is mainstream api for Order Management System (OMS), where marketplace orders with created state and within some defined timeframe (generally 15 days) are fetched and created in Uniware for processing.
Tip
- It is recommended to check out Notes for the reader. You might find this helpful as it contains Guidelines for using API references and Terminologies used here.
- The pagination works on order level, which means in each API request we will fetch 50 orders (not order Items). If there are less than 50 orders then the order fetch will stop, otherwise, second API request with pageNumber as 2 will be sent to fetch the next 50 orders from the marketplace.
Status Definition
Following are the orderStatus
and orderItem.status
definitions supported by Uniware:
-
For
orderStatus
:- PENDING_VERIFICATION: order awaited to be accepted manually by seller for processing, remains on the marketplace till acceptance.
- CREATED: when order is created on the marketplace.
- COMPLETE: order is dispatched from the warehouse.
- CANCELLED: order is cancelled on the marketplace.
-
For
orderItems.status
:- CREATED: item added to an order on the marketplace.
- CANCELLED: item cancelled on the marketplace.
- DISPATCHED: item dispatched from warehouse.
- DELIVERED: item delivered to the customer.
- RETURN_REQUESTED: customer initiated return on marketplace.
- COURIER_RETURN: return to origin (warehouse), due to non-delivery to customer.
Flow
Tip
Complete integration flow is available on Basic Overview page.
Basic Information
NAME | DETAILS |
---|---|
Usage: | Mandatory |
Initiation: | Automatically |
Frequency: | 10 mins |
Endpoint: | /orders |
Request Type: | GET |
Scheme: | HTTPS |
Header (apiKey): | accessToken (got from Get Authentication) |
Sample URL
https://{MarketplaceBaseUrl}/orders?pageSize=50&pageNumber=1&orderDateFrom=2023-02-02T16:13:44+05:30&orderDateTo=2023-02-17T16:13:44+05:30&orderStatus=CREATED
Query Parameters
PARAMETERS | TYPE | DESCRIPTION | MANDATORY | NOTES |
---|---|---|---|---|
pageNumber | string | Page number | Yes | Default: 1 |
pageSize | string | Page size | Yes | Fixed: 50 |
orderDateFrom | date | Order date (15 days) back to orderDateTo | Yes | Format: yyyy-MM-dd’T’HH:mm:ss+05:30 Eg: 2023-02-02T08:12:53+05:30 (in IST) |
orderDateTo | date | Order date to (Current API call time) | Yes | Format: yyyy-MM-dd’T’HH:mm:ss+05:30 Eg: 2023-02-17T08:12:53+05:30 (in IST) |
orderStatus | string | Order status | Yes | Fixed: CREATED |
Response Payload
Following is the schema defined for the order resource in Unicommerce system. Which means this includes superset of all the fields and types that define an order for the Unicommerce. The partner is expected to follow this schema for each order information, to complete the transaction successfully.
NOTE:
The charges and price details can be provided either at order level or order item level (charges which are common), but not in both. However, it is recommended to send price at order item level for better handling.
{
"orders": [
{
"id": "string",
"code":"string",
"orderDate": "2023-02-15T08:12:53",
"orderStatus": "CREATED",
"sla": "2023-02-17T08:12:53",
"priority": 0,
"paymentType": "PREPAID",
"orderPrice": {
"currency": "INR",
"totalCashOnDeliveryCharges": 0,
"totalDiscount": 0,
"totalGiftCharges": 0,
"totalStoreCredit": 0,
"totalPrepaidAmount": 0,
"totalShippingCharges": 0
},
"orderItems": [
{
"orderItemId": "string",
"status": "CREATED",
"productId": "string",
"variantId": "string",
"sku": "string",
"returnReason": "string",
"returnDate": "string",
"returnAWB": "string",
"returnShippingProvider": "string",
"title": "string",
"shippingMethodCode": "STD",
"orderItemPrice": {
"cashOnDeliveryCharges": 0,
"sellingPrice": 0,
"shippingCharges": 0,
"discount": 0,
"totalPrice": 0,
"transferPrice": 0,
"currency": "string"
},
"quantity": 0,
"giftWrap": {
"giftWrapMessage": "string",
"giftWrapCharges": 0
},
"onHold": false,
"packetNumber": 0,
"facilityCode" : "string"
}
],
"taxExempted": false,
"cFormProvided": false,
"thirdPartyShipping": false,
"shippingAddress": {
"addressLine1": "string",
"addressLine2": "string",
"city": "string",
"country": "string",
"email": "string",
"name": "string",
"phone": "string",
"pincode": "string",
"state": "string"
},
"billingAddress": {
"addressLine1": "string",
"addressLine2": "string",
"city": "string",
"country": "string",
"email": "string",
"name": "string",
"phone": "string",
"pincode": "string",
"state": "string"
},
"gstin" : "string",
"additionalInfo": "string"
}
]
}
Response Payload Details
LEVEL | PARAMETER | TYPE | DESCRIPTION | MANDATORY | NOTES |
---|---|---|---|---|---|
1 | orders | list | list of orders | - | - |
1.1 | id | string | Unique identifier for an order | Yes | Eg: 12322 |
1.2 | code | string | This number corresponds to Display Order Number in Unicommerce. If the Marketplace passes a blank value, the Order ID will be used in Display Order Number value. | Opt | If the Marketplace not have code then pass same id value in this field, or not use this param |
1.3 | orderDate | date | Order creation Date times on marketplace | Yes | Format: yyyy-MM-dd’T’HH:mm:ss Eg: 2017-01-02T08:12:53 real time of order creation |
1.4 | orderStatus | string | Status of the order | Yes | Allowable: CREATED or PENDING_VERIFICATION |
1.5 | sla | date | Max. time for which order processing can be delayed, beyond which the system will start giving alerts to take action. | Yes | Format: yyyy-MM-dd’T’HH:mm:ss Eg: 2023-02-17T08:12:53 from real time of order creation |
1.6 | priority | integer | Order fullfillment priority | No | Default: 0, High Value equals High Priority |
1.7 | paymentType | string | Mode of payment | Yes | Allowable: COD, PREPAID. (Case sensitive) |
1.8 | orderPrice | object | Sale Order Pricing Components | - | |
1.8.1 | currency | string | Currency codes (3 digit) | Yes | Default: INR, Currency Codes |
1.8.2 | totalCashonDeliveryCharges | number | Total charges for COD | Opt | Sale order level |
1.8.3 | totalDiscount | number | Total Discount amount | Opt | Sale order level |
1.8.4 | totalGiftCharges | number | Total Gift charges | Opt | Sale order level |
1.8.5 | totalStoreCredit | number | Total Store Credits charges | Opt | Sale order level |
1.8.6 | totalPrepaidAmount | number | Total Amount prepaid while ordering | Opt | Sale order level |
1.8.7 | totalShippingCharges | number | Total Shipping charges | Opt | Sale order level |
1.9 | orderItems | list | List of items in an order | - | - |
1.9.1 | orderItemId | string | The ID of an item present inside the order | Yes | length must be between 0 and 45, This Id must be Unique identifier as UC will use this id in consecutive apis. |
1.9.2 | status | string | Generally same as orderStatus . Only is case of partial order fulfilment the status of item in the order will vary. |
Yes | Allowable: CREATED |
1.9.3 | productId | string | Product ID of the item | Yes | length must be between 0 and 45 |
1.9.4 | variantId | string | Variant ID of the item | Yes | length must be between 0 and 45 |
1.9.5 | sku | string | SKU code of the item on the marketplace | Yes | - |
1.9.6 | returnReason | string | Reason for return | Yes | - |
1.9.7 | returnDate | string | Date of return creation on marketplace | Yes | - |
1.9.8 | returnAWB | string | Return tracking no. | Yes | - |
1.9.9 | returnShippingProvider | string | Return shipping provider | Yes | - |
1.9.10 | title | string | Title of the item Listing | No | - |
1.9.11 | shippingMethodcode | string | The shipping method of the order | No | Allowable: STD (Standard) |
1.9.12 | orderItemPrice | object | Item price details | - | - |
1.9.12.1 | cashOnDeliveryCharges | number | COD items charge of item | Yes | - |
1.9.12.2 | sellingPrice | number | Selling price of single item | Yes | - |
1.9.12.3 | shippingCharges | number | Shipping charge of item | Yes | |
1.9.12.4 | discount | number | Discount amount of item | Yes | - |
1.9.12.5 | totalPrice | number | Total final price of single item | Yes | - |
1.9.12.6 | transferPrice | number | - | Opt | - |
1.9.12.7 | currency | string | Currency codes (3 digit) | Yes | Default: INR, Currency Codes |
1.9.13 | quantity | integer | Qty of the item ordered | Yes | Default: 1 |
1.9.14 | giftWrap | object | Gift wrap details | - | - |
1.9.14.1 | giftWrapMessage | string | Message on the gift wrap | No | - |
1.9.14.2 | giftWrapCharges | number | Extra charges for the wrap | No | - |
1.9.15 | onHold | boolean | true if order not available for processing | No | Default: false |
1.9.16 | packetNumber | integer | Packet number | No | Default: 1 |
1.9.17 | facilityCode | string | This is the code passed by the Marketplace corresponding to their internal Location ID, and we will create orders based on the Location ID Map put in the connectors by the seller for that Marketplace. Else Skip this parameter or pass Null | No | - |
1.10 | taxExempted | boolean | Tax Exemption on item | No | Fixed: false |
1.11 | cFormProvided | boolean | Pre-GST configuration | No | Fixed: false |
1.12 | thirdPartyShipping | boolean | true if the shipping to end customer is taken care by the Marketplace. false for self shipping | Yes | - |
1.13 | shippingAddress | object | Shipping address details | - | - |
1.13.1 | addressLine1 | string | Precise address of the customer | Yes | - |
1.13.2 | addressLine2 | string | Additional address information | No | - |
1.13.3 | city | string | City name | Yes | Eg: Surat |
1.13.4 | country | string | Country name | Yes | - |
1.13.5 | string | Email ID | No | case insensitive | |
1.13.6 | name | string | Name of receiver | Yes | - |
1.13.7 | phone | string | Contact no. | Yes | - |
1.13.8 | pincode | string | Area pincode (min. 6 digits) | Yes | Eg: 395006 |
1.13.9 | state | string | State name | Yes | Eg: Gujrat |
1.14 | billingAddress | object | Billing address details | - | - |
1.14.1 | addressLine1 | string | Precise address of the customer | Yes | - |
1.14.2 | addressLine2 | string | Additional address information | No | - |
1.14.3 | city | string | City name | Yes | Eg: Surat |
1.14.4 | country | string | Country name | Yes | - |
1.14.5 | string | Email ID | No | case insensitive | |
1.14.6 | name | string | Name of receiver | Yes | - |
1.14.7 | phone | string | Contact no. | Yes | - |
1.14.8 | pincode | string | Area pincode (min. 6 digits) | Yes | Eg: 395006 |
1.14.9 | state | string | State name | Yes | Eg: Gujrat |
1.15 | gstin | string | gstin no. | No | - |
1.16 | additionalInfo | string | Any additional information | No | Only internal purpose |
Error Codes
Refer Response Codes section to know about specific errors codes.
FAQs/Notes
Q1. What is frequency in this Get Order API?
Ans. It is 10 minutes (Fixed) to pull the orders in UC through Get Order API.
Q2. Since the pagination works on order level, if the orders are more than 50 then would the API be called automatically?
Ans. Yes, the next request will be generated automatically.
Q3. When the order is in pending verification status, would its inventory get blocked?
Ans. No, as the order is not confirmed from the seller in UC but at the MP, it goes on hold.
Q4. Is it possible that some orders are fulfilled from MP and others are fulfilled from self shipping? Can UC do this by API calls and tell MP about the same?
Ans. Yes it is possible from the Third Party Shipping column in the Get Orders API. For example : For MP shipping, the third party shipping field is set to “true” and for all other cases it is set to “false”.
Q5. From Dispatch to Deliver, from where and how will the details get updated in real time from the courier side?
Ans. From Shipment Status API in shipper integration. Also, it depends on the model since the same can be done by Get Orders Status API also if the MP is using its own shipping service.
Q6. Can we skip integrating GET Orders API as we’re going with Post Orders API?
Ans. Yes, either of them can be used depending on the MP requirements. but it is recommended to use Get order API
for better Handling in UC and to avoid seller issues.
Q7. In its end-point and URL, the orderStatus is set as CREATED but in response we get orderStatus as “CANCELLED”. How is this possible?
Ans. This is possible since by default we take orders that are with orderStatus as “Created”. But in response it can reflect all the statuses as mentioned in the document according to the correct order status. Rest all orders with different order status would not synced in UC.
Q8. Why does the GET Orders and GET Order Status API have the same endpoint ?
Ans. Even if the endpoint is the same, since query params are different, APIs will fetch different details. Distinguishing won’t be an issue.
Q9. What is SLA?
Ans. SLA is Service Level Agreement referring to the time period that a particular order takes after it’s received by the MP till it is delivered. Format: yyyy-MM-dd’T’HH:mm:ss Eg: 2023-02-17T08:12:53 from real time of order creation.
Q10. Does the MP need to send orders of all merchants enabled for UC, or this API call would be merchant specific? If getOrder would be for each merchant, how would the merchant details be passed to the MP?
Ans. This is a merchant specific API call. It is the basic premise of the integration itself. The MP will be authenticating a particular seller using the GET/Auth API (Get Authentication) and then sending us an access token in the Response Payload of the same. The same token would be used in the other API calls such as GET/Orders API mentioned here. For reference see the “Basic Information” table of Get Orders document.
Q11. What data will be passed in OrderID
& OrderItemID
in the response?
Ans. OrderID
& OrderItemID
These Id must be unique as UC will use these ids in consecutive apis. The API design should be kept in consideration with the possibility of these filters as it might be helpful during debugging of any issues as such.
Q12. There are two types of status fields in the response for this API, for order item and order item id, what is the difference between them?
Ans. There are two types of status mappings in UC, one for order as a whole and one for the order item id for the separate products in the order. For more details refer to the Status Definition header on Get Orders document.
Q13. Who will define the routing logic and if marketplace defines logic at their end what will happen in that case?
Ans. For order routing, MP will have to define the routing logic at thier end which can be based on any parameters (depends upon business) and the same has to be mapped with facilityCode
in this API. Then order will be allocated according to the Uniware facility. Generally that is dfined on seller warehosue pincode that MP stored at their end and controlled by Get order API call.
Q14. If facilityCode
is not passed by any Marketplace, what will happen in that case?
Ans. The facility will be allocated according to the Uniware facility allocation rules. Generally seller selection must be based on username and password respective token used in api call.
Q15. What will happen in the cases where such a facilityCode
is passed by channel which is not available in the Location ID Mapping in the connectors?
Ans. In such cases, orders will not be created into the system, provided there is a mapping set by the seller already.
Q16. Will it affect any old integration?
Ans. This will not affect any of our existing integrations in any way, as previously their orders were processed using facility allocation rules and now also it’ll still work the same way. But in future if the marketplace wants to use this facilityCode
based handling, we’ll have to update the merchant in our database.
Q17. There are two types of chnarge as order level and order item level, what is the difference between them??
Ans. The charges and price details can be provided either at order level or order item level (charges which are common), but not in both. However, it is recommended to send price at order item level for better handling.