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

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 (Urls)

required

To help companies and merchants, Salla provides a “urls” attribute that has been added to different modules to guide the merchants to have the full URL of this module from both scopes, the dashboard scope as a store admin, and as a customer.

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.

rating_link

string

deprecated

The rating URL to review the order.
🛑 The variable is to be deprecated; use data.urls.rating variable instead.

checkout_url

string

deprecated

The checkout URL to settle payments related to the order.
🛑 The variable is to be deprecated; use data.urls.checkout variable instead.

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

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:

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.

Order Fulfilment#

Order Placement#

Update Shipment Details#

Shipments Return and Cancellation#

Return Shipments#

Cancel Shipments#

Order Fulfilment

Order Placement

Update Shipment Details

Shipments Return and Cancellation

Return Shipments

Cancel Shipments