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.

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

Handling Returns

Cancelling Shipment

Creating New Shipment

The following diagram visually displays the Create New Shipment stage:

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.

Webhook Payload shipment.creating

Update Shipment Request Body

Update Shipment Response Body

Payload

Response

The following payload is correspondent to when the shipment.creating event is fired

Shipments Webhook Events Model

Note

As a shipping App, you need to ensure the following when updating the Shipment Details:

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 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:

Payload

Sample

Sample Example - Order / Shipment Status

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"

Update Shipments / Orders Diagram

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 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:

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:

Webhook Payload shipment.creating

Update Shipment Request Body

Update Shipment Response Body

Payload

Response

The following payload is correspondent to when the shipment.creating event is fired with the "type" variable set to "return".

Shipments Webhook Events Model

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:

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.

Webhook Payload shipment.cancelled

When the event is fired successfully, the shipping App is expected to receive the following payload

Payload

Response

Shipments Webhook Events Model

🎉

Getting here means that the developer has a full overview of the Shipping App Cycle and now ready to Setup the Shipping App.

Creating New Shipment#

Updating Shipment / Order Status#

Required vs Optional Parameters#

Available Statuses#

Exception Shipment Statuses#

Handling Returns#

Cancelling Shipment#

Creating New Shipment

Updating Shipment / Order Status

Required vs Optional Parameters

Available Statuses

Exception Shipment Statuses

Handling Returns

Cancelling Shipment