Generating Shipping Labels
One of the most common shipping strategies in the marketplace space is to provide vendors with shipping labels. Onport integrates with multiple carrier aggregators which are able to provide real time shipping rates and generate labels for Purchase Orders. The supported carrier aggregators are:
- This process can be carried out from Onport's app or initiated by vendors though the vendor portal.
However, custom marketplace flows may require the shipping labels to be generated programmatically. This can be accomplished with Onport's API.
The main steps to generate a shipping label based on a Purchase Order are:
- Weight Calcuation
- Rate Calculation
- Shipment Creation
Weight Calculation
Although dimensions and weight can be set arbitrarily, it is recommended to use Onport's endpoint to calculate them.
The cURL request below:
curl --request GET \--url https://api.jetti.io/api/purchases/:id/calculate-weight.json \--header 'Authorization: Bearer {{token}}' \--header 'Content-Type: application/json'
would return the following response:
{"massUnit": "g","missing": [],"weight": 420,"totalQuantity": 1,"dimensions": {"length": 2.4,"width": 11.5,"height": 13.3,"distanceUnit": "in"}}
It is necessary to replace :id with the Purchase Order ID.
The following properties will need to be saved as they will be used in subsequent API calls.
- dimensions.length
- dimensions.width
- dimensions.height
- dimensions.distanceUnit
- weight
- massUnit
Rate Calculation
The next step is to calculate the rates based on the same Purchase Order ID.
This can be accomplished by making the following cURL request, after replacing :id with the Purchase Order Id.
curl --request POST \--url https://api.jetti.io/api/purchases/:id/rates.json \--header 'Authorization: Bearer {{token}}' \--header 'Content-Type: application/json' \--data '{"dimensions":{"height":13.3,"width":11.5,"length":2.4,"weight":"420.0000","distanceUnit":"in","massUnit":"g"},"async":true,"ids":[]}'
Jetti's API will return the main rate as well as potential alternatives. In order to proceed with label generation, it will be necessary to collect the quoteId of the chosen rate.
The quoteId is available from the following elements, expressed in JSONPath:
- rates.quoteId
- rates.alternatives[0].quoteId
- rates.alternatives[n].quoteId
Shipment Creation
Once the quoteId is collected, it is possible to request the carrier aggregator to generate a shipment (as well as shipping label and tracking code).
This can be accomplished by calling the following endpoint, after replacing :id with the Purchase Order ID and :quoteId with the previous Quote ID.
curl --request POST \--url https://api.jetti.io/api/purchases/:id/ship.json \--header 'Authorization: Bearer {{token}}' \--header 'Content-Type: application/json' \--data '{"inventoryStatus":"shipped","rateId":":quoteId","ids":[]}'
The successful Shipment Creation will return a Dropshipment. Further details on all the properties of a Dropshipment are availble via the API Documentation.
The following properties are usually recommended to be stored externally for further processing:
- id
- labelUrl
- trackingCompany
- trackingUrl
- serviceLevel
Single Request Label generation
In case it's necessary to reduce the number of requests made to Onport's API, without the need to calculate weights or get Rate ID, it is possible to use the POST /api/purchases/:id/default-label.json endpoint.
It will be necessary to change :id with the Purchase Order's ID.
curl --request POST \--url https://api.jetti.io/api/purchases/:id/default-label.json \--header 'Authorization: Bearer {{token}}' \--header 'Content-Type: application/json' \--data '{"inventoryStatus":"shipped","ids":[]}'
Partial Shipments
Both POST /api/purchases/:id/ship.json and POST https://api.jetti.io/api/purchases/:id/default-label.json endpoints support partial shipments.
This is carried out by providing a value of the ids array.
Below is an example:
"ids": [{ id: 1, quantity: 10}]
The Purchase Item ID will need to be set as value for the id.