Salla Docs
App Cycle
Salla Order Fulfilment is a powerful workflow used by Merchants to streamline their orders' processing. It manages the entire order-to-delivery from the time an order is placed until it has been fulfilled, returned, or canceled.
:::tip[Note]
Salla Shipping API supports assigning an order to multiple shipping Apps, providing accurate information about the order to the Shipping Apps ,and managing the order flow.
:::
In this article, we will explore the following topics:
- Order Fulfilment
- Shipments Return and Cancellation
Order Fulfilment
The following diagram explains two main workflows, which are receiving orders from customers, and then assigning those orders to multiple shipping Apps based on either custom Merchant preferences, the closest shipping service to the customer, and the least shipping cost for the Merchant.
Moreover, the Order Fulfilment App can handle order shipping cancellations and returns from the customer.
sequenceDiagram
actor c as Customer
participant m as Salla Merchant
participant o as Order Fulfilment App
participant a as Shipping App
c->>m: Order Placed
Note right of c: new order
m->>o: Dispatch order.created Webhook
Note over o: Fetch merchant's <br/> active shipping companies. <br/> GET /shipping/companies/
o->>o: Assign and generate shipment(s)
o->>m: Send shipments detailes vis API
Note right of m: (POST /shipments) <br/> {shipment.status:"creating"}
m->>a: Dispatch shipment.creating Webhook
a->>a: Generate Shipment
a->>m: Provide Shipment Details via API
Note right of o: PUT /shipments/{shipment_id} <br/> {tracking_link, shipment_number, tracking_number ..}
m->>o: Dispatch shipment.created Webhook
Order Placement
The first step in the Order Fulfilment Cycle is when an order is placed/created, and this happens:
- After checkout is fully processed and done from the Customer's side of the Merchant's store.
- Via the Create Order API Endpoint.
The store webhook, order.created, will be triggered and sent over to the Order Fulfilment App, with shipment status being pending. That sent data can then be processed to assign the orders to multi-shipping Apps.
At this step, the Order Fulfilment App has all the required information received from the order.created webhook event and is now able to process the splitting of orders to the shipping Apps. The following payload is correspondent to when the order.created event is fired.
The Order Fulfilment App has to consume the List Shipping Apps API Endpoint to know which shipping Apps have been enabled by the Merchant on the store, so that the assigning of the orders can be handled smoothly.
The Order Fulfilment App will then now be able to assign a shipment to the order using the Create Shipment API endpoint.
The following enlists the values that are sent to the endpoint to do so:
When the endpoint is consumed successfully, the developer is expected to receive the following payload payload.
{
"status": 200,
"success": true,
"data": {
"id": 1139865338,
"order_id": 1915190521,
"created_at": {
"date": "2023-01-12 14:19:08.000000",
"timezone_type": 3,
"timezone": "Asia/Riyadh"
},
"type": "shipment",
"courier_id": 814202285,
"courier_name": "DHL",
"courier_logo": "https://company.com/logo.png",
"shipping_number": "0",
"tracking_number": "0",
"pickup_id": null,
"trackable": true,
"tracking_link": "https://www.logistics.dhl/us-en/home/tracking/tracking-express.html?submit=1&tracking-id=0",
"label": [],
"payment_method": "cod",
"source": "api",
"status": "creating",
"total": {
"amount": 100,
"currency": "SAR"
},
"cash_on_delivery": {
"amount": "10.70",
"currency": "SAR"
},
"meta": {
"app_id": null,
"policy_options": {
"types": "",
"boxes": "1"
}
},
"ship_from": {
"type": "branch",
"name": "Riyadh",
"email": "",
"phone": "0555555555",
"country": "السعودية",
"city": "RIYADH",
"address_line": "7687 طريق الملك فهد الفرعي,الملك فهد,12262, 7687 طريق الملك فهد الفرعي، الملك فهد، الرياض 12262 3010، السعودية, RIYADH,السعودية",
"street_number": "7687 طريق الملك فهد الفرعي",
"block": "الملك فهد",
"postal_code": "12262",
"latitude": 24.7431373,
"longitude": 46.6570741,
"branch_id": 1723506348
},
"ship_to": {
"type": "address",
"name": "Username",
"email": "[email protected]",
"phone": "055-555-555",
"country": "السعودية",
"city": "الرياض",
"address_line": " شارع 2345، الحي السلام 95128،, شارع عبدالله سنابل السلام مكة السعوديه,, الرياض, السعودية",
"street_number": "2345",
"block": "السلام",
"postal_code": "95128",
"latitude": 21.382590509685,
"longitude": 39.773191030685
},
"packages": [
{
"name": "منتج تجريبي",
"sku": "6ytrrhrhr",
"price": {
"amount": "50.00",
"currency": "SAR"
},
"quantity": 2,
"weight": {
"value": "1.00",
"unit": "kg"
}
}
]
}
}
Update Shipment Details
Understanding the process of the Shipping App Cycle is vital for the Order Fulfilment App, which adds a layer of smooth integration and communication between both services.
:::info[Information]
Checkout the Shipping App Cycle guide for more details on the workflow.
:::
The store webhook, shipment.creating, will be triggered and sent to the Shipping App. The Shipping App will 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, so the Merchant will be able to download the shipment policy.
Accordingly, after creating the shipment by the Shipping App, the Merchant store will receive the updates, and the store webhook, shipment.created will be triggered at that moment to update the shipment status for the Order Fulfillment App.
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.
{
"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": "[email protected]",
"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"
}
}
]
}
}
Shipments Return and Cancellation
Return Shipments
The following diagram details the return process, which can be triggered by the Order Fulfilment App on behalf of the Merchant to the Shipping App
sequenceDiagram
participant o as Order Fulfilment App
participant m as Salla Merchant
participant a as Shipping App
opt
o-->>m: POST shipments/{shipment_id}/return
Note right of o: return a delivered shipment
m-->>a: Dispatch shipment.creating{type:"return"} Webhook
a->>a: internal process
end
The Order Fulfilment can initiate a return on delivered shipment by consuming the Return Shipments API Endpoint by sending the shipment_id as a path parameter in this manner https://api.salla.dev/admin/v2/shipments/{shipment_id}/return, which such request will then be sent to the Shipping Apps for them to handle the returning process.
When the endpoint is consumed successfully, the developer is expected to receive the following payload.
{
"status": 200,
"success": true,
"data": {
"id": 1139865338,
"order_id": 1915190521,
"created_at": {
"date": "2023-01-12 14:19:08.000000",
"timezone_type": 3,
"timezone": "Asia/Riyadh"
},
"type": "shipment",
"courier_id": 814202285,
"courier_name": "DHL",
"courier_logo": "https://company.com/logo.png",
"shipping_number": "0",
"tracking_number": "0",
"pickup_id": null,
"trackable": true,
"tracking_link": "https://www.logistics.dhl/us-en/home/tracking/tracking-express.html?submit=1&tracking-id=0",
"label": [],
"payment_method": "cod",
"source": "api",
"status": "creating",
"total": {
"amount": 100,
"currency": "SAR"
},
"cash_on_delivery": {
"amount": "10.70",
"currency": "SAR"
},
"meta": {
"app_id": null,
"policy_options": {
"types": "",
"boxes": "1"
}
},
"ship_from": {
"type": "branch",
"name": "Riyadh",
"email": "",
"phone": "0555555555",
"country": "السعودية",
"city": "RIYADH",
"address_line": "7687 طريق الملك فهد الفرعي,الملك فهد,12262, 7687 طريق الملك فهد الفرعي، الملك فهد، الرياض 12262 3010، السعودية, RIYADH,السعودية",
"street_number": "7687 طريق الملك فهد الفرعي",
"block": "الملك فهد",
"postal_code": "12262",
"latitude": 24.7431373,
"longitude": 46.6570741,
"branch_id": 1723506348
},
"ship_to": {
"type": "address",
"name": "Username",
"email": "[email protected]",
"phone": "055-555-555",
"country": "السعودية",
"city": "الرياض",
"address_line": " شارع 2345، الحي السلام 95128،, شارع عبدالله سنابل السلام مكة السعوديه,, الرياض, السعودية",
"street_number": "2345",
"block": "السلام",
"postal_code": "95128",
"latitude": 21.382590509685,
"longitude": 39.773191030685
},
"packages": [
{
"name": "منتج تجريبي",
"sku": "6ytrrhrhr",
"price": {
"amount": "50.00",
"currency": "SAR"
},
"quantity": 2,
"weight": {
"value": "1.00",
"unit": "kg"
}
}
]
}
}
Cancel Shipments
The following diagram details the cancellation process, which can be triggered by the Order Fulfilment App on behalf of the Merchant to the Shipping App
sequenceDiagram
participant o as Order Fulfilment App
participant m as Salla Merchant
participant a as Shipping App
opt
o-->>m: POST shipments/{shipment_id}/cancel
Note right of o: cancel shipment
m-->>a: Dispatch shipment.cancelled Webhook
a->>a: internal process
end
The Order Fulfilment App is able to cancel any shipment by consuming the Cancel Shipments API Endpoint by sending the shipment_id as a path parameter in this manner https://api.salla.dev/admin/v2/shipments/{shipment_id}/cancel, which the Shipping App will receive to handle the proper action for that.
When the endpoint is consumed successfully, the developer is expected to receive the following payload.
{
"status": 200,
"success": true,
"data": {
"id": 1139865338,
"order_id": 1915190521,
"created_at": {
"date": "2023-01-12 14:19:08.000000",
"timezone_type": 3,
"timezone": "Asia/Riyadh"
},
"type": "shipment",
"courier_id": 814202285,
"courier_name": "DHL",
"courier_logo": "https://company.com/logo.png",
"shipping_number": "0",
"tracking_number": "0",
"pickup_id": null,
"trackable": true,
"tracking_link": "https://www.logistics.dhl/us-en/home/tracking/tracking-express.html?submit=1&tracking-id=0",
"label": [],
"payment_method": "cod",
"source": "api",
"status": "creating",
"total": {
"amount": 100,
"currency": "SAR"
},
"cash_on_delivery": {
"amount": "10.70",
"currency": "SAR"
},
"meta": {
"app_id": null,
"policy_options": {
"types": "",
"boxes": "1"
}
},
"ship_from": {
"type": "branch",
"name": "Riyadh",
"email": "",
"phone": "0555555555",
"country": "السعودية",
"city": "RIYADH",
"address_line": "7687 طريق الملك فهد الفرعي,الملك فهد,12262, 7687 طريق الملك فهد الفرعي، الملك فهد، الرياض 12262 3010، السعودية, RIYADH,السعودية",
"street_number": "7687 طريق الملك فهد الفرعي",
"block": "الملك فهد",
"postal_code": "12262",
"latitude": 24.7431373,
"longitude": 46.6570741,
"branch_id": 1723506348
},
"ship_to": {
"type": "address",
"name": "Username",
"email": "[email protected]",
"phone": "055-555-555",
"country": "السعودية",
"city": "الرياض",
"address_line": " شارع 2345، الحي السلام 95128،, شارع عبدالله سنابل السلام مكة السعوديه,, الرياض, السعودية",
"street_number": "2345",
"block": "السلام",
"postal_code": "95128",
"latitude": 21.382590509685,
"longitude": 39.773191030685
},
"packages": [
{
"name": "منتج تجريبي",
"sku": "6ytrrhrhr",
"price": {
"amount": "50.00",
"currency": "SAR"
},
"quantity": 2,
"weight": {
"value": "1.00",
"unit": "kg"
}
}
]
}
}
🎉 Reaching here means you have a full idea of how Order Fulfilment Apps functions and you can proceed to Set Up your Orders Fulfilment App.