Get Order Status
This REST API is used to get the active status of orders in Uniware from marketplace. It is important to fetch the most recent status of the orders on marketplace to be aware of the dispatch status, any cancellations or returns.
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.
- This method is similar to Get Orders API, just that here the marketplace is queried for orderIds existing in Uniware to get their recent status.
Return Order Status Handling
Many a times an order is fulfilled by the marketplaces to the customer. In such scenario when the order comes back to the seller, they are ambiguous about the reason of return i.e. is it a customer initiated return (CIR) or due to non-delivery, categorized as return-to-origin (RTO).
To handle these concerns, following orderItems.status
were introduced to explicitly differentiate between CIR and RTO.
RETURN_REQUESTED
: signifies CIRCOURIER_RETURN
: signifies RTO
Also following fields were added in the orderItem
array to details the reason of return, date of return when initiated by the customer and track the return shipment details like return AWB number and return Shipping provider.
returnReason
: Return ReasonreturnDate
: Return DatereturnAWB
: Return Tracking NumberreturnShippingProvider
: Return Shipping Provider
Other orderStatus
and orderItem.status
status definitions can be referred in Get Orders API. For more for statuses details check faq Q5 at the end of the page.
The marketplaces are expected to abide by these definitions for clearer order status communications.
Flow
Tip
Complete integration flow is available on Basic Overview page.
Sample URL
https://{MarketplaceBaseUrl}/orders?pageNumber=1&pageSize=5&orderIds=abc
Basic Information
NAME | DETAILS |
---|---|
Usage: | Mandatory |
Frequency: | 40 mins for orders in pending state (to get cancellation or dispatch status), Once in a day** for orders in dispatch state (to get delivered and return status) **check Q1 in FaQ section listed down in same page. |
Endpoint: | /orders |
Request Type: | GET |
Scheme: | HTTPS |
Header (apiKey): | accessToken (got from Get Authentication) |
Query Parameters
PARAMETERS | TYPE | DESCRIPTION | MANDATORY | NOTES |
---|---|---|---|---|
pageNumber | string | Page number | Yes | Default: 1 |
pageSize | string | Page size | Yes | Fixed: 5 |
orderIds | string | Order ID’s (comma separated) | Yes | - |
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.
{
"orders": [
{
"id": "string",
"orderDate": "2023-02-15T08:12:53",
"orderStatus": "CREATED",
"sla": "2023-02-01T08:12:53",
"priority": 0,
"paymentType": "string",
"orderPrice": {
"currency": "string",
"totalCashOnDeliveryCharges": 0,
"totalDiscount": 0,
"totalGiftCharges": 0,
"totalPrepaidAmount": 0,
"totalShippingCharges": 0
},
"orderItems": [
{
"orderItemId": "string",
"status": "CANCELLED",
"productId": "string",
"variantId": "string",
"sku": "string",
"returnReason": "string",
"returnDate": "string",
"returnAWB": "string",
"returnShippingProvider": "string",
"returnId": "string",
"courierStatus": "string",
"returnDeliveryDate": "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
}
],
"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"
},
"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 | 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.3 | orderStatus | string | Status of the order | Yes | Allowable: PENDING_VERIFICATION, CREATED, COMPLETE, CANCELLED |
1.4 | 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.5 | priority | integer | Order fullfillment priority | No | Default: 0, High Value equals High Priority |
1.6 | paymentType | string | Mode of payment | Yes | Allowable: COD, PREPAID. (Case sensitive) |
1.7 | orderPrice | object | Sale Order Pricing Components | - | - |
1.7.1 | currency | string | Currency codes (3 digit) | Yes | Default: INR, Currency Codes |
1.7.2 | totalCashonDeliveryCharges | number | Total Charges for COD | Opt | Sale order level |
1.7.3 | totalDiscount | number | Total Discount amount | Opt | Sale order level |
1.7.4 | totalGiftCharges | number | Total Gift charges | Opt | Sale order level |
1.7.5 | totalPrepaidAmount | number | Total Amount paid while ordering | Opt | Sale order level |
1.7.6 | totalShippingCharges | number | Total Shipping charges | Opt | Sale order level |
1.8 | orderItems | list | List of items in an order | - | - |
1.8.1 | orderItemId | string | The ID of an item present inside the order | Yes | - |
1.8.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: CANCELLED, CREATED, DISPATCHED, DELIVERED, RETURN_REQUESTED, COURIER_RETURN |
1.8.3 | productId | string | Product ID of the item | Yes | Pass the same as used in Get Product API |
1.8.4 | variantId | string | Variant ID of the item | Yes | Pass the same as used in Get Product API |
1.8.5 | sku | string | SKU code of the item on the marketplace | Yes | Pass the same as used in Get Product API |
1.8.6 | returnReason | string | Reason for return | Yes | - |
1.8.7 | returnDate | string | Date of return creation on marketplace | Yes | - |
1.8.8 | returnAWB | string | Return tracking no. | Yes | - |
1.8.9 | returnShippingProvider | string | Return shipping provider | Yes | - |
1.8.10 | returnId | string | Return ID | No | - |
1.8.18 | courierStatus | string | Courier tracking status | No | - |
1.8.19 | returnDeliveryDate | string | Date of physical return at seller warehouse by marketplace | No | - |
1.8.11 | title | string | Title of the item | No | Pass the same as used in Get Product APi |
1.8.12 | shippingMethodcode | string | The shipping method of the order | No | Allowable: STD (Standard), EXP (Express), PKP (Pickup), CHQ (Standard Cheque) |
1.8.13 | orderItemPrice | object | Item price details | - | - |
1.8.13.1 | cashOnDeliveryCharges | number | Total COD itemscharges of all unique items | Opt | - |
1.8.13.2 | sellingPrice | number | Selling price of single item | Yes | - |
1.8.13.3 | shippingCharges | number | Total shipping charges of all unique items | Opt | - |
1.8.13.4 | discount | number | Total Discount amount of all unique items | Opt | - |
1.8.13.5 | totalPrice | number | Total price of single item | Opt | - |
1.8.13.6 | transferPrice | number | - | Opt | - |
1.8.13.7 | currency | string | Currency codes (3 digit) | Yes | Default: INR, Currency Codes |
1.8.14 | quantity | integer | Qty of the item ordered | Yes | Default: 1 |
1.8.15 | giftWrap | object | Gift wrap details | - | - |
1.8.15.1 | giftWrapMessage | string | Message on the gift wrap | No | - |
1.8.15.2 | giftWrapCharges | number | Extra charges for the wrap | No | - |
1.8.16 | onHold | boolean | true- if order not available for processing | No | Default: false |
1.8.17 | packetNumber | integer | Packet number | No | Default: 1 |
1.9 | taxExempted | boolean | Tax Exemption on item | No | Fixed: false |
1.10 | cFormProvided | boolean | Pre-GST configuration | No | Fixed: false |
1.11 | thirdPartyShipping | boolean | true- if the shipping to end customer is taken care by the Marketplace. false- for self shipping | Yes | - |
1.12 | shippingAddress | object | Shipping address details | - | - |
1.12.1 | addressLine1 | string | Precise address of the facility | Yes | - |
1.12.2 | addressLine2 | string | Additional address information | No | - |
1.12.3 | city | string | City name | Yes | Eg: Surat |
1.12.4 | country | string | Country name | Yes | - |
1.12.5 | string | Email ID | No | case insensitive | |
1.12.6 | name | string | Name of receiver | Yes | - |
1.12.7 | phone | string | Contact no. | Yes | - |
1.12.8 | pincode | string | Area pincode (min. 6 digits) | Yes | Eg: 395006 |
1.12.9 | state | string | State name | Yes | Eg: Gujrat |
1.13 | billingAddress | object | Billing address details | - | - |
1.13.1 | addressLine1 | string | Precise address of the facility | 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 | 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 are frequencies in some rest APIs like Get Order Status?
Ans. It is 40 minutes for the orders in pending state(order sync) and once in a day for orders post dispatch state for return and delivered status update in UC.
**For more details connect with integration team.
Q2. What would be the status of order on UC when order is in pending status on MP?
Ans. It depends upon the MP as to which status is mapped but generally the UC status for given condition would be reflected as PROCESSING.
Q3. Can those orders be cancelled whose status is “Pending” on MP?
Ans. It depends on the MP about what does Pending status mean. Generally in UC, orders in Processing state can be cancelled but once they are dispatched they can’t be cancelled.
Q4. In the case of MP shipping, how can the MP pass the status to the seller dashboard?
Ans. Post shipping, the latest status of the order would automatically get synced via Get Order Status API.
Q5. What are the status mapping for order and order item statuses to pass in this APIs?
Ans. The latest status of the order/order items would automatically get synced via Get Order Status API. For proper handling pass the following status at Order orderStatus
and OrderItemStatus status
Order Status(orderStatus ) |
Order Item Status(status ) |
DESCRIPTION |
---|---|---|
PENDING_VERIFICATION | CREATED | - |
CREATED | CREATED | To get fresh orders in UC |
CREATED | CANCELLED | For Partial item wise cancellation |
CANCELLED | CANCELLED | For whole order cancellation |
COMPLETE | DISPATCHED | - |
COMPLETE | DELIVERED | - |
COMPLETE | RETURN_REQUESTED | To handle CIR case |
COMPLETE | COURIER_RETURN | To handle RTO case |
COMPLETE | CANCELLED,DISPATCHED,DELIVERED | To handle Partial item wise case |
CREATED | CREATED,CANCELLED,DISPATCHED,RETURN_REQUESTED | To handle Partial item wise case |
CREATED | CREATED,,DISPATCHED,RETURN_REQUESTED | To handle Partial item wise case |
CREATED | CREATED,DISPATCHED,COURIER_RETURN | To handle Partial item wise case |
CREATED | CREATED,DISPATCHED,DELIVERED,RETURN_REQUESTED | To handle Partial item wise case |