# 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](https://docs.salla.dev/doc-421119#list-of-salla-store-events?nav=01HNA8MH78MVX1S0DRXDHE3A1K), which are: [`shipment.creating`](https://docs.salla.dev/doc-433807/?nav=01J1Y9KTRRDA57Q8ZSW95TTVDB) & [`shipment.cancelled`](https://docs.salla.dev/doc-433807/?nav=01J1Y9KTRRDA57Q8ZSW95TTVDB).
- To learn more about Webhooks, such as Registration, Security Strategies, Troubleshooting and more, read more [here](https://docs.salla.dev/doc-421119?nav=01HNA8MH78MVX1S0DRXDHE3A1K). ::: In this article, we will take a closer look at: - [Creating New Shipment](#creating-new-shipment) - [Handling Returns](#handling-returns) - [Cancelling Shipment](#cancelling-shipment) ### Creating New Shipment The following diagram visually displays the Create New Shipment stage: ```mermaid 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'
or policy is requested by Merchant s->>a: Dispatch shipment.creating Webhook a->>a: Generate Shipment Note left of a: PUT /shipment/{shipment_id}
{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}
{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](https://docs.salla.dev/api-5394148?nav=01HNA8MH78MVX1S0DRXDHE3A1K) is changed to `completed | تم التنفيذ` - Via the Merchant Dashboard, where the Merchant clicks on the `Generate Policy | اصدار بوليصة` button The store webhook, [`shipment.creating`](https://docs.salla.dev/doc-433807/?nav=01J1Y9KTRRDA57Q8ZSW95TTVDB), 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](http[s://docs.salla.dev/api-5394233?nav=01HNA8MH78MVX1S0DRXDHE3A1K) 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 ```json { "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":"username@email.com", "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. ✅ When the endpoint is consumed successfully, your shipping App is expected to receive this JSON payload. ```json { "status": 200, "success": true, "data": { "id": 1139865338, "reference_id": null, "created_at": { "date": "2023-01-12 14:19:08.000000", "timezone_type": 3, "timezone": "Asia/Riyadh" }, "type": "shipment", "courier": { "id": 814202285, "name": "DHL", "logo": "https://company.com/logo.png" }, "shipping_number": "0", "tracking_number": "0", "pickup_id": null, "trackable": true, "tracking_link": "https://www.company/tracking/tracking-express.html?submit=1&tracking-id=12345", "label": [], "payment_method": "cod", "source": "api", "status": { "id": 566146469, "name": "بإنتظار المراجعة", "slug": "under_review" }, "total": { "amount": 7000, "currency": "SAR" }, "cash_on_delivery": { "amount": 15, "currency": "SAR" }, "meta": { "app_id": null, "policy_options": { "boxes": 2 } }, "ship_from": { "type": "branch", "branch_id": 1723506348, "name": "Riyadh", "email": null, "phone": "0555555555", "country": "السعودية", "city": "الرياض", "address_line": "7687 طريق الملك فهد الفرعي، الملك فهد، الرياض 12262 3010، السعودية", "street_number": "7687 طريق الملك فهد الفرعي", "block": "الملك فهد", "postal_code": "12262", "geo_coordinates": { "lat": "24.7431373", "lng": "46.6570741" } }, "ship_to": { "type": "address", "name": "Username", "email": "username@email.com", "phone": "050-948-0868", "country": "السعودية", "city": "الرياض", "address_line": "شارع عبدالله سنابل السلام مكة السعوديه", "street_number": "2345", "block": "السلام", "postal_code": "95128", "geo_coordinates": { "lat": "21.382590509685", "lng": "39.773191030685" } }, "packages": [ { "name": "Apple Watch", "sku": "6ytrrhrhr", "price": { "amount": "1000.00", "currency": "SAR" }, "quantity": 2, "weight": { "value": "0.10", "unit": "kg" } }, { "name": "Apple Iphone 14 Pro Max", "sku": "6ytrrhrhr3332", "price": { "amount": "5000.00", "currency": "SAR" }, "quantity": 1, "weight": { "value": "0.50", "unit": "kg" } } ] } } ``` :::tip[Note] As a shipping App, you need to ensure the following when updating the [Shipment Details](https://docs.salla.dev/api-5394234?nav=01HNA8MH78MVX1S0DRXDHE3A1K): - Update the `cost` variable, 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](https://docs.salla.dev/api-5394234?nav=01HNA8MH78MVX1S0DRXDHE3A1K) 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: ```json { "shipment_number": "123123", "status": "delivered", } ``` #### Required vs Optional Parameters The `"shipment_number"` and `"status"`values åre **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"` ![](https://api.apidog.com/api/v1/projects/451700/resources/342721/image-preview) ### Handling Returns In the case of a shipment return, the [store webhook](https://docs.salla.dev/doc-421119#list-of-salla-store-events) `shipment.creating` will be triggered with the `type` value set to `return` in the payload. This event will be triggered when: - The [Order Status](https://docs.salla.dev/api-5394148?nav=01HNA8MH78MVX1S0DRXDHE3A1K) is set to `restoring` or `restored` - Via the Merchant Dashboard, where the Merchant clicks the `Generate Return Policy | اصدار بوليصة ارجاع` button The following diagram visually explains the Shipment Cancellation stage: ```mermaid 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}
{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](https://docs.salla.dev/api-5578810/?nav=01HNA8MH78MVX1S0DRXDHE3A1K) 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"`. ```json { "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":"username@email.com", "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"`. ✅ When the endpoint is consumed successfully, your shipping App is expected to receive this JSON payload with the `"type"` variable set to `"return"`. ```json { "status": 200, "success": true, "data": { "id": 1139865338, "reference_id": null, "created_at": { "date": "2023-01-12 14:19:08.000000", "timezone_type": 3, "timezone": "Asia/Riyadh" }, "type": "return", "courier": { "id": 814202285, "name": "DHL", "logo": "https://company.com/logo.png" }, "shipping_number": "0", "tracking_number": "0", "pickup_id": null, "trackable": true, "tracking_link": "https://www.company/tracking/tracking-express.html?submit=1&tracking-id=12345", "label": [], "payment_method": "cod", "source": "api", "status": { "id": 566146469, "name": "بإنتظار المراجعة", "slug": "under_review" }, "total": { "amount": 7000, "currency": "SAR" }, "cash_on_delivery": { "amount": 15, "currency": "SAR" }, "meta": { "app_id": null, "policy_options": { "boxes": 2 } }, "ship_from": { "type": "branch", "branch_id": 1723506348, "name": "Riyadh", "email": null, "phone": "0555555555", "country": "السعودية", "city": "الرياض", "address_line": "7687 طريق الملك فهد الفرعي، الملك فهد، الرياض 12262 3010، السعودية", "street_number": "7687 طريق الملك فهد الفرعي", "block": "الملك فهد", "postal_code": "12262", "geo_coordinates": { "lat": "24.7431373", "lng": "46.6570741" } }, "ship_to": { "type": "address", "name": "Username", "email": "username@email.com", "phone": "050-948-0868", "country": "السعودية", "city": "الرياض", "address_line": "شارع عبدالله سنابل السلام مكة السعوديه", "street_number": "2345", "block": "السلام", "postal_code": "95128", "geo_coordinates": { "lat": "21.382590509685", "lng": "39.773191030685" } }, "packages": [ { "name": "Apple Watch", "sku": "6ytrrhrhr", "price": { "amount": "1000.00", "currency": "SAR" }, "quantity": 2, "weight": { "value": "0.10", "unit": "kg" } }, { "name": "Apple Iphone 14 Pro Max", "sku": "6ytrrhrhr3332", "price": { "amount": "5000.00", "currency": "SAR" }, "quantity": 1, "weight": { "value": "0.50", "unit": "kg" } } ] } } ``` ### 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: ```mermaid 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`](https://docs.salla.dev/doc-433807/?nav=01J1Y9KTRRDA57Q8ZSW95TTVDB), 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 ```json { "event": "shipment.cancelled", "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": "cancelled", "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": "username@email.com", "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 } } } } ``` :::highlight green 🎉 Getting here means that the developer has a full overview of the Shipping App Cycle and now ready to [Setup](https://docs.salla.dev/doc-422996?nav=01HNA8MH78MVX1S0DRXDHE3A1K) the Shipping App. :::