CONNECTOR CONTRACT V1
What your system needs to expose
This page is for developers. It defines the interface between UC Integrator and a transport management system, so you can judge the work before committing to it.
Read this first — the direction of truth
The integrator is the system of record. It issues the tracking number, generates the shipping label and owns shipment status. Your system does not supply tracking numbers and is never called while Unicommerce is waiting.
Every operation below is a best-effort synchronisation, running outside the request Unicommerce makes. If your system is slow, offline or mid-upgrade, Unicommerce still receives a correct and immediate answer; the synchronisation is retried and the failure is surfaced in monitoring. This is deliberate: a transport system outage must never turn into a failed waybill for the seller.
It also means a connector is optional. A company with no system of its own works directly in our console, and every Unicommerce endpoint behaves identically.
Why every requirement here is traceable
Each operation and field below cites the Unicommerce requirement it comes from. That is intentional. Nothing on this page is an eMathrix preference you could negotiate away — if an item is listed, Unicommerce's specification requires the data, and an integration that omits it will not pass their testing.
Operations
Declare which of these your system supports. Only capabilities is
mandatory: it is how a connector states what it can and cannot do, so unsupported
operations are skipped rather than failing.
| Operation | Direction | Required | Input | Returns | Purpose and Unicommerce basis |
|---|---|---|---|---|---|
capabilities | Local | Required | — | set<operation_name> | Declare which operations this connector's TMS supports. A 'none' connector returns the empty set; a company with no system of its own shipping providers operate directly on the integrator. |
push_shipment | Integrator → your system | Optional | shipment | — | Mirror a newly created shipment (with our AWB and label URL) to the shipping provider's TMS for fulfilment. POST /waybill (spec 3.2): shipment creation returning waybill + shippingLabel |
push_shipment_update | Integrator → your system | Optional | shipment | — | Mirror an updated shipment after Waybill Updation, including the re-issued label. Waybill Updation (spec 3.3): updates an allocated shipment, returns fresh shippingLabel |
pull_status | Your system → integrator | Optional | list<awb> (max 50) | list<status> | Sync current status and tracking history from the TMS INTO the integrator so /waybillDetails answers from our own tables, never a live TMS call. GET /waybillDetails (spec 3.4): up to 50 AWBs; requires currentStatus, statusDate, tracking_history |
push_cancel | Integrator → your system | Optional | awb | — | Mirror a cancellation to the TMS. POST /cancel (spec 3.5, optional) |
Fields
These are the fields Unicommerce requires, so the record stays complete regardless of what your own system happens to store.
Shipment
Carried whenever a shipment is mirrored to your system.
| Field | Type | Required | Applies to | Required by Unicommerce because… |
|---|---|---|---|---|
code | string | Required | Both | waybill.Shipment.code — unique at seller UC warehouse level; idempotency key with seller |
SaleOrderCode | string | Required | Both | waybill.Shipment.SaleOrderCode — unique at channel level |
orderCode | string | Required | Both | waybill.Shipment.orderCode — display code, may be duplicated at channel level |
channelCode | string | Optional | Both | waybill.Shipment.channelCode |
channelName | string | Optional | Both | waybill.Shipment.channelName |
invoiceCode | string | Optional | Forward | waybill.Shipment.invoiceCode — forward only |
orderDate | datetime(dd-MMM-yyyy HH:mm:ss) | Required | Both | waybill.Shipment.orderDate — format 16-Sep-2021 00:00:00 |
fullFilllmentTat | datetime(dd-MMM-yyyy HH:mm:ss) | Required | Both | waybill.Shipment.fullFilllmentTat — spelled with three l's in UC spec; match exactly |
weight | float(grams, max 6 digits/4 dp) | Required | Both | waybill.Shipment.weight — grams |
length | string(mm) | Required | Both | waybill.Shipment.length — millimetres |
height | string(mm) | Required | Both | waybill.Shipment.height — millimetres |
breadth | string(mm) | Required | Both | waybill.Shipment.breadth — millimetres |
numberOfBoxes | string | Required | Forward | waybill.Shipment.numberOfBoxes — default 1; forward only |
items | array<item> | Required | Both | waybill.Shipment.items[] |
deliver_by_date | date | Optional | Both | waybill.Shipment.customField[] entry named 'deliver_by_date' — UC confirmed 2026-08-07 (open question Q7) as the scheduled delivery date. Optional: customField is Optional and arrives as [] when nothing maps, so a connector must accept its absence. The TMS needs it to schedule the delivery. |
serviceType | string | Optional | Both | waybill.serviceType — agreed with seller at UC shipper config |
returnShipmentFlag | string(bool) | Required | Both | waybill.returnShipmentFlag — 'false' forward, 'true' reverse |
paymentMode | string(COD|PREPAID) | Required | Both | waybill.paymentMode |
currencyCode | string(ISO 4217) | Required | Both | waybill.currencyCode |
totalAmount | string(decimal) | Required | Both | waybill.totalAmount |
collectableAmount | string(decimal) | Required | Both | waybill.collectableAmount — 0.00 for prepaid |
deliveryAddressDetails | address | Required | Both | waybill.deliveryAddressDetails |
pickupAddressDetails | address | Required | Both | waybill.pickupAddressDetails |
returnAddressDetails | address | Required | Forward | waybill.returnAddressDetails — not sent when returnShipmentFlag true |
waybill | string | Required | Both | waybill response.waybill — OUR AWB, permanent for shipment life (FAQ Q5); issued by integrator, never by a connector |
shippingLabel | string(url) | Required | Forward | waybill response.shippingLabel — PDF URL, unencrypted, must exist when we respond (FAQ Q6); generated by integrator |
courierName | string | Optional | Both | waybill response.courierName — direct LSP: our own company name (shipping providers.company_name) |
routingCode | string | Optional | Forward | waybill response.routingCode — shipper pickup routing code |
Address
Used by the delivery, pickup and return address blocks.
| Field | Type | Required | Applies to | Required by Unicommerce because… |
|---|---|---|---|---|
name | string | Required | Both | waybill address block.name |
phone | string | Required | Both | waybill address block.phone |
address1 | string | Required | Both | waybill address block.address1 |
pincode | string | Required | Both | waybill address block.pincode (open question 8: PH format) |
city | string | Required | Both | waybill address block.city |
state | string | Required | Both | waybill address block.state |
country | string | Required | Both | waybill address block.country |
stateCode | string(2-digit ISO) | Required | Both | waybill address block.stateCode (open question 3/8) |
countryCode | string(2-digit ISO) | Required | Both | waybill address block.countryCode (open question 3/8) |
Item
One entry per line item on the shipment.
| Field | Type | Required | Applies to | Required by Unicommerce because… |
|---|---|---|---|---|
name | string | Required | Both | waybill Shipment.items[].name |
description | string | Required | Both | waybill Shipment.items[].description |
quantity | int | Required | Both | waybill Shipment.items[].quantity |
skuCode | string | Required | Forward | waybill Shipment.items[].skuCode — forward only (open question 3) |
itemPrice | float | Required | Forward | waybill Shipment.items[].itemPrice — forward only (open question 3) |
return_reason | string | Optional | Reverse | waybill Shipment.items[].return_reason — reverse only |
Status
Returned when your system reports shipment status back.
| Field | Type | Required | Applies to | Required by Unicommerce because… |
|---|---|---|---|---|
waybill | string | Required | Both | waybillDetails[].waybill |
statusDate | datetime(dd-MMM-yyyy HH:mm:ss) | Required | Both | waybillDetails[].statusDate |
currentStatus | string | Required | Both | waybillDetails[].currentStatus — mapped onto the status list you supply; no status vocabulary is hardcoded |
current_sub_status | string | Optional | Both | waybillDetails[].current_sub_status — MUST be blank until parent/child agreed with UC (spec 3.4) |
tracking_history | array<history_event> | Optional | Both | waybillDetails[].tracking_history[] (date_time,status,sub_status,remark,location,pincode,city,state,country) |
Rules every caller must honour
- never_null — waybillDetails FAQ Q3 — send blank string or omit; never null. Callers must honour this on every field.
Versioning
This is version v1 of the contract. Fields may be added in a later version; existing meanings will not change under the same version number. Build against v1 and a later revision will not break you silently.
What is not on this page
How UC Integrator implements its side — storage, numbering, label rendering, monitoring — is not published here. You do not need it to build a connector, and it is not part of the interface. If your integration needs something this page does not answer, ask us directly rather than inferring it.