Overview
This document has details of all the API integrated with MAGENTO 2.4 and above.
API Documentation
Understanding of APIs
Given the nature of software development, reasonable minor modifications are expected in future. Here are the clarifications on processes and APIs.
Proxy Flow | Channel API's | Channel API endpoints |
Get List of Orders | Lists orders that match specified search criteria.(based on filters for status and created_at time) | /rest/default/V1/orders |
Get an Order | Get order details for an order id | /rest/default/V1/orders/{orderId} |
Get Order status | Get status of a specific order | /rest/default/V1/orders/{id}/statuses |
Get Canceled orders List | Lists orders that match specified search criteria.(based on filters for status and updated_at time | /rest/default/V1/orders |
Order Acknowledgment | Change order status to processing as an acknowledgement of order received | rest/default/V1/orders/orders/{orderId}/comments |
Cancel order | Cancels a specified order. | /rest/default/V1/orders/{orderId}/cancel |
Create Shipment | Performs persist operations for a specified shipment. | /rest/default/V1/shipment/ |
Create Invoice | Create invoice on magento | /rest/default/V1/order/{orderId}/invoice |
Get Invoice | Get invoice details from magento based on the filter of order id | /rest/default/V1/invoices |
Get Shipment | Get shipping label | /rest/default/V1/shipment/{shipmentId} |
Create Manifest | No call to channel | null |
Get Manifest | No call to channel | null |
Update Inventory | Update the inventory of a specific sku | /rest/default/V1/products/{productSku}/stockItems/{itemId} |
Credential Api | Get access token | /rest/V1/integration/admin/token |
Return Orders | No call to channel(used to create a return order corresponding to a forward order in Increff Omni) | null |
Handover Orders | The order is handed over to the delivery partner marking the order complete at magento panel | /rest/default/V1/order/{orderId}/ship |
Fetch Orders
Get Orders: GET | /rest/default/V1/orders
Lists orders that match specified search criteria. This call returns an array of objects.
Order fetch is done based on search criteria with filters on fields, status and created_at time.These statuses are the order status when the order is created.
The items to be synced should have the product_type as simple.
The field method under payment should be cashondelivery for COD orders.
The increament_id will be used as the parent order id(will be displayed on invoice and shipping label) whereas, the internal order id(used to fetch order) will be used as the channel order id.
Request
QueryParams
Name | Type | Mandatory | Comments |
|
|
|
|
|
|
|
|
|
|
|
|
Response
{
"items": [
{
"base_currency_code": "INR",
"base_discount_amount": 10.0,
"base_shipping_amount": 50.0,
"created_at": "2022-02-17 07:24:49",
"discount_amount": 50,
"entity_id": 11254,
"grand_total": 25980.0,
"discount_tax_compensation_amount": 10,
"increment_id": "M000013856",
"order_currency_code": "INR",
"shipping_amount": 60,
"status": "string",
"items": [
{
"base_original_price": 0,
"base_price": 0,
"base_price_incl_tax": 0,
"base_row_total": 0,
"base_row_total_incl_tax": 0,
"base_tax_amount": 0,
"discount_amount": 0,
"item_id": 0,
"name": "string",
"order_id": 0,
"original_price": 0,
"price": 0,
"price_incl_tax": 0,
"product_type": "simple",
"qty_canceled": 0,
"qty_ordered": 0,
"qty_refunded": 0,
"row_total_incl_tax": 0,
"sku": "string",
"tax_amount": 0,
"parent_item": {},
"product_option": {
"extension_attributes": {
"giftcard_item_option": {}
}
}
}
],
"billing_address": {
"city": "string",
"country_id": "string",
"email": "string",
"firstname": "string",
"lastname": "string",
"middlename": "string",
"postcode": "string",
"region": "string",
"street": [
"string"
],
"telephone": "string"
},
"payment": {
"method": "string"
},
"extension_attributes": {
"shipping_assignments": [
{
"shipping": {
"address": {
"city": "string",
"country_id": "string",
"email": "string",
"firstname": "string",
"lastname": "string",
"middlename": "string",
"postcode": "string",
"region": "string",
"street": [
"string"
],
"telephone": "string"
}
}
}
],
"cash_on_delivery_fee": 50.0,
"base_cash_on_delivery_fee": 60.0,
"amstorecredit_base_amount": 100.0,
"amstorecredit_amount": 120.0,
"applied_taxes": [
{
"code": "GST-18",
"title": "GST-18",
"percent": 18,
"amount": 3963.05,
"base_amount": 3963.05
}
],
"item_applied_taxes": [
{
"type": "product",
"item_id": 11593,
"applied_taxes": [
{
"code": "GST-18",
"title": "GST-18",
"percent": 18,
"amount": 3963.05,
"base_amount": 3963.05
}
]
}
]
}
}
]
}
HttpStatus : 200
Get Order Status:
GET | /rest/default/V1/orders/{id}/statuses
Gets the status for a specified order.
Request
Path parameter
Name | Type | Mandatory | Comments |
|
|
|
|
Response
“processing”
HttpStatus : 200
Order Acknowledgment
POST | rest/default/V1/orders/orders/{id}/comments
This call is made to acknowledge that the order is received in our system and to make the status of order processing in the magento panel(if not already in processing).
Request
Path parameter
Name | Type | Mandatory | Comments |
|
|
|
|
Response
True
HttpStatus : 200
Get Canceled Orders
GET | /rest/default/V1/orders
Lists orders that match specified search criteria. This call returns an array of objects.
Order fetch is done based on search criteria with filters on fields, status and updated_at time.These statuses are the order status when the order is created.
The items to be synced should have the product_type as simple.
Request
QueryParams
Name | Type | Mandatory | Comments |
|
|
|
|
|
|
|
|
|
|
|
|
Response
HttpStatus : 200
Cancel Order
POST | /rest/default/V1/orders/{id}/cancel
Cancels a specified order based on the order id of the order.
Request
Path parameter
Name | Type | Mandatory | Comments |
|
|
|
|
Response
True
HttpStatus : 200
Shipment
Create Invoice
POST | /rest/default/V1/order/{orderId}/invoice
This API call generates an invoice at magento for a specific order.
Note: This is not a mandatory call. For some clients the invoice generation on magento is done as soon as the order moves to processing status, so in cases in which such a job does not run at client end, this call generates invoice at magento, as without invoice generation, shipment creation cannot be done for magento.
Request
Path parameter
Name | Type | Mandatory | Comments |
|
|
|
|
Response
HttpStatus : 200
Get Invoice
GET | /rest/default/V1/invoices
This API call is used to get the invoice details for the specified order based on search criteria.
Request
QueryParams
Name | Type | Mandatory | Comments |
|
|
|
|
|
|
|
|
|
|
|
|
Response
{
"items": [
{
"base_currency_code": "INR",
"base_discount_amount": 0,
"base_shipping_amount": 0,
"billing_address_id": 70058,
"created_at": "2022-07-29 09:00:05",
"discount_amount": 0,
"entity_id": 1,
"grand_total": 100,
"discount_tax_compensation_amount": 0,
"increment_id": "M000033958",
"order_id": 1,
"shipping_address_id": 1,
"shipping_amount": 0,
"store_to_base_rate": 0,
"store_to_order_rate": 0,
"subtotal": 100.0,
"subtotal_incl_tax": 100,
"tax_amount": 73.93,
"total_qty": 1,
"transaction_id": "pay_Jz7LmmJjjfMjPk",
"updated_at": "2022-07-29 09:00:05",
"items": [
{
"base_discount_tax_compensation_amount": 0,
"base_price": 690,
"base_price_incl_tax": 690,
"base_row_total": 616.07,
"base_row_total_incl_tax": 690,
"base_tax_amount": 73.93,
"description": "",
"entity_id": 167859,
"discount_tax_compensation_amount": 0,
"name": "Pack of 1 dress - off white",
"parent_id": 33958,
"price": 616.07,
"price_incl_tax": 690,
"product_id": 28618,
"row_total": 616.07,
"row_total_incl_tax": 690,
"sku": "8907095618689",
"tax_amount": 73.93,
"order_item_id": 172596,
"qty": 1
}
],
"comments": []
}
],
"search_criteria": {
"filter_groups": [
{
"filters": [
{
"field": "order_id",
"value": "1",
"condition_type": "eq"
}
]
}
]
},
"total_count": 1
}
HttpStatus : 200
Create Shipment
POST | /rest/default/V1/shipment/
Performs persist operation for a specified shipment
Request
{
"entity": {
"created_at": "2022-11-30 12:28:00",
"order_id": 46773,
"items": [
{
"sku": "8907095853998",
"order_item_id": 235211,
"qty": 2
}
],
"tracks": [
{
"order_id": 46773,
"created_at": "2022-11-30 12:28:00",
"parent_id": 46773,
"weight": 1,
"qty": 1,
"description": "",
"track_number": "11704910415542",
"title": "Delhivery",
"carrier_code": "11704910415542"
}
],
"comments": [
{
"is_customer_notified": 0,
"parent_id": 0,
"comment": "comment",
"is_visible_on_front": 0,
"created_at": "2022-11-30 12:28:00",
}
]
}
}
Name | Type | Mandatory | Comments |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
entity.comments[]
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Entity.items[]
|
|
|
|
|
|
|
|
|
|
|
|
Entity.tracks[]
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Response
{
"entity_id": 0,
"increment_id": "string",
"order_id": 0
}
HttpStatus : 200
Get Shipment
GET | /rest/default/V1/shipment/{id}
Loads a specified shipment.
Request
Path parameter
Name | Type | Mandatory | Comments |
|
|
|
|
Response
{
"entity_id": 0,
"increment_id": "string",
"order_id": 0
}
HttpStatus : 200
Update Inventory
PUT | /rest/default/V1/products/{productSku}/stockItems/{itemId}
This API will push the inventory count to the channel.
Request
Path parameter
Name | Type | Mandatory | Comments |
|
|
|
|
|
|
|
|
Request Body
Name | Type | Mandatory | Comments |
|
|
|
|
|
|
|
|
|
|
|
|
Response
32380(entity id)
HttpStatus : 200
Handover
POST | /rest/default/V1/order/{orderId}/ship
This API marks the order complete in magento.
Request
Path parameter
Name | Type | Mandatory | Comments |
|
|
|
|
Response
2568 ( Handover ID)
HttpStatus : 200
Create Return Order
Inbound | POST | /return-orders
Summary
This API is used to create B2C return orders in Increff Omni.
Description
This API is used to create B2C return orders in Increff Omni. One order item represents only one quantity of an SKU. If there are multiple quantities of the same SKU then multiple order items should be created.
Request
{
"forwardOrderCode": "108",
"returnOrderCode": "100078",
"locationCode": "Wid234",
"returnOrderTime": "2020-10-16T20:22:28.000+05:30",
"orderItems": [
{
"itemCode": "I10098",
"reason": "Different Size",
"channelSkuCode": "10007345"
}
],
"orderType": "CUSTOMER_RETURN",
"awbNumber": "HYN402",
"transporter": "transporter"
}
Parameter Name | Data Type | Description | Mandatory |
| String | Forward order code for which return order is being created. This will be the entity_id of the forward order created in Increff Omni | yes |
| String | This is a unique identifier provided by the channel to identify the return order | yes |
| String | Location code of the warehouse where the return order will be received. This is the location code of order in Increff Omni. | yes |
| String | Time at which return order got placed by customer. This should be in the format as mentioned above | no |
| Object[] | Array of order items, order items represent each line of return order. | yes |
| String | This is a unique identifier provided by the channel to identify the return order item. | yes |
| String | Reason for return as given by the customer. | yes |
| String | SKU code for return order item. | yes |
| String | Type of return. Possible values - SELF_SHIP,CUSTOMER_RETURN,RETURN_TO_ORIGIN | yes |
| String | Courier tracking number. | no |
| String | Courier partner name. | no |
Response
Empty Body
HttpStatus : 200
Nuances
Shipment
The required by time of Increff OMS(SLA) is set as 2 days from the time at which the order is created at channel.
Shipping Label
Shipping labels are generated by RMS.
The customer address details will not be changed after order creation.(If needed in case of a pin code not serviceable from clickpost)it should be raised and then will be changed from the database.
A set of default dimensions will be sent to the logistic aggregator(non configurable)
Invoice
Signature and logo png file to be provided by the client which further needs to be stored in the system.(By default increff logo is used in invoice)
From party location contact name will be shown in the from to address in invoice
The invoice will include item level discount(which is populated from magento in the discount field of the get order response payload)
The total discount will be shown in the invoice (it can also include the store credit if it is present in amstorecredit_amount inside the extension_attributes of the order response payload).
The cash on delivery fee is added to the shipping charge in case it is present in the field cash_on_delivery_fee inside the extension_attributes of order.
HSN code will be visible under Item tax code/HSN code
The pdf format supported is A4 size.
Two options for invoice creation: channel or RMS.
Channel
Tax breakup to be provided by the channel under the item_applied_tax object of the get order response(Invoice pdf creation will be based on these details). The code, percentage and amount will be visible in the invoice. The code should be IGST/CGST/SGST.
Logo png file to be provided by the client which further needs to be stored in the system.
RMS
Logistic Aggregator type to be selected from CLICKPOST, SHIPROCKET, SHIPWAY
The Invoice prefix and series(Integer) to be provided by client
Updates
Multi-warehousing support in Magento- 13-May-23
Introduced multi-warehousing support through our advanced order splitting and routing capabilities. This means that we can now split and route all orders to different locations mapped to the client-channel pair, providing seamless fulfillment across multiple locations.
As Magento does not support multi-warehousing and does not split orders based on location, we have implemented this functionality to support multi-warehousing.
All the orders will be split based on the selected logic of splitting and routing