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 CIR
  • COURIER_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 Reason
  • returnDate: Return Date
  • returnAWB: Return Tracking Number
  • returnShippingProvider: Return Shipping Provider

Other orderStatus and orderItem.status status definitions can be referred in Get Orders API.

The marketplaces are expected to abide by these definitions for clearer order status communications.

Flow

Order_Flow

Tip

Complete integration flow is available on Basic Overview page.

Sample URL

https://{marketplace}.com/orders?pageNumber=1&pageSize=5&orderIds=abc

Basic Information

NAME DETAILS
Usage: Mandatory
Frequency: 10 mins for orders in pending state (to get cancellation or dispatch status),
3 days for orders in dispatch state (to get delivered and return status)
Endpoint: /orders
Request Type: GET
Scheme: HTTPS
Header (Content-Type): application/json
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": "2017-01-02T08:12:53",
      "orderStatus": "CREATED",
      "sla": "2017-01-02T08: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",
          "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 on marketplace Yes Format : yyyy-MM-dd’T’HH:mm:ss
Eg: 2017-01-02T08:12:53
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: 2017-01-02T08:12:53
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 title string Title of the item No Pass the same as used in Get Product APi
1.8.11 shippingMethodcode string The shipping method of the order No Allowable: STD (Standard), EXP (Express), PKP (Pickup), CHQ (Standard Cheque)
1.8.12 orderItemPrice object Item price details - -
1.8.12.1 cashOnDeliveryCharges number Total COD itemscharges of all unique items Opt -
1.8.12.2 sellingPrice number Selling price of single item Yes -
1.8.12.3 shippingCharges number Total shipping charges of all unique items Opt -
1.8.12.4 discount number Total Discount amount of all unique items Opt -
1.8.12.5 totalPrice number Total price of single item Opt -
1.8.12.6 transferPrice number - Opt -
1.8.12.7 currency string Currency codes (3 digit) Yes Default: INR, Currency Codes
1.8.13 quantity integer Qty of the item ordered Yes Default: 1
1.8.14 giftWrap object Gift wrap details - -
1.8.14.1 giftWrapMessage string Message on the gift wrap No -
1.8.14.2 giftWrapCharges number Extra charges for the wrap No -
1.8.15 onHold boolean true- if order not available for processing No Default: false
1.8.16 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 email 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 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 additionalInfo string Any additional information No -

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 10 minutes for the orders in pending state(order sync) and once in 3 days it is done for orders in dispatch state.

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 would automatically get synced via Get Order Status API. For proper handling use the following Order orderStatus- OrderItemStatus status

UC Order Status UC Order Item Status DESCRIPTION
PENDING_VERIFICATION CREATED -
CREATED CREATED Pass these status to get fresh orders in UC
CREATED CANCELLED For 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
Unicommerce Website

Copyright © 2022 Unicommerce eSolutions Pvt. Ltd.