DROP SHIP ORDER FULFILMENT API

SPECIFICATION
(Version 3.0)

1
Sl.No Document Version Date Comments Reviewer
updated by
1 Maneesh Sharma Baseline (V0.1) 10.02.2021 Created initial Sumith Vijayan
document
2 V0.12 1. Added return
type filter in get
return API
2. Added return
order Id in RSI
response
3 V0.13 1. Updated QC
API(create RTO and
perform QC) to
support quantity
wise QC
2. Added base price
info in PO details
4 V0.14 1. Added forward
order details in RSI
response
5 V0.15 Added QC code and
reason matrix in
perform QC API
6 V0.16 Added enum in
response code
7 V1.1 Change date time
format to Epoc time
in API response
8 V1.2 Added throttling
limit against each
user
9 V1.3 Added b2b price in
pendency orders
10 V1.4 Added order item id
in Create RTO API
request
11 V2.0 Added delivery
challan feature
12 Vipul Gupta, Tarini V3.0 21.12.2022 Guidebook with Maneesh Sharma
Tripathy, Rajen samples
Raiyerla

2
Table of Contents
OVERVIEW ........................................................................................................................................................................... 4
GETTING STARTED................................................................................................................................................................ 4
URI SCHEME ....................................................................................................................................................................................... 4
API CALLS............................................................................................................................................................................. 5
AUTHENTICATION ................................................................................................................................................................................. 5
GET PRODUCT COUNT ........................................................................................................................................................................... 6
GET PRODUCT ...................................................................................................................................................................................... 7
UPDATE ATP INVENTORY ....................................................................................................................................................................... 8
GET NODE STATUS ................................................................................................................................................................................ 9
ENABLE/DISABLE NODE ....................................................................................................................................................................... 10
FORWARD ...................................................................................................................................................................................... 11
GET PENDENCY ORDERS....................................................................................................................................................................... 12
ACKNOWLEDGE ORDER ........................................................................................................................................................................ 14
GET ORDERS ...................................................................................................................................................................................... 17
GENERATE B2B INVOICE ...................................................................................................................................................................... 21
UPDATE B2B INVOICE ......................................................................................................................................................................... 24
UPLOAD SIGNED COPY OF B2B INVOICE .................................................................................................................................................. 26
GET B2C INVOICE ............................................................................................................................................................................... 27
CANCELLATION SUMMARY (NOT AN API, GENERAL UNDERSTANDING):......................................................................................................... 28
GENERATE SHIPPING LABEL DATA .......................................................................................................................................................... 30
GENERATE SHIPPING LABEL PDF ........................................................................................................................................................... 32
GENERATE MANIFEST .......................................................................................................................................................................... 33
CREATE RTO ..................................................................................................................................................................................... 35
GET RETURN ORDERS .......................................................................................................................................................................... 36
GET RETURN SALES INVOICE ................................................................................................................................................................ 40
ACCEPT RETURN SALES INVOICE ............................................................................................................................................................ 43
GET DELIVERY CHALLAN ...................................................................................................................................................................... 44
GENERATE CREDIT NOTE ...................................................................................................................................................................... 48
UPDATE CREDIT-NOTE......................................................................................................................................................................... 51
UPLOAD SIGNED COPY OF CREDIT-NOTE.................................................................................................................................................. 53
OTHER API........................................................................................................................................................................................ 54
GET DOCUMENT ................................................................................................................................................................................. 54

3
Overview
This is the AJIO Dropship (B2C- Ajio.com) API Integration Guide. It provides details for the
implementation, parameter formats, Cancelation flow, and order status information. It also provides
descriptions, syntax, and usage examples for each of the actions and data types.

Getting Started
URI Scheme
Base path: to be confirmed
Sandbox IP: http://116.50.64.106:8080
Prod URL: https://api-seller.services.ajio.com

Once Onboarding is completed, generated POB ID and POB password will be shared over email which is to
be used in every authentication call, detailed below.

4
API Calls

Authentication

Generate auth token using username and password. This auth token is needed to pass in header with header
name ‘apiKey’ for all interaction with AJIO Platform.

POST /authToken

Description :
• All API requests will require to pass Auth Token.
• You can use Authentication API to get Auth token by passing your POB ID and POB password
• Token once generated is valid for 30 mins, upon expiry with response code as 401, fresh token to be
generated using same steps.

Behaviour :
• Authenticate and generate JWT based auth and refresh token.
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 40x if authentication is unsuccessful.

Consumes
• application/json

Produces
• application/json

Sample Request

{
"password":"",
"username":""
}

Sample Response
{
"success": true,
"statusCode": 0,
"result": {
"accessToken": "string",
"refreshToken": "string"
}
}

5
Get Product Count
API to get product count.

GET /productsCount
Description :
• Retrieve product count of catalogued products.

Behaviour :
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.

Parameters
Type Name Description Schema
Query publishedStatus Filter Criteria on publish status enum(PUBLISHED/U
NPUBLISHED)

Produces
• application/json

Sample Response:

{
"count": 0
}

6
Get Product
API to get PUBLISHED product details.

GET /products
Description :
• Use this GET Product API with publishedStatus = PUBLISHED to get list of articles cataloged on AJIO end and
published.

Behaviour :
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.

Parameters
Type Name Description Schema
Query publishedStatus Filter Criteria on publish status enum(PUBLISHED/U
NPUBLISHED)
Query skus Filter Criteria on seller skus string

Query pageNumber Page Number integer (int32)

Query pageSize Page Size. (Max size is 50) integer (int32)

Produces
• application/json

Sample Response:

{
"products": [
{
"id": "string",
"brand": "string",
"variants": [
{
"variantId": "string",
"sku": "string",
"size": "string",
"color": "string",
"live": true,
"productDescription": "string"
}
]
}
]
}

7
Update ATP Inventory
API to update ATP (Available To Promise) inventory.

POST /updateInventory

Description :
• API to update inventory at a ‘Product ID’ level
• Inventory against a particular Product ID gets blocked automatically upon seller
cancellations to avoid future booking, which can be restored by Updating Inventory count by
this API

Behaviour :
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.

Consumes
• application/json

Produces
• application/json

Sample Request
{
"inventoryList": [
{
"inventory": "string",
"productId": "string",
"variantId": "string"
}
]
}

Sample Response
{
"status": "enum (SUCCESS, FAILED)",
"failedProductList": [
{
"productId": "string",
"variantId": "string",
"message": "string"
}]
}

8
Get Node status
API to get the node status.

GET /node
Description :
• API will get the status of the POB node.
• To ACTIVATE/ DE-ACTIVATE node refer to Enable/Disable Node API

Behaviour :
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.

Throttling limit: 100 requests per minute per user.

Consumes
• application/json

Produces
• application/json

Sample Response
{
"is_active": true,
"disable_reason": "string"
}

9
Enable/Disable Node
API to enable disable a node.

POST /node

Description :
• API will enable or disable a POB (node).

Behaviour :
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.

Throttling limit: 100 requests per minute per user.

Consumes
• application/json

Produces
• application/json

Sample Request
{
"active": true,
"effective_date": "string",
"reason": "string"
}

Sample Response
{
"status": "enum (SUCCESS, FAILED)",
"message": "string"
}

10
FORWARD

11
Get Pendency Orders
API to fetch newly created Orders(without any Purchase Order). This can also be used for soft inventory
reservation at vendor side. The response contains all the open orders belongs to a POB which are yet to be
acknowledge by seller.

GET /orders/pendency

Description :
• Filter and fetch orders which are in Open status and whose acknowledgment is not yet
received.
• It is advised not to consume Order value from this API.
• This API should only be used to get visibility on booked orders and blocking inventory.
• Date Format to be adhered to avoid failures described at beginning

Behaviour :
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.

Throttling limit: 100 requests per minute per user.

Parameters
Type Name Description Schema
orderDateFro
Query m Filter Criteria for Order date string

orderDateTo
Query Filter Criteria for Order date string

pageNumber
Query Page Number integer (int32)

pageSize
Query Page Size. (Max size is 50) integer (int32)

Produces
• application/json

Sample Response:

{
"orders": [
{
"carrier": "string",
"order_date": 1635828975,
"order_id": "string",

12
 "order_lines": [
{
"item_details": {
"brand_name": "string",
"color": "string",
"ean": "string",
"item_code": "string",
"name": "string",
"size": "string"
},
"order_item_id": "string",
"ordered_quantity": 0,
"mrp": 0,
"unit_price": 0,
"listing_price ": 0,
"seller_discount": 0,
"b2b_base_price": 0,
"b2b_tax": 0
}
],
"payment_method": "string",
"tracking_number": "string",
"total_amount": 0,
}
],
"page": {
"number": 0,
"size": 0,
"totalElements": 0,
"totalPages": 0
}
}

13
Acknowledge Order
API to acknowledge and confirm/cancel the order. Basis this acknowledgement quantity purchase order will
be triggered.
POST /orders

Description :
• Consume acknowledgment from seller and trigger purchase order generation.
• Purchase Order is triggered for confirmed orders & their respective line items and
corresponding quantities
• It is advised to keep Auto Acknowledgement of orders basis response of Get Pendency call
and seller ATP at integrator’s end
• Any customers cancellations prior to this call will flow as "cancelled_quantity" as response is
to be reconciled and handled

Behaviour :
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.

Throttling limit: 100 requests per minute per user.

Consumes
• application/json

Produces
• application/json

Sample Request:

{ "order_id": "string",
"order_lines": [
{
"cancelled_quantity": 0,
"confirmed_quantity": 0,
"order_item_id": "string"
}
],
"status": "enum(Acknowledge, Cancel)"
}

Sample Response:

{
"failed_items": [
{
"error_message": "string",
"order_id": "string"
}

14
 ],
"success": [
{
"order_id": "string",
"order_lines": [
{
"cancelled_quantity": "string",
"confirmed_quantity": "string",
"order_item_id": "string"
}
],
"order_status": "enum(Acknowledge, Cancel)"
}
]
}

15
16
Get Orders
API to fetch Purchase Orders (Orders) which are previously acknowledge by seller and whose purchase
order is generated in the system.

GET /orders

Description :
• Filter and fetch orders whose purchase order is generated.
• Reconcile Order quantity
• Refer "quantity", for quantities to be fulfilled as of now (net off all cancellations)
• PO (Order) value to be considered from this API

Calculating B2B Invoice value:

• MRP – MRP is price at which seller has catalogued specific product (inclusive of GST)
• Item_base_price – It is Product ID level base price after adjustments of Seller discounts and
AJIO Margin at a unit level, exclusive of GST
• Quantity – Is the count of items to be fulfilled for the mentioned Product ID
• tax_summary– It is the breakup of tax values under different heads at consolidated quantity
level for the specific Product ID.
• po_line_amount" – It is the final price of PO inclusive of tax and item prices* qty.
po_line_amount = Item_base_price * Quantity + tax_summary
• total_tax: - It is the tax value of total PO amount.

Example:

a b c d e f g h
Item_base_ quant cgst_am cgst_perce igst_am igst_perce sgst_am sgst_perce
price ity ount ntage ount ntage ount ntage
Line 1 100 2 10 5% - - 10 5%
Line 2 200 1 - - 20 10% - -
po_line_a
mount 440
(a*b+c+e+
g)
total_tax 40
(c+e+g)

Behaviour :
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.

Throttling limit: 100 requests per minute per user.

17
Different Status in Forward Journey:

• Cancelled - When an order is cancelled by a customer.

• Confirmed - When an order is acknowledged.
• Packed - When B2B is uploaded
• Dispatched - When manifest is generated
• Delivered - When order reached destination
• READY_TO_DISPATCH – After B2C is created or Shipping label is created.

Parameters
Type Name Description Schema
orderDateFrom
Query Filter Criteria for Order date string

orderDateTo
Query Filter Criteria for Order date string

orderIds
Query Filter Criteria for order ids string

poNumbers
Query Filter Criteria for purchase order numbers string

enum (CANCELLED,
CONFIRMED,
PACKED,
DISPATCHED,
orderStatus
Query Filter Criteria for Order Status DELIVERED,
READY_TO_DISPATCH
)

pageNumber
Query Page number integer (int32)

pageSize
Query Page Size (Max size is 50) integer (int32)

Produces
• application/json

Sample Response:

{
"orders": [

18
 {
"carrier": "string",
"order_date": 1635828975,
"order_id": "string",
"payment_method": "string",
"po_amount": 0,
"total_tax": 0,
"po_number": "string",
"po_date": 1635828975,
"po_pdf_url": "string",
"status": "enum (CANCELLED, CONFIRMED, PACKED, DISPATCHED, DELIVERED,
READY_TO_DISPATCH)",
"order_lines": [
{
"item_details": {
"brand_name": "string",
"color": "string",
"ean": "string",
"item_code": "string",
"name": "string",
"size": "string"
},
"mrp": 0,
"item_base_price": 0,
"order_item_id": "string",
"quantity": 0,
"customer_cancelled_qty": 0,
"seller_cancelled_qty": 0,
"seller_short_picked_qty": 0,
"hsn": "string",
"tax_summary": {
"cess_amount": 0,
"cess_percentage": 0,
"cgst_amount": 0,
"cgst_percentage": 0,
"igst_amount": 0,
"igst_percentage": 0,
"sgst_amount": 0,
"sgst_percentage": 0,
"tcs_amount": 0,
"tcs_percentage": 0,
"gst_amount": 0
},
"po_line_amount": 0,
"total_tax": 0
}
],
"recipient_address": {
"address_line_1": "string",
"address_line_2": "string",
"address_line_3": "string",

19
 "city": "string",
"country": "string",
"first_name": "string",
"last_name": "string",
"mobile": "string",
"state": "string",
"state_code": 0,
"zipcode": "string",
"gstin": "string"
}
}
],
"page": {
"number": 0,
"size": 0,
"totalElements": 0,
"totalPages": 0
}
}

20
Generate B2B Invoice
API to generate B2B invoice in AJIO.

POST /orders/{order_Id}/invoice/b2b

Description :
• This API is to be used for requesting B2B Invoice generation
• The response gives B2B generated PDF as well as soft data to generate it by self.
• Reconcile Order quantity. Any cancellations post Get Orders API shall reflect with updated
quantity under attribute ‘quantity’.
• Refer "quantity", for quantities to be fulfilled as of now (net off all cancellations)
• Customer cancellations and Seller Cancellations Hard stops beyond this point. (Business
cancellations are allowed)
• Custom Invoice no. as needed can be used under attribute ‘b2b_invoice_number’ in this call
• B2B Invoice Number updation should follow GOI approved format and should be validated using the
regex ^([a-zA-Z1-9]{1}[a-zA-Z0-9\/-]{0,15})$ provided by GOI.
• Seller can either use Ajio generated B2B Invoice as is or can use their own template.
• For AJIO generated documents, pass true for pdf_required in Generate and Update B2B
Invoice calls and use Get Document API to download the document and upload the same in
upload signed copy of B2B Invoice API call (mentioned further)
• For custom template, integrators can pass false for pdf_required and upload the custom
document in upload signed copy of B2B Invoice API call. Note, it is compulsory to call
Generate and Update B2B Invoice.

Calculating B2B Invoice value:

• Item_base_price – It is Product ID level base price after adjustments of Seller discounts and
AJIO Margin at a unit level, exclusive of GST
• Quantity – Is the count of items to be fulfilled for the mentioned Product ID
• Tax Summary – It is the breakup of tax values under different heads at consolidated
quantity level for the specific Product ID.
• total_price – It is the final value of B2B Invoice inclusive of tax and item prices* qty.
Total_Price = Item_base_price * Quantity + Tax summary
• total_tax: - It is the tax value of total B2B Invoice amount.

Behaviour :
21
 • Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.

Throttling limit: 100 requests per minute per user.

Parameters
Type Name Description Schema
Order_id The Order Id for which B2B invoice needs to be
Path string
required generated

Consumes
• application/json

Produces
• application/json

Sample Request

{
"order_id": "string",
"b2b_invoice_number": "string",
"pdf_required": true,
"order_lines": [
{
"order_item_id": "string",
"quantity": 0
}
]
}

Sample Response

{
"invoice_number": "string",
"invoice_date": 1635828975
"invoice_lines": [
{
"item_base_price": 0,
"order_item_id": "string",
"quantity": 0,
"hsn": "string",
"tax_summary": {
"cess_amount": 0,
"cess_percentage": 0,
"cgst_amount": 0,
"cgst_percentage": 0,
"igst_amount": 0,
"igst_percentage": 0,
"sgst_amount": 0,
"sgst_percentage": 0,

22
 "tcs_amount": 0,
"tcs_percentage": 0,
"gst_amount": 0
},
"total_price": 0,
"total_tax": 0
}
],
"order_id": "string",
"b2b_invoice_pdf_url": "string"
}

23
Update B2B Invoice
API to update B2B invoice.

PUT /orders/{order_Id}/invoice/b2b

Description :
• Update B2B invoice, this API needs to be called to update e-invoice data (irn_number,
Signed_invoice, Signed_qr_code etc) and custom Invoice no.
• If the vendor is using Ajio Format, they need to send pdf_required: true in request payload to
download pdf and re-upload same in next call
• B2B Invoice Number updation should follow GOI approved format and should be validated using the
regex ^([a-zA-Z1-9]{1}[a-zA-Z0-9\/-]{0,15})$ provided by GOI.

Behaviour :
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.
Throttling limit: 100 requests per minute per user.

Parameters
Type Name Description Schema
Order_id The Order Id for which B2B invoice needs to be
Path string
required updated

Consumes
• application/json

Produces
• application/json

Sample Request

{
"b2b_invoice_number": "string",
"ack_number": "string",
"ack_date": "string",
"irn_number": "string",
"signed_invoice": "string",
"signed_qr_code": "string",
"pdf_required": true
}

Sample Response

{
"status": "enum (SUCCESS, FAILED)",
"b2b_invoice_pdf_url": "string"
}

24
25
Upload signed copy of B2B Invoice
API to upload signed(manually or digital) copy of B2B invoice. Post this only, settlement will be made.

POST /orders/{order_Id}/invoice/b2b/file

Description :
• Upload signed invoice copy of B2B invoice, without this settlement won’t be initiated.
• Upload B2B completes B2B transaction journey
• This API triggers Invoice posting in Ajio ERP to reflect for billing, settlements and
reconciliation purpose.

Behaviour :
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.
Throttling limit: 100 requests per minute per user.

Parameters
Type Name Description Schema
Order_id The Order Id for which B2B invoice file needs to be
Path string
required uploaded

FormDat file
Signed copy of B2B invoice file
a required

Consumes
• multipart/form-data

Produces
• application/json

Sample Response

{
"result": {
"error_message": "string",
"status": "enum (SUCCESS, FAILED)"
}
}

26
Get B2C Invoice
API to fetch B2C invoice from AJIO

GET /orders/{order_Id}/invoice/b2c
Description :
• To generate and fetch B2C invoice.
• This is only in Ajio format
• At this event, Business cancellations also stops. No format of cancellations is allowed
beyond this point.
• Pdf to be downloaded, printed and attach physically in shipment along with order.

Behaviour :
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.

Throttling limit: 100 requests per minute per user.

Parameters
Type Name Description Schema
Order_id The Order Id for which B2C invoice needs to be
Path string
required fetched

Produces
• application/json

Sample Response
{
"order_id": "string",
"order_lines": [
{
"order_item_id": "string",
"quantity": 0
}
],
"tracking_number": "string",
"b2c_invoice_pdf_url": "string"
}

27
Cancellation Summary (Not an API, general understanding):

Customer Cancellation
Customer cancellation is allowed until B2B invoice is not generated. API integrator needs to
1. Reconcile the quantity received in Acknowledge call and consider fulfilment of the quantity
mentioned against the confirmed_quantity response parameter.
2. Reconcile the quantity received in Generate B2B invoice call and consider fulfilment of the
quantity received in response.
3. If a full order is cancelled then the seller has to stop order processing.

Seller Cancellation
Seller cancellation can be done.as below:
1. During Acknowledgement Call: In this request, seller can specify cancelled_quantity and
confirmed_quantity.
2. During Generate B2B Invoice Call: In this request, seller can specify lesser quantity against quantity
parameter than what mentioned in the confirmed_quantity during Acknowledgement call. Quantity value
should be always less than or equal to the confirmed_quantity mentioned in ACK call.

Business Cancellation
Business cancellation is allowed until B2B invoice is uploaded. API integrator needs to
1. Reconcile quantity received in Generate B2C invoice call and consider fulfilment of the quantity
received in response.
2. If a full order is business cancelled then the seller has to stop order processing.
3. Account reconciliation will be handled offline.

Customer Order 5 Tshirt

Scenario 1 No Cancellation
Pendency API Ordered_Quantity=5
Acknowledge Order API Cancelled_Quantity=0 Confirmed_quantity=5
Get Orders API quantity = 5 customer_cancelled quantity =0
Generate B2B invoice API quantity = 5
Generate B2C invoice API quantity = 5

Scenario 2 Customer Cancels 2 quantity before Acknowledge API is triggered

Pendency API Ordered_Quantity=5
Acknowledge Order API Cancelled_Quantity=2 Confirmed_quantity=3
Get Orders API quantity = 3 customer_cancelled quantity =2
Generate B2B invoice API quantity = 3
Generate B2C invoice API quantity = 3

Scenario 3 Customer Cancels 2 quantity before PO API is triggered but after acknowledge API
Pendency API Ordered_Quantity=5
Acknowledge Order API Cancelled_Quantity=0 Confirmed_quantity=5
Get Orders API quantity = 3 customer_cancelled quantity =2
Generate B2B invoice API quantity = 3
Generate B2C invoice API quantity = 3

Scenario 4 Customer Cancels 2 quantity before generate B2B API is triggered but after PO API

28
Pendency API Ordered_Quantity=5
Acknowledge Order API Cancelled_Quantity=0 Confirmed_quantity=5
Get Orders API quantity = 5 customer_cancelled quantity =0
Generate B2B invoice API quantity = 3
Generate B2C invoice API quantity = 3
Customer Cancels 1 quantity before Acknowledge API, 1 before PO API and 1
Scenario 5 before generate B2B invoice API
Pendency API Ordered_Quantity=5
Acknowledge Order API Cancelled_Quantity=1 Confirmed_quantity=4
Get Orders API quantity = 3 customer_cancelled quantity =2
Generate B2B invoice API quantity = 2
Generate B2C invoice API quantity = 2
No Customer Cancellation but 2 quantities are cancelled by business after B2B
Scenario 6 invoice
Pendency API Ordered_Quantity=5
Acknowledge Order API Cancelled_Quantity=0 Confirmed_quantity=5
Get Orders API quantity = 5 customer_cancelled quantity =0
Generate B2B invoice API quantity = 5
Generate B2C invoice API quantity = 3
Business Cancels 1 quantity before Acknowledge API, 1 before PO API and 1 before
Scenario 7 generate B2B invoice API
Pendency API Ordered_Quantity=5
Acknowledge Order API Cancelled_Quantity=1 Confirmed_quantity=4
Get Orders API quantity = 3 customer_cancelled quantity =2
Generate B2B invoice API quantity = 2

29
Generate Shipping Label Data
API to get JSON data require to generate Ship Label

GET /shipment/label

Description :
• Get necessary data to generate a shipping label.

Behaviour :
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.

Throttling limit: 100 requests per minute per user.

Parameters
Type Name Description Schema
order_id The order id for which Ship Label needs to be
Query string
required generated

Produces
• application/json

Sample Response
{
"awb": "string",
"carrier": "string",
"carrier_service": "string",
"cod_amount": 0,
"consignment_number": "string",
"container_number": "string",
"gstin": "string",
"invoice_date": 1635828975,
"invoice_number": "string",
"invoice_total": 0,
"order_id": "string",
"payment_type": "string",
"recipient_address": {
"address_line_1": "string",
"address_line_2": "string",
"address_line_3": "string",
"city": "string",
"country": "string",
"first_name": "string",
"last_name": "string",
"mobile": "string",
"state": "string",
30
 "state_code": 0,
"zipcode": "string"
},
"routing": {
"destination": "string",
"origin": "string",
"routing_code": "string"
},
"supplier_address": {
"address_line_1": "string",
"address_line_2": "string",
"address_line_3": "string",
"city": "string",
"country": "string",
"first_name": "string",
"last_name": "string",
"mobile": "string",
"state": "string",
"state_code": 0,
"zipcode": "string"
},
"tax": {
"tax_summary_list": [
{
"cess_amount": 0,
"cess_percentage": 0,
"cgst_amount": 0,
"cgst_percentage": 0,
"hsn_code": "string",
"hsn_total_amount": 0,
"igst_amount": 0,
"igst_percentage": 0,
"sgst_amount": 0,
"sgst_percentage": 0
}
],
"total_cess_amount": 0,
"total_cgst_amount": 0,
"total_igst_amount": 0,
"total_sgst_amount": 0
}
}

31
Generate Shipping Label PDF
API to get Shipping Label PDF generated by AJIO

GET /shipment/label/pdf
Description :
• Generate a shipping plan PDF and provide the byte stream of it.

Behaviour :
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.

Throttling limit: 100 requests per minute per user.

Parameters
Type Name Description Schema
order_id The Order id for which Ship Label needs to be
Query string
required generated

Produces
application/octet-stream

32
Generate Manifest
API to create manifest for multiple consignment per carrier.

POST /manifest

Description :
• Generate manifest and mark the order status as shipped.
• Closing Manifest is a Important step for buyer visibility
• Unclosed manifest also results in Buyer return creation/ Request failure.

Behaviour :
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.
Throttling limit: 100 requests per minute per user.

Sample Request

{
"carrier": "string",
"shipments": [
{
"order_id": "string",
"weight": 0
}
]
}

Sample Response
{
"failed_items": [
{
"error_message": "string",
"order_id": "string"
}
],
"manifest_id": "string",
"manifest_url": "string",
"status": "enum (SUCCESS, FAILED, IN_PROGRESS)"
}

33
RETURN

34
Create RTO
API to create RTO (initiated from vendor) for an order

POST /return/rto

Description :
• Generate RTO for undelivered order.
• Sellers can use this API to create RTO if for return delivered order info isn’t available with
them on respective platform.

Behaviour :
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.

Throttling limit: 100 requests per minute per user.

Consumes
• application/json

Produces
• application/json

Sample Request
{
"order_id": "string",
"order_items": [
{
"item_id": "string",
"order_item_id": "string",
"quantity": 0,
"qc_code": "string",
"reason": "string"
}
]
}

Sample Response
{
"error_message": "string",
"return_order_id": "string",
"status": "enum (SUCCESS, FAILED)"
}

35
Get Return Orders
API to fetch Return Orders (both RTO and Customer returns)

GET /return

Description :
• Filter and fetch return orders (both RTO and RVP).
• Return orders are to be fetched in RETURN_INITIATED/RETURN_CREATED state itself

Different Statuses and Inferences:

• RETURN_INITIATED / RETURN_CREATED – When a return order request is received status will

be first in RETURN_INITIATED and automatically in sometime will change to RETURN_CREATED.
• RETURN_DELIVERED – When a return order reaches the seller or when seller creates the RTO.
• RETURN_PROCESSED – When a QC is done or when Credit Note upload API is successful.
• RETURN_CANCELLED – When return request is cancelled by customer.

Behaviour :
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.

Throttling limit: 100 requests per minute per user.

Parameters
Type Name Description Schema
orderIds
Query Filter Criteria for Order Ids string

pageNumber
Query Page Number integer (int32)

pageSize
Query Page Size integer (int32)

returnOrderDat
Query eFrom Filter Criteria for Return Order date string

returnOrderDat
Query eTo Filter Criteria for Return Order date string

returnOrderIds
Query Filter Criteria for Return Order Ids string

36
 returnType
Query Filter Criteria for Return Type. string

enum
(RETURN_INITIATED,
returnOrderStat RETURN_CREATED,
Query Filter Criteria for Return Order Status
us RETURN_DELIVERED,
RETURN_PROCESSED,
RETURN_CANCELLED)

Produces
• application/json

Sample Response

{
"orders": [
{
"return_order_id": "string",
"return_date": 1635828975,
"order_id": "string",
"return_status": "enum (RETURN_INITIATED, RETURN_CREATED, RETURN_DELIVERED,
RETURN_PROCESSED, RETURN_CANCELLED)",
"return_type": "string",
"tracking_number": "string",
"return_order_items": [
{
"item_details": {
"brand_name": "string",
"color": "string",
"ean": "string",
"item_code": "string",
"name": "string",
"size": "string"
},
"return_quantity": 1,
"order_item_id": "string",
"return_item_id": "string",
"cancelled_return_quantity": 0
}
]
}
],
"page": {
"number": 0,
"size": 0,
"totalElements": 0,
"totalPages": 0
}

37
 }

Perform QC for returned Order

API to perform QC for a return order

POST /return/qc
Description :
• Perform QC for return orders for both RTO and RVP.
• For certain category of orders, on successful consumption of QC update from vendor, Ajio
triggers refund to buyer.
• Refund to buyer is trigger point for request of delivery challan
• Delivery challan corresponds to debit entry to seller ledger
• Delivery challan generates in batch of 3 hrs
• CN and subsequent APIs (described further) can only be triggered once delivery challan is
successfully generated
• QC reason is captured at 2 levels L0- Disposition code and L1 – QC reacon code as
detailed in table below.

Behaviour :
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.

Throttling limit: 10 requests per minute per user.

Below table summarized list of Disposition code (L0) and corresponding QC reason code
(L1) expected:

Disposition Code QC Reason Code Description

GOOD Good Same brand, design and size, in good condition
Same brand, design and size, in good condition, but brand
BAD Box Damage
box missing/damaged
Same brand, design and size, in good condition, but tag
BAD Tag missing
missing
Same brand, size, design but is dirty and damaged beyond
UGLY Used Product
repair
Product which is torn/broken/not working incase of
UGLY Damaged Product
electronics
UGLY Expired product Product which are past their expiry date
Component Missing /Partial Same brand, same design, same size with a missing
UGLY
Return component
MISSING Fake product Duplicate or non AJIO product received
MISSING Lost in Transit Shipment declared lost by 3PL
MISSING Not Delivered Item not delivered
MISSING Delivery Dispute Delivery status mismatch
MISSING Empty Return Box received with no product inside/empty box received

38
 Wrong product - Different
MISSING Size/Design/colour/brand mismatch
brand
Wrong product - Same
MISSING Size/Design/colour mismatch but same brand
brand

Description field can be used as UI tool tip for vendors while submitting QC. [OPTIONAL]
Consumes
• application/json

Produces
• application/json

Sample Request
{
"return_order_id": "string",
"return_order_items": [
{
"return_item_id": "string",
"quantity": 0,
"qc_code": "string",
"reason": "string"
}
]
}

Sample Response:
{
"error_message": "string",
"status": "enum (SUCCESS, FAILED)"
}

39
GET Return Sales Invoice
API to fetch return sales invoice from AJIO.
Vendor can either be integrated with Return Sales Invoice flow or Credit Note + Delivery challan flow.

GET /rsi
Description :
• Filter and fetch return sales invoice.

Behaviour :
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.

Throttling limit: 100 requests per minute per user.

Parameters
Type Name Description Schema
returnOrderIds
Query Filter Criteria for Return Order Ids string

pageNumber
Query Page Number integer (int32)

pageSize
Query Page Size integer (int32)

rsiDateFrom
Query Filter Criteria for RSI created date string

rsiDateTo
Query Filter Criteria for RSI created date string

rsiNumbers
Query Filter Criteria for Return sales invoice numbers string

Produces
• application/json

Sample Response:
{
"return_sales_invoices": [
{
"rsi_number": "string",

40
"rsi_date": 1635828975,
"rsi_pdf_url": "string",
"billing_no": "string",
"irn_number": "string",
"signed_qr_code": "string",
"rsi_amount": 0,
"total_tax": 0,
"rsi_lines": [
{
"order_id": "string",
"order_item_id": "string",
"return_order_id": "string",
"return_item_id": "string",
"item_details": {
"brand_name": "string",
"color": "string",
"ean": "string",
"item_code": "string",
"name": "string",
"size": "string"
},
"hsn": "string",
"quantity": 0,
"tax_summary": {
"cess_amount": 0,
"cess_percentage": 0,
"cgst_amount": 0,
"cgst_percentage": 0,
"igst_amount": 0,
"igst_percentage": 0,
"sgst_amount": 0,
"sgst_percentage": 0,
"tcs_amount": 0,
"tcs_percentage": 0,
"gst_amount": 0
},
"rsi_line_amount": 0,
"total_tax": 0
}
],
"supply_address": {
"address_line_1": "string",
"address_line_2": "string",
"address_line_3": "string",
"city": "string",
"country": "string",
"first_name": "string",
"last_name": "string",
"mobile": "string",
"state": "string",
"state_code": 0,

41
 "zipcode": "string",
"gstin": "string",
"site_code": "string",
},
"recipient_address": {
"address_line_1": "string",
"address_line_2": "string",
"address_line_3": "string",
"city": "string",
"country": "string",
"first_name": "string",
"last_name": "string",
"mobile": "string",
"state": "string",
"state_code": 0,
"zipcode": "string",
"gstin": "string"
}
}
],
"page": {
"number": 0,
"size": 0,
"totalElements": 0,
"totalPages": 0
}
}

42
Accept Return Sales Invoice
API to accept return sales invoice.

PUT /rsi/{rsi_number}

Description :
• API to accept return sales invoice.

Behaviour :
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.
Throttling limit: 100 requests per minute per user.

Parameters
Type Name Description Schema
rsi_number The return sales invoice number
Path string
required

Consumes
• application/json

Produces
• application/json

Sample Request

{
"status": "ACCEPTED"
}

Sample Response

{
"status": "enum (SUCCESS, FAILED)"
}

43
GET Delivery Challan
API to fetch deliver challan document from AJIO.

GET /delivery-challan
Description :
• Filter and fetch delivery challan.
• Delivery challan document (.pdf) can only be consumed from Ajio.
• As part of response soft data is also shared at line level for reporting and other use cases
• Refund to buyer is trigger point for request of delivery challan. This can be doorstep refund
at time of pickup or seller QC updation at warehouse depending on Category and Return
type as per policy
• Delivery challan corresponds to debit entry to seller ledger
• Delivery challan generates in batch of 3 hrs
• CN and subsequent APIs (described further) can only be triggered once delivery challan is
successfully generated

Understanding values in response:

• delivery_challan_amount – it is the total Delivery challan value inclusive of tax and all
Return Order line items and corresponding quantities
• total_tax- it is the total Delivery challan tax value inclusive of all taxes at different line item
level and quantities level
• Quantity – Is the count of items for which the Delivery challan is generated against the
mentioned Product ID
• tax_summary– It is the breakup of tax values under different heads at consolidated quantity
level for the specific Product ID
• delivery_challan _line_amount – It is the final return price of Delivery challan at line level
inclusive of tax and item prices* qty
delivery_challan _line_amount = Item price * Quantity + tax_summary
• total_tax: - It is the final tax value of Delivery challan at line level at consolidated quantity

Behaviour :
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.

Throttling limit: 100 requests per minute per user.

Parameters
Type Name Description Schema
returnOrderIds
Query Filter Criteria for Return Order Ids string

44
 pageNumber
Query Page Number integer (int32)

pageSize
Query Page Size integer (int32)

dcDateFrom
Query Filter Criteria for Delivery-Challan created date string

dcDateTo
Query Filter Criteria for Delivery-Challan created date string

dcNumbers
Query Filter Criteria for Delivery-Challan numbers string

Produces
• application/json

Sample Response:
{
"delivery_challan": [
{
"delivery_challan _number": "string",
"delivery_challan _date": 1635828975,
"delivery_challan _pdf_url": "string",
"serial_no": "string",
"delivery_challan _amount": 0,
"total_tax": 0,
"delivery_challan _lines": [
{
"order_id": "string",
"order_item_id": "string",
"return_order_id": "string",
"return_item_id": "string",
"item_details": {
"brand_name": "string",
"color": "string",
"ean": "string",
"item_code": "string",
"name": "string",
"size": "string"
},
"hsn": "string",
"quantity": 0,

45
 "tax_summary": {
"cess_amount": 0,
"cess_percentage": 0,
"cgst_amount": 0,
"cgst_percentage": 0,
"igst_amount": 0,
"igst_percentage": 0,
"sgst_amount": 0,
"sgst_percentage": 0,
"tcs_amount": 0,
"tcs_percentage": 0,
"gst_amount": 0
},
"delivery_challan _line_amount": 0,
"total_tax": 0
}
],
"supply_address": {
"address_line_1": "string",
"address_line_2": "string",
"address_line_3": "string",
"city": "string",
"country": "string",
"first_name": "string",
"last_name": "string",
"mobile": "string",
"state": "string",
"state_code": 0,
"zipcode": "string",
"gstin": "string",
"site_code": "string",
},
"recipient_address": {
"address_line_1": "string",
"address_line_2": "string",
"address_line_3": "string",
"city": "string",
"country": "string",
"first_name": "string",
"last_name": "string",
"mobile": "string",
"state": "string",
"state_code": 0,
"zipcode": "string",
"gstin": "string"
}
}
],
"page": {
"number": 0,
"size": 0,

46
 "totalElements": 0,
"totalPages": 0
}
}

47
Generate Credit Note
API to generate credit note from AJIO.

POST /credit-note/{return_order_id}
Description :
• API to generate the credit note for a return order.
• Credit Note Number updation should follow GOI approved format and should be validated
using the regex ^([a-zA-Z1-9]{1}[a-zA-Z0-9\/-]{0,15})$ provided by GOI.
• Seller can either use Ajio generated Credit note as is or can use their own template.
• For AJIO generated documents, pass true for pdf_required in Generate and Update Credit
Note calls and use Get Document API to download the document and upload the same in
upload signed copy of Credit Note API call (mentioned further)
• For custom template, integrators can pass false for pdf_required and upload the custom
document in upload signed copy of Credit Note API call. Note, it is compulsory to call
Generate and Update Credit Note

Behaviour :
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.

Throttling limit: 100 requests per minute per user.

Understanding values in response:

• credit_note_amount– it is the total Delivery challan value inclusive of tax and all Return
Order line items and corresponding quantities
• total_tax- it is the total Delivery challan tax value inclusive of all taxes at different line item
level and quantities level
• Quantity – Is the count of items for which the Delivery challan is generated against the
mentioned Product ID
• tax_summary– It is the breakup of tax values under different heads at consolidated quantity
level for the specific Product ID
• credit_note_line_amount– It is the final return price of Delivery challan at line level
inclusive of tax and item prices* qty
credit_note_line_amount= Item price * Quantity + tax_summary
• total_tax: - It is the final tax value of Delivery challan at line level at consolidated quantity

Parameters
Type Name Description Schema
return_order_id string
required Return order id for which credit-note needs to be
Query generated

Produces
48
 • application/json

Sample Request

{
"credit_note_number": "string",
"pdf_required": true
}

Sample Response:
{
"credit_note_number": "string",
"credit_note_date": 1635828975,
"delivery_challan_number": "string",
"delivery_challan_date": 1635828975,
"return_order_id": "string",
"credit_note_pdf_url": "string",
"credit_note_amount": 0,
"total_tax": 0,
"credit_note_lines": [
{
"return_item_id": "string",
"item_details": {
"brand_name": "string",
"color": "string",
"ean": "string",
"item_code": "string",
"name": "string",
"size": "string"
},
"hsn": "string",
"quantity": 0,
"tax_summary": {
"cess_amount": 0,
"cess_percentage": 0,
"cgst_amount": 0,
"cgst_percentage": 0,
"igst_amount": 0,
"igst_percentage": 0,
"sgst_amount": 0,
"sgst_percentage": 0,
"tcs_amount": 0,
"tcs_percentage": 0,
"gst_amount": 0
},
"credit_note_line_amount": 0,
"total_tax": 0
}
],
"recipient_address": {
"address_line_1": "string",

49
 "address_line_2": "string",
"address_line_3": "string",
"city": "string",
"country": "string",
"first_name": "string",
"last_name": "string",
"mobile": "string",
"state": "string",
"state_code": 0,
"zipcode": "string",
"gstin": "string"
}
}

50
Update Credit-Note
API to update Credit-Note.

PUT /credit-note/{return_order_id}

Description :
• API to update credit-note.
• Update Credit Note, this API needs to be called to update e-invoice data (irn_number,
Signed_invoice, Signed_qr_code etc) and custom Credit Note no.
• If the vendor is using Ajio Format, they need to send pdf_required: true in request payload to
download pdf and re-upload same in next call
• Credit Note Number updation should follow GOI approved format and should be validated using the
regex ^([a-zA-Z1-9]{1}[a-zA-Z0-9\/-]{0,15})$ provided by GOI.

Behaviour :
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.
Throttling limit: 100 requests per minute per user.

Parameters
Type Name Description Schema
return_order_id The Return Order Id for which Credit-Note needs to
Path string
required be updated

Consumes
• application/json

Produces
• application/json

Sample Request

{
"credit_note_number": "string",
"ack_number": "string",
"ack_date": "string",
"irn_number": "string",
"signed_credit_note": "string",
"signed_qr_code": "string",
"pdf_required": true
}

Sample Response

{
"status": "enum (SUCCESS, FAILED)",

51
 "credit_note_pdf_url": "string"
}

52
Upload signed copy of Credit-Note
API to upload signed(manually or digital) copy of credit-note.

POST /credit-note/{return_order_number}/file

Description :
• Upload signed copy of credit-note.

Behaviour :
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.
Throttling limit: 100 requests per minute per user.

Parameters
Type Name Description Schema
return_orde The return order number for which credit-note file needs
Path r_number string
to be uploaded
required

FormDat file
Signed copy of B2B invoice file
a required

Consumes
• multipart/form-data

Produces
• application/json

Sample Response

{
"result": {
"error_message": "string",
"status": "enum (SUCCESS, FAILED)"
}
}

53
Other API
Get Document
API to fetch document from AJIO

GET /v1/document/{documentId}
Description :
• Download document from AJIO using document Id. Document includes customer invoice,
purchase order, manifest, seller invoice etc.
• This is Idempotent API and thus can be called anytime post successful generation.

Behaviour :
• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 request in invalid.
• Returns HTTP/1.1 status code 401 if token is invalid/expired.

Throttling limit: 100 requests per minute per user.

Parameters
Type Name Description Schema
documentId The Id of the document which needs to be
Path string
required fetched

Produces
• application/octet-stream

54