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

This webhook schema defines shipment event properties, including event name, merchant ID, creation timestamp, shipment data (order and shipment ID, type, courier, tracking, payment, and status), and other details. The webhook provides shipment-specific details to update the receiver's systems.

event

enum<string>

optional

Event Name

Allowed values:

shipment.creatingshipment.createdshipment.updatedshipment.cancelled

merchant

number

optional

Merchant ID who installed the application on their store. Get details on the Merchant via the ID using the endpoint here

created_at

string

optional

Webhook Created At Date Timestamp

data

object

optional

number

optional

This field refers to a unique identifier for the shipment.

Example:

987654321

order_id

integer

optional

This field refers to the unique identifier for the order associated with the shipment.

Example:

123456789

order_reference_id

number | null

optional

This field refers to a reference ID that can be used to look up additional information about the order

created_at

object

optional

type

enum<string>

optional

Shipment Type

Allowed values:

returnshipment

Example:

shipment

courier_id

integer

optional

Shipment Courier ID. Find a complete list of Shipment companies here

Example:

1723506348

courier_name

string

optional

Shipment Courier Name

Example:

Semsa

courier_logo

string

optional

Shipment Courier Logo

Example:

https://semsa.com/assets/logo.png

shipping_number

string

optional

Shipment Shipping Number

Example:

192837465

tracking_number

string

optional

Shipment Tracking Number

Example:

918273645

pickup_id

null

optional

Shipment Pickup ID

Example:

10954392

trackable

boolean

optional

Whether or not the shipment is trackable

Example:

true

tracking_link

string

optional

Shipment Tracking Link

Example:

https://semsa.com/tracking/order_url.com

label

object

optional

payment_method

enum<string>

optional

Shipment Payment Method

Allowed values:

codpre_paid

Example:

cod

source

string

optional

Shipment Source

Example:

dashboard

status

enum<string>

optional

Shipment Status

Allowed values:

createdin_progressdeliveringdeliveredshippedcancelled

Example:

in_progress

total

object

optional

cash_on_delivery

object

optional

is_international

boolean

optional

Whether the shipment is shipped internationally

Example:

true

total_weight

object

optional

packages

array [object {8}]

optional

ship_from

object

optional

ship_to

object

optional

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

shipment_number

string

required

Shipment Number. Must match the shipment number in the first request.

status

enum<string>

required

Shipment / Order Status. Use only the allowed enum values.

Allowed values:

createdshippeddeliveringdeliveredin_progresscancelled

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

event

enum<string>

optional

Event Name

Allowed values:

shipment.creatingshipment.createdshipment.updatedshipment.cancelled

merchant

number

optional

Merchant ID who installed the application on their store. Get details on the Merchant via the ID using the endpoint here

created_at

string

optional

Webhook Created At Date Timestamp

data

object

optional

number

optional

This field refers to a unique identifier for the shipment.

Example:

987654321

order_id

integer

optional

This field refers to the unique identifier for the order associated with the shipment.

Example:

123456789

order_reference_id

number | null

optional

This field refers to a reference ID that can be used to look up additional information about the order

created_at

object

optional

type

enum<string>

optional

Shipment Type

Allowed values:

returnshipment

Example:

shipment

courier_id

integer

optional

Shipment Courier ID. Find a complete list of Shipment companies here

Example:

1723506348

courier_name

string

optional

Shipment Courier Name

Example:

Semsa

courier_logo

string

optional

Shipment Courier Logo

Example:

https://semsa.com/assets/logo.png

shipping_number

string

optional

Shipment Shipping Number

Example:

192837465

tracking_number

string

optional

Shipment Tracking Number

Example:

918273645

pickup_id

null

optional

Shipment Pickup ID

Example:

10954392

trackable

boolean

optional

Whether or not the shipment is trackable

Example:

true

tracking_link

string

optional

Shipment Tracking Link

Example:

https://semsa.com/tracking/order_url.com

label

object

optional

payment_method

enum<string>

optional

Shipment Payment Method

Allowed values:

codpre_paid

Example:

cod

source

string

optional

Shipment Source

Example:

dashboard

status

enum<string>

optional

Shipment Status

Allowed values:

createdin_progressdeliveringdeliveredshippedcancelled

Example:

in_progress

total

object

optional

cash_on_delivery

object

optional

is_international

boolean

optional

Whether the shipment is shipped internationally

Example:

true

total_weight

object

optional

packages

array [object {8}]

optional

ship_from

object

optional

ship_to

object

optional

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

event

enum<string>

optional

Event Name

Allowed values:

shipment.creatingshipment.createdshipment.updatedshipment.cancelled

merchant

number

optional

Merchant ID who installed the application on their store. Get details on the Merchant via the ID using the endpoint here

created_at

string

optional

Webhook Created At Date Timestamp

data

object

optional

number

optional

This field refers to a unique identifier for the shipment.

Example:

987654321

order_id

integer

optional

This field refers to the unique identifier for the order associated with the shipment.

Example:

123456789

order_reference_id

number | null

optional

This field refers to a reference ID that can be used to look up additional information about the order

created_at

object

optional

type

enum<string>

optional

Shipment Type

Allowed values:

returnshipment

Example:

shipment

courier_id

integer

optional

Shipment Courier ID. Find a complete list of Shipment companies here

Example:

1723506348

courier_name

string

optional

Shipment Courier Name

Example:

Semsa

courier_logo

string

optional

Shipment Courier Logo

Example:

https://semsa.com/assets/logo.png

shipping_number

string

optional

Shipment Shipping Number

Example:

192837465

tracking_number

string

optional

Shipment Tracking Number

Example:

918273645

pickup_id

null

optional

Shipment Pickup ID

Example:

10954392

trackable

boolean

optional

Whether or not the shipment is trackable

Example:

true

tracking_link

string

optional

Shipment Tracking Link

Example:

https://semsa.com/tracking/order_url.com

label

object

optional

payment_method

enum<string>

optional

Shipment Payment Method

Allowed values:

codpre_paid

Example:

cod

source

string

optional

Shipment Source

Example:

dashboard

status

enum<string>

optional

Shipment Status

Allowed values:

createdin_progressdeliveringdeliveredshippedcancelled

Example:

in_progress

total

object

optional

cash_on_delivery

object

optional

is_international

boolean

optional

Whether the shipment is shipped internationally

Example:

true

total_weight

object

optional

packages

array [object {8}]

optional

ship_from

object

optional

ship_to

object

optional

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