Salla Docs
Merchant API
  • Merchant API
  • Salla OAuth 2.0
Partner APIs
  • App API
  • Shipment API
Storefront
  • Twilight Engine
  • Twilight SDK
  • Web Components
  • Change Log
Salla CLI
Merchant API
  • Merchant API
  • Salla OAuth 2.0
Partner APIs
  • App API
  • Shipment API
Storefront
  • Twilight Engine
  • Twilight SDK
  • Web Components
  • Change Log
Salla CLI
Salla - Opensource
Salla - Developers Community
  1. Order Fulfilment
  • Publish App
  • Change Log
  • Getting Started
  • Migration to the New API
  • Shipping Management
    • Create App
    • App Cycle
    • Setup App
    • Test App
  • Order Fulfilment
    • Create App
    • App Cycle
    • Setup App
    • Test App
  • Shipments
    • Create Shipment
      POST
    • List Shipments
      GET
    • Update Shipment Details
      PUT
    • Shipment Details
      GET
    • Cancel Shipments
      POST
    • Return Shipments
      POST
    • Shipment Tracking
      GET
  • Shipping Companies
    • List Shipping Companies
      GET
    • Shipping Company Details
      GET
  1. Order Fulfilment

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.
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
Order Placement
Assign Shipments
Update Shipment Details
Shipments Return and Cancellation
Return Shipments
Cancel Shipments

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. 

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.
Webhook Payload order.created
List Shipping Apps Endpoint
Assign Shipments Body Request
Assign Shipments Response
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.
Payload
Response
Orders Webhook Events Model
event
enum<string> 
optional
Event Name
Allowed values:
order.createdorder.updatedorder.refundedorder.deletedorder.products.updatedorder.payment.updatedorder.coupon.updatedorder.total.price.updatedorder.shipping.address.updatedorder.cancelledorder.customer.updated
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
Timestamp of webhook creation
data
object 
optional
id
number 
required
A unique alphanumeric code or identifier assigned to a specific order. List of orders can be found here
cart_reference_id
number 
required
A unique alphanumeric code or identifier assigned to a specific order cart.
reference_id
number 
required
A specific alphanumeric identifier associated with an order.
urls
object 
required
date
object (Date) 
required
Date and Time of the order.
updated_at
object (Date) 
required
source
enum<string> 
required
The source of the order.
Allowed values:
storelandingforgotten_basketabandoned-cartcampaigndashboardbuy_as_giftmahly-appbuy_nowone-clickcomplete_order
draft
boolean 
required
Whether or not the order 's status is set to draft
read
boolean 
required
Whether or not the Merchant has read the order
source_device
string 
required
The machine or device used when the customer placed the order.
source_details
object 
required
Order source details.
status
object (NewOrderStatus) 
required
Order status.
is_price_quote
boolean 
required
The option to quote order price.
payment_method
string 
required
The specific payment option or financial mechanism chosen and used by a customer to pay for a product or service as part of an order, encompassing various methods.
receipt_image
string 
required
Order's image receipt
currency
string 
required
The currency in which order costs and prices are expressed and processed, based on the customer's preferences or the business's operational currency.
amounts
object 
required
Order amounts.
exchange_rate
object 
required
The order exchange rate.
can_cancel
boolean 
required
The option to enable order cancellation by the store customer.
True value should be set if the order status is in under review and in progress, as according to the store settings.
show_weight
boolean 
required
Whether or not to show the weight value.
can_reorder
boolean 
required
Whether or not to enable reorder .
is_pending_payment
boolean 
required
The option of displaying order is pending payment to the customer when the order status is payment_pending.
pending_payment_ends_at
integer 
required
Last date allowed to customer to pay the order.
total_weight
string 
required
Total weight value
shipping
object 
required
Order Shipping details.
shipments
array [object {22}] 
required
Order shipment details.
pickup_branch
object (Branch) 
required
Order pickup branch details.
shipment_branch
object (ShipmentBranch) 
required
Order shipment branch details.
customer
object (Customer) 
required
Customer details.
items
array [object {16}] 
required
bank
object 
required
tags
object (OrderTag) 
required
Order Tag details.
store
object 
required
Order store details.

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.
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.
Update Shipment Request Body
Update Shipment Response Body
The following enlists the values that can be sent to the endpoint to update the details of the shipment
put_shipmentDetails_request_body
tracking_link
string 
optional
A URL that provides a link to the tracking information for the shipment.
Example:
https://xyz-shipping.com/v1/labels/498498496/track
shipment_number
string 
required
A unique identifier for the shipment that distinguishes it from other shipments.
Example:
846984645
tracking_number
string 
optional
A unique identifier for the tracking information associated with the shipment.
Example:
54563653
status
enum<string> 
required
The current status of the shipment.
Effective January 20th, 2025, the status variable will be a required field in the request payload.
Allowed values:
createdin_progressdeliveringdeliveredshippedcancelled
Example:
delivered
status_note
string 
optional
The note field provides additional shipment information relevant factors, as it is used to clarify the shipment status and provide context.
Example:
Parcel has been picked up by our logistics partner
pdf_label
string 
optional
A PDF label that contains information about the shipment, such as the sender's and recipient's address, tracking number, and other relevant details.
Example:
https://xyz-shipping/v1/downloads/10/F91fByOB-0aJJadf7JLeww/label-63563751.pdf
cost
integer 
optional
The actual cost of the shipment that the Merchant will be charged for, which is calculated per the shipping company's actual costs. Ensure to include VAT in the cost.
Example:
40
external_company_name
string 
optional
The name of the shipping company for shipments created via the API

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
Return Shipments Request
Return Shipments Response
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.

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
Cancel Shipments Request
Cancel Shipments Response
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.

🎉

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.

Modified at 2025-01-05 10:22:13
Previous
Create App
Next
Setup App