Salla Docs
App Cycle
There are several steps that occur before processing a shipping order, and these steps are crucial to streamlining the shipping process, from creating a shipment based on the order from the Merchant to handling returned and cancelled shipments.
The Salla Shipping API is a tool designed to help developers integrate shipping functionality into Salla Stores. With this API, users can manage their shipments, returns, and cancellations through seamless endpoints and straightforward flows.
:::tip[Note]
- The App has to be subscribed to two store webhooks, which are:
shipment.creating&shipment.cancelled. - To learn more about Webhooks, such as Registration, Security Strategies, Troubleshooting and more, read more here.
:::
In this article, we will take a closer look at:
Creating New Shipment
The following diagram visually displays the Create New Shipment stage:
sequenceDiagram
actor m as Salla Merchant
participant s as Salla Platform
participant a as Shipping App
m->>s: Create Shipment
Note right of m: Auto when Order Status is 'completed' <br/> or policy is requested by Merchant
s->>a: Dispatch shipment.creating Webhook
a->>a: Generate Shipment
Note left of a: PUT /shipment/{shipment_id} <br/> {shipment_number, tracking_number, tracking_link ..}
a->>s: Provide Shipment Details via API
Note left of s: in order details and history
s->>m: Show Shipment Details
Note left of a: Report actual shipping cost and status_note.
a->>s: PUT /shipment/{shipment_id} <br/> {cost, status_note}
The first stage in the Shipping Cycle is creating a new shipment request when a new order has been set by the Salla Merchant, and this happens:
- The Order Status is changed to
completed | تم التنفيذ - Via the Merchant Dashboard, where the Merchant clicks on the
Generate Policy | اصدار بوليصةbutton
The store webhook, shipment.creating, will be triggered and sent to your shipping app. As a result, you will be able to use the shipment information, such as the recipient's address and the items being shipped, to create the shipment and set up the delivery process, and the Merchant will be able to download the shipment policy.
You will be able to update the shipment information using the Update Shipment Details API endpoint.
The following payload is correspondent to when the shipment.creating event is fired
The following response is what you should expect when the shipment.creating event is fired
{
"event":"shipment.creating",
"merchant":136409261,
"created_at":"Sun Jan 29 2023 21:16:38 GMT+0300",
"data":{
"order_id":538219147,
"id":629905440,
"created_at":{
"date":"2023-01-29 21:16:38.000000",
"timezone_type":3,
"timezone":"Asia/Riyadh"
},
"type":"shipment",
"courier_id":1927161457,
"courier_name":"Shipping App",
"courier_logo":"https://company.com/logo.png",
"shipping_number":"846984645",
"tracking_number":"4324233",
"pickup_id":null,
"trackable":true,
"tracking_link":"https://www.company/tracking/tracking-express.html?submit=1&tracking-id=12345",
"label":{
"format":"pdf",
"url":"https://company.com/lable.pdf"
},
"payment_method":"cod",
"source":"api",
"status":"delivered",
"total":{
"amount":25.5,
"currency":"SAR"
},
"cash_on_delivery":{
"amount":10.7,
"currency":"SAR"
},
"is_international":false,
"total_weight":{
"value":5,
"units":"kg"
},
"packages":[
{
"name":"منتج تجريبي",
"sku":"6ytrrhrhr",
"price":{
"amount":25.5,
"currency":"SAR"
},
"quantity":1,
"weight":{
"value":5,
"unit":"kg"
}
}
],
"ship_from":{
"type":"branch",
"name":"الفرع الرئيسي",
"email":"",
"phone":"966920034002",
"country":"السعودية",
"city":"Mecca",
"address_line":"Mecca,السعودية",
"street_number":null,
"block":null,
"postal_code":null,
"latitude":21.3825905096851,
"longitude":39.77319103068542,
"branch_id":1987977866
},
"ship_to":{
"type":"address",
"name":"Username",
"email":"[email protected]",
"phone":"966501806978",
"country":"السعودية",
"city":"الرياض",
"address_line":" شارع 2345، الحي السلام 95128،, شارع عبدالله سنابل السلام مكة السعوديه,, الرياض, السعودية",
"street_number":"2345",
"block":"السلام",
"postal_code":"95128",
"latitude":21.382590509685,
"longitude":39.773191030685
},
"meta":{
"app_id":1222362158,
"policy_options":{
"boxes":1
}
}
}
}
The following enlists the values that can be sent to the endpoint to update the details of the shipment
✅ When the endpoint is consumed successfully, your shipping App is expected to receive this payload.
:::tip[Note]
As a shipping App, you need to ensure the following when updating the Shipment Details:
- Update the
costvariable, containing the actual cost value of the Shipping that the Merchant will be charged for, which is calculated per the shipping App's actual costs. Ensure to include VAT in the cost. - Update the shipment status according to its current status.
:::
Updating Shipment / Order Status
Update the shipment and/or order status based on its current status using the Update Shipment Details endpoint.
This allows you to use a single API for both updating shipment and order status. You can take the following payload as an example to update the shipment / order status:
{
"shipment_number": "123123",
"status": "delivered",
}
Required vs Optional Parameters
The "shipment_number" value is required and must match the value used in the first update shipment request. The rest of the parameters are optional.
Available Statuses
The available statuses when updating shipments / order statuses are listed as below:
• "created"
• "shipped"
• "delivering"
• "delivered"
• "in_progress"
• "cancelled"
Exception Shipment Statuses
If the shipment status is set to either "shipped", "delivering", or "delivered", the status cannot be updated to "created" nor "in_progress"
Handling Returns
In the case of a shipment return, the store webhook shipment.creating will be triggered with the type value set to return in the payload.
This event will be triggered when:
- The Order Status is set to
restoringorrestored - Via the Merchant Dashboard, where the Merchant clicks the
Generate Return Policy | اصدار بوليصة ارجاعbutton
The following diagram visually explains the Shipment Cancellation stage:
sequenceDiagram
actor m as Salla Merchant
participant s as Salla Platform
participant a as Shipping App
m-->>s: Request create return shipment
s-->>a: Dispatch shipment.creating Webhook with type return
a->>a: Generate Return Shipment
a-->>s: Provide Return Details
Note left of a: PUT /shipment/{shipment_id} <br/> {tracking_link, shipment_number, tracking_number ..}
s->>m: Show Shipment Details
Note left of s: in order details and history
The shipping App will be able to access the shipment information using the Update Shipment Details API endpoint. The following enlists the values that are sent to the endpoint to update the details of the order:
The following payload is correspondent to when the shipment.creating event is fired with the "type" variable set to "return".
The following response is what you should expect when the shipment.creating event is fired with the "type" variable set to "return".
{
"event":"shipment.creating",
"merchant":136409261,
"created_at":"Sun Jan 29 2023 21:16:38 GMT+0300",
"data":{
"order_id":538219147,
"id":629905440,
"created_at":{
"date":"2023-01-29 21:16:38.000000",
"timezone_type":3,
"timezone":"Asia/Riyadh"
},
"type":"return",
"courier_id":1927161457,
"courier_name":"Shipping App",
"courier_logo":"https://company.com/logo.png",
"shipping_number":"846984645",
"tracking_number":"4324233",
"pickup_id":null,
"trackable":true,
"tracking_link":"https://www.company/tracking/tracking-express.html?submit=1&tracking-id=12345",
"label":{
"format":"pdf",
"url":"https://company.com/lable.pdf"
},
"payment_method":"cod",
"source":"api",
"status":"delivered",
"total":{
"amount":25.5,
"currency":"SAR"
},
"cash_on_delivery":{
"amount":10.7,
"currency":"SAR"
},
"is_international":false,
"total_weight":{
"value":5,
"units":"kg"
},
"packages":[
{
"name":"منتج تجريبي",
"sku":"6ytrrhrhr",
"price":{
"amount":25.5,
"currency":"SAR"
},
"quantity":1,
"weight":{
"value":5,
"unit":"kg"
}
}
],
"ship_from":{
"type":"branch",
"name":"الفرع الرئيسي",
"email":"",
"phone":"966920034002",
"country":"السعودية",
"city":"Mecca",
"address_line":"Mecca,السعودية",
"street_number":null,
"block":null,
"postal_code":null,
"latitude":21.3825905096851,
"longitude":39.77319103068542,
"branch_id":1987977866
},
"ship_to":{
"type":"address",
"name":"Username",
"email":"[email protected]",
"phone":"966501806978",
"country":"السعودية",
"city":"الرياض",
"address_line":" شارع 2345، الحي السلام 95128،, شارع عبدالله سنابل السلام مكة السعوديه,, الرياض, السعودية",
"street_number":"2345",
"block":"السلام",
"postal_code":"95128",
"latitude":21.382590509685,
"longitude":39.773191030685
},
"meta":{
"app_id":1222362158,
"policy_options":{
"boxes":1
}
}
}
}
The following enlists the values that can be sent to the endpoint to update the details of the shipment
✅ When the endpoint is consumed successfully, your shipping App is expected to receive this payload with the "type" variable set to "return".
Cancelling Shipment
In the case of cancelling a shipment, the event shipment.cancelled will be triggered with a type value set to return or shipment, depending on the canceled shipment.
The following diagram visually explains the Shipment Cancellation stage:
sequenceDiagram
actor m as Salla Merchant
participant s as Salla Platform
participant a as Shipping App
m-->>s: Cancel Shipment
s-->>a: Dispatch shipment.cancelled Webhook
s-->>m: Update shipemant details
The store webhook, shipment.cancelled, will be triggered and sent to the shipping app, which then will be able to access the updated shipment information and handle the cancellation process.
When the event is fired successfully, the shipping App is expected to receive the following payload
🎉 Getting here means that the developer has a full overview of the Shipping App Cycle and now ready to Setup the Shipping App.