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

Order_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 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 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 orderStatusand 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
Unicommerce Website

Copyright © 2024 Unicommerce eSolutions Pvt. Ltd.