Create Shipment

This endpoint allows you to create a shipment related to your store directly from this endpoint.

The following variables are deprecated. Please update your implementation to use the recommended replacements:

ship_to

country_id → use the ship_to.country variable

city_id → use the ship_to.city variable

ship_from

country_id → use the ship_from.country variable

country_code → use the ship_from.country variable

city_id → use the ship_from.city variable

Scopes

shipping.read_write- Shipping Read & Write

Request

Authorization

Add the parameter

Authorization

to Headers，whose value is to concatenate the Token after the Bearer.

Example:

Authorization: Bearer ********************

Body Params application/json

overwrite_exists_pending

boolean

optional

Whether or not to allow the pending shipment, which was generated during the order creation, to be replace by the new shipment that is assigned by the Order Management App

Example:

true

courier_id

integer

required

Shipment Courier ID. List of Shipment companies can be found [here](api-5394239.

Example:

1723506348

order_id

integer

optional

The order ID that the shipment will be assigned, list of orders can be found here.

Example:

28475601

shipment_id

integer

optional

The unique identifier of the shipment. Required if shipment_type is set to 'return'.

shipment_type

enum<string>

required

Shipment Type.

Allowed values:

returnshipment

Example:

shipment

payment_method

enum<string>

required

Shipment Payment Method

Allowed values:

codpre_paid

Example:

cod

cash_on_delivery

object

optional

Cash on delivery details.

amount

number

required

Shipment Cash On Delivery Amount

Example:

200

currency

string

required

Shipment Cash On Delivery Currency. You may refer to the external Merchant API Docs of the List of Currencies here

Example:

SAR

description

string

optional

A brief summary or explanation of the contents or purpose of the shipment.

remarks

string

optional

Any additional notes, comments, or special delivery instructions related to the shipment.

external_id

string

optional

A unique identifier for the shipment provided by the external shipping company, used for cross-system reference.

external_additional_id

string

optional

An alternate or supplementary identifier for the shipment, used for additional tracking or internal references.

external_company_name

string

optional

The name of the external shipping company used for shipments created via the API, if different from the standard courier list.

service_types

array[string]

optional

A list of service types requested for the shipment, Example: domestic,international,normal, fulfillment,heavy,express,cash_on_delivery,cold

policy_options

object

optional

Custom shipment policy details. Each key represents a policy option (e.g. number_of_boxes, shipment_content_type), and the value is a string. This allows flexibility for any store-defined policy.

ship_to

object

optional

Detailed information about the recipient or destination location of the shipment, including contact details and address.

name

string

required

The name of the recipient or destination contact person for the shipment.

Example:

username

string

required

The email address of the recipient or destination contact.

Example:

username@gmailcom

phone

string

required

The phone number of the recipient or destination contact.

Example:

555-555-555

country

string

required

The country to which the shipment is being sent. Use the country code or ID as specified in the country list here.

city

string

required

The city to which the shipment is being sent. Use the city name or ID as specified in the city list here.

address_line

string

required

The street address or location details for the shipment's destination.

Example:

Tahlia Street

street_number

string

required

The street number for the shipment's destination address.

Example:

120

block

string

required

The block or building identifier for the shipment's destination address.

Example:

Block AB

postal_code

string

required

The postal or ZIP code for the shipment's destination address.

Example:

1000

country_id

string

deprecated

Country ID.

This is a deprecated variable. Instead, use the ship_to.country variable.

city_id

string

deprecated

City ID.

This is a deprecated variable. Instead, use the ship_to.city variable.

geo_coordinates

object

optional

Geographical coordinates (latitude and longitude) for the shipment's destination address.

ship_from

object

optional

Detailed information about the sender or origin location of the shipment, including contact details and address.

type

enum<string>

required

Specifies the type of origin for the shipment, such as an address or branch location.

Allowed values:

addressbranch

Default:

branch

branch_id

integer

optional

The unique identifier for the branch or facility from which the shipment is sent, required when the type is 'branch'.

Example:

194309

name

string

optional

The name of the sender or origin contact person for the shipment.

Example:

Username

string

optional

The email address of the sender or origin contact.

Example:

username@gmail.com

phone

string

optional

The phone number of the sender or origin contact.

Example:

555-555-555

country

string

optional

The country from which the shipment is being sent. Use the country code or ID as specified in the country list here.

Example:

Saudi Arabia

city

string

optional

The city from which the shipment is being sent. Use the city name or ID as specified in the city list here.

Example:

Mecca

address_line

string

optional

The street address or location details for the shipment's origin.

Example:

Mecca Street

street_number

string

optional

The street number for the shipment's origin address.

block

string

optional

The block or building identifier for the shipment's origin address.

postal_code

string

optional

The postal or ZIP code for the shipment's origin address.

country_id

string

deprecated

Country ID.

This is a deprecated variable. Instead, use the ship_from.country variable.

city_id

string

deprecated

City ID.

This is a deprecated variable. Instead, use the ship_from.city variable.

geo_coordinates

object

optional

Geographical coordinates (latitude and longitude) for the shipment's origin address.

packages

array [object {6}]

required

A list of packages included in the shipment, each containing detailed information about the items, quantities, weights, and options.

external_id

string

optional

An external identifier for the item, which may be used by third-party systems or integrations.

name

string

optional

The name or title of the item contained in the package.

Example:

Package 1

sku

string

optional

The Stock Keeping Unit (SKU) code assigned to the item for inventory management.

Example:

SKU-123-456

price

object

optional

Details about the price of the item, including amount and currency.

quantity

integer

optional

The number of units of the item included in the package.

Example:

weight

object

optional

Details about the weight of the item, including value and units.

Example

{
    "overwrite_exists_pending": true,
    "courier_id": 1927161457,
    "order_id": 54534523,
    "shipment_type": "shipment",
    "payment_method": "pre_paid",
    "cash_on_delivery": {
        "amount": 10.7,
        "currency": "SAR"
    },
    "description": "Fashion Apparel - 3 T-Shirts",
    "remarks": "Customer requested delivery after 5 PM",
    "external_id": "34567898",
    "external_additional_id": "OM656545543",
    "external_company_name": "Salla Express",
    "service_types": [
        "international",
        "normal",
        "fulfillment"
    ],
    "policy_options": {
        "boxes": 1
    },
    "ship_to": {
        "name": "Mohammed Khalid",
        "email": "test@gmail.com",
        "phone": "966501636784",
        "country": 1473353380,
        "city": 1473353380,
        "postal_code": "95128",
        "street_number": "2345",
        "block": "السلام",
        "address_line": "شارع عبدالله  سنابل السلام  مكة  السعوديه",
        "geo_coordinates": {
            "lat": 21.3825905096851,
            "lng": 39.77319103068542
        }
    },
    "ship_from": {
        "type": "address",
        "name": "الفرع الرئيسي",
        "email": "",
        "phone": "966501636784",
        "country": 1473353380,
        "city": 1939592358,
        "address_line": "Mecca,السعودية",
        "street_number": "1234",
        "block": "block",
        "postal_code": "1234",
        "geo_coordinates": {
            "latitude": [
                21.3825905096851
            ],
            "longitude": [
                39.77319103068542
            ]
        }
    },
    "packages": [
        {
            "external_id": null,
            "name": "منتج تجريبي",
            "sku": "52743-145",
            "quantity": 1,
            "price": {
                "amount": 25.5,
                "currency": "SAR"
            },
            "weight": {
                "value": 5,
                "units": "kg"
            }
        }
    ]
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://api.salla.dev/admin/v2/shipments' \
--header 'Content-Type: application/json' \
--data-raw '{
    "overwrite_exists_pending": true,
    "courier_id": 1927161457,
    "order_id": 54534523,
    "shipment_type": "shipment",
    "payment_method": "pre_paid",
    "cash_on_delivery": {
        "amount": 10.7,
        "currency": "SAR"
    },
    "description": "Fashion Apparel - 3 T-Shirts",
    "remarks": "Customer requested delivery after 5 PM",
    "external_id": "34567898",
    "external_additional_id": "OM656545543",
    "external_company_name": "Salla Express",
    "service_types": [
        "international",
        "normal",
        "fulfillment"
    ],
    "policy_options": {
        "boxes": 1
    },
    "ship_to": {
        "name": "Mohammed Khalid",
        "email": "test@gmail.com",
        "phone": "966501636784",
        "country": 1473353380,
        "city": 1473353380,
        "postal_code": "95128",
        "street_number": "2345",
        "block": "السلام",
        "address_line": "شارع عبدالله  سنابل السلام  مكة  السعوديه",
        "geo_coordinates": {
            "lat": 21.3825905096851,
            "lng": 39.77319103068542
        }
    },
    "ship_from": {
        "type": "address",
        "name": "الفرع الرئيسي",
        "email": "",
        "phone": "966501636784",
        "country": 1473353380,
        "city": 1939592358,
        "address_line": "Mecca,السعودية",
        "street_number": "1234",
        "block": "block",
        "postal_code": "1234",
        "geo_coordinates": {
            "latitude": [
                21.3825905096851
            ],
            "longitude": [
                39.77319103068542
            ]
        }
    },
    "packages": [
        {
            "external_id": null,
            "name": "منتج تجريبي",
            "sku": "52743-145",
            "quantity": 1,
            "price": {
                "amount": 25.5,
                "currency": "SAR"
            },
            "weight": {
                "value": 5,
                "units": "kg"
            }
        }
    ]
}'

Responses

🟢200Success

application/json

Body

status

number

optional

Response status code, a numeric or alphanumeric identifier used to convey the outcome or status of a request, operation, or transaction in various systems and applications, typically indicating whether the action was successful, encountered an error, or resulted in a specific condition.

success

boolean

optional

Response flag, boolean indicator used to signal a particular condition or state in the response of a system or application, often representing the presence or absence of certain conditions or outcomes.

data

object (Shipment)

optional

number

required

A unique identifier for the shipment. Shipment list can be found here.

Example:

987654321

order_id

number

required

A unique identifier for the order associated with the shipment. List of orders can be found here

Example:

123456789

order_reference_id

number | null

required

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

reference

object

required

created_at

object

required

Date and time of shipment creations.

type

enum<string>

required

Specifies the nature of the shipment, indicating whether it is an outgoing delivery to a customer ("shipment") or a return shipment sent back to the merchant ("return").

Allowed values:

returnshipment

Example:

shipment

courier_id

integer

required

Shipment courier identification. Find a complete list of Shipment companies here

Example:

1723506348

courier_name

string

required

The full name of the courier or shipping company responsible for transporting and delivering the shipment to its destination.

Example:

Semsa

courier_logo

string

required

A URL pointing to the official logo image of the courier or shipping company, which can be used for display in user interfaces or documentation.

Example:

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

external_company_name

string

optional

The name of the external shipping company used for shipments created via the API, if different from the standard courier list.

shipping_number

string

required

The unique shipping number assigned to the shipment by the courier, used for internal tracking and reference within the courier's system.

Example:

192837465

tracking_number

string

required

The unique tracking number provided by the courier, allowing customers and merchants to track the shipment's delivery status online.

Example:

918273645

pickup_id

number

required

A unique identifier for the shipment's pickup event, used to reference and manage the pickup process with the courier or logistics provider.

trackable

boolean

required

Indicates whether the shipment can be tracked online using a tracking number or link provided by the courier.

Example:

true

tracking_link

string

required

A direct URL to the courier's online tracking page for this shipment, allowing real-time status updates and location information.

Example:

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

label

object

required

Detailed information about the shipment label, including its file format and a link to access the label.

payment_method

enum<string>

required

Specifies the payment method used for the shipment, such as cash on delivery (cod) or pre-paid, determining how the shipping cost is settled.

Allowed values:

codpre_paid

Example:

cod

source

string

required

Indicates the origin of the shipment request, such as the dashboard, API, or other system sources.

Example:

dashboard

status

enum<string>

required

Current status of the shipment in the delivery process, such as created, in_progress, delivered, cancelled, etc.

Allowed values:

createdin_progressin_transitreceived_at_final_hubto_be_reattemptedreattemptedunable_to_deliverdeliveringdeliveredpartially_deliveredshippedcancelledlostdamagedreturn_to_originreturn_in_progress

Example:

in_progress

total

object

required

Details about the total value and currency of the shipment.

cash_on_delivery

object

required

Details about the cash on delivery amount and its currency.

is_international

boolean

required

Indicates whether the shipment is being sent to a destination outside the origin country (international shipping).

Example:

true

total_weight

object

required

Information about the total weight of the shipment and its measurement units.

billing_account

enum<string>

required

Indicates which billing account is used for the shipment charges, such as the merchant's own account or a platform account (e.g., Salla).

Allowed values:

sallamerchant

description

string

optional

A brief summary or explanation of the contents or purpose of the shipment.

remarks

string

optional

Any additional notes, comments, or special delivery instructions related to the shipment.

service_types

array[string]

required

A list of service types requested for the shipment, Example: domestic,international,normal, fulfillment,heavy,express,cash_on_delivery,cold

packages

array [object {8}]

required

A list of packages included in the shipment, each containing detailed information about the items, quantities, weights, and options.

ship_from

object

required

Detailed information about the sender or origin location of the shipment, including contact details and address.

ship_to

object

required

Detailed information about the recipient or destination location of the shipment, including contact details and address.

ship_to#

ship_from#

Request

Request samples

Responses

ship_to

ship_from