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:

    1. PENDING_VERIFICATION: order awaited to be accepted manually by seller for processing, remains on the marketplace till acceptance.
    2. CREATED: when order is created on the marketplace.
    3. COMPLETE: order is dispatched from the warehouse.
    4. CANCELLED: order is cancelled on the marketplace.
  • For orderItems.status:

    1. CREATED: item added to an order on the marketplace.
    2. CANCELLED: item cancelled on the marketplace.
    3. DISPATCHED: item dispatched from warehouse.
    4. DELIVERED: item delivered to the customer.
    5. RETURN_REQUESTED: customer initiated return on marketplace.
    6. COURIER_RETURN: return to origin (warehouse), due to non-delivery to customer.

Flow

Order_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 (Content-Type): application/json
Header (apiKey): accessToken (got from Get Authentication)

Sample URL

https://{marketplace}.com/orders?pageSize=50&pageNumber=1&orderStatus=CREATED&orderDateFrom=2021-09-22T16:13:44+05:30&orderDateTo=2021-12-21T16: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
orderIds string Order ID’s - -
orderItemIds string Item ID’s - -
orderDateFrom date Order date from Yes Format: yyyy-MM-dd’T’HH:mm:ss+05:30
Eg: 2022-08-02T08:12:53+05:30 (for Indian time zone)
orderDateTo date Order date to (Current API call time) Yes Format: yyyy-MM-dd’T’HH:mm:ss+05:30
Eg: 2022-08-22T08:12:53+05:30 (for Indian time zone)
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": "2017-01-02T08:12:53",
      "orderStatus": "CREATED",
      "sla": "2017-01-02T08: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 on Unicommerce. If the Marketplace passes a blank value, the Order ID will be used in Display Order Number. 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
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: 2017-01-04T08:12:53
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
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 Total (cumulative) COD items charges of all unique items Yes -
1.9.12.2 sellingPrice number Selling price of single item Yes -
1.9.12.3 shippingCharges number Total (cumulative) shipping charges of all unique items Yes
1.9.12.4 discount number Total (cumulative) Discount amount of all unique items Yes -
1.9.12.5 totalPrice number Total 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 email 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 email 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 -

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.

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 Query Params and what should be the response if these values are passed?
Ans. No data will be passed in those fields while fetching the orders. But 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. 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.

Q14. 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.

Q15. 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.

Q16. 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. Also, order item level charges (except sellingPrice and totalPrice) are cumulative or sum for all unique items.

Unicommerce Website

Copyright © 2022 Unicommerce eSolutions Pvt. Ltd.