Create Shipment - Salla Merchants APIs

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

Scopes

shipping.read_write- Shipping Read & Write

curl --location --request POST 'https://api.salla.dev/admin/v2/shipments' \ --header 'Content-Type: application/json' \ --data-raw '{ "courier_id": 1927161457, "order_id": 54534523, "external_company_name": "Salla Express", "overwrite_exists_pending": true, "shipment_type": "shipment", "policy_options": { "boxes": 1 }, "payment_method": "pre_paid", "cash_on_delivery": { "amount": 10.7, "currency": "SAR" }, "ship_to": { "name": "Mohammed Khalid", "email": "[email protected]", "phone": "966501636784", "country_id": 1473353380, "city_id": 1473353380, "postal_code": "95128", "street_number": "2345", "block": "السلام", "address_line": "شارع عبدالله سنابل السلام مكة السعوديه", "geo_coordinates": { "lat": 21.3825905096851, "lng": 39.77319103068542 } }, "ship_from": { "type": "branch", "branch_id": 1987977866, "name": "الفرع الرئيسي", "email": "", "phone": "966501636784", "country": ["السعودية"], "country_id": 1473353380, "country_code": "SA", "city": ["Mecca"], "city_id": 1939592358, "address_line": "Mecca,السعودية", "street_number": "1234", "block": "block", "postal_code": "1234", "geo_coordinates":{ "latitude": [21.3825905096851], "longitude": [39.77319103068542] } }, "packages": [ { "item_id": 2077288690, "external_id": null, "name": " منتج تجريبي", "sku": "52743-145", "quantity": 1, "price": { "amount": 25.5, "currency": "SAR" }, "weight": { "value": 5, "units": "kg" } } ] }'

{ "status": 200, "success": true, "data": { "id": 362985662, "order_id": 560695738, "order_reference_id": 48927, "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", "external_company_name": "Salla Express", "shipping_number": "0", "tracking_number": "0", "pickup_id": 576756, "trackable": true, "tracking_link": "https://www.company/tracking/tracking-express.html?submit=1&tracking-id=12345", "label": [], "payment_method": "cod", "source": "api", "status": "creating", "total": { "amount": 100, "currency": "SAR" }, "cash_on_delivery": { "amount": "10.70", "currency": "SAR" }, "packages": [ { "item_id": 2077288690, "external_id": 123212, "name": "منتج تجريبي", "sku": "6ytrrhrhr", "price": { "amount": "50.00", "currency": "SAR" }, "quantity": 2, "weight": { "value": "1.00", "unit": "kg" }, "options": [] } ], "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 }, "meta": { "app_id": 12345643, "policy_options": { "types": "", "boxes": "1" } }, "billing_account": "salla" } }

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

courier_id

integer

required

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

Example:

1723506348

shipment_type

enum<string>

required

Shipment Type.

Allowed values:

returnshipment

Example:

shipment

shipment_id

integer

optional

The id of the shipment. Required if shipment_type = "return"

order_id

integer

optional

Order ID, list of orders can be found here.

Example:

28475601

external_company_name

string

optional

The name of the shipping company for shipments created via the API

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

policy_options

object

optional

The shipment policy options details.

boxes

integer

optional

Shipment Boxes

Example:

payment_method

enum<string>

required

Shipment Payment Method

Allowed values:

codpre_paid

Example:

cod

cash_on_delivery

object

optional

Required if payment_method is cod

amount

number

required

Shipment Cash On Delivery Amount. Value between 0 and 9999

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

ship_to

object

required

name

string

required

Shipment Ship To Name

Example:

username

string

required

Shipment Ship To Email

Example:

username@gmailcom

phone

string

required

Shipment Ship To Phone

>= 10 characters

Example:

0512345678

country_id

number

required

Shipment Ship To Country. Find a complete list of countries here.

city_id

number

required

Shipment Ship To CityFind a complete list of cities here.

address_line

string

required

Shipment Ship To Address Line

Example:

Tahlia Street

street_number

string

required

Shipment Ship To Street Number

Example:

120

block

string

required

Shipment Ship To Block

Example:

Block AB

postal_code

string

required

Shipment Ship To Postal Code

Example:

1000

geo_coordinates

object

required

ship_from

object

required

type

string

required

Shipment Ship From Type

Example:

address

branch_id

integer

optional

Shipment Ship From Branch ID

Example:

194309

name

string

optional

Shipment Ship From Name

Example:

Username

string

optional

Shipment Ship From Email

Example:

[email protected]

phone

string

optional

Shipment Ship From Phone

>= 10 characters

Example:

0512345678

country

array[string]

optional

Shipment Ship From Country

country_code

string

write-onlyoptional

Country code. required if country_id is not set

Example:

country_id

number

optional

Country ID. required if country_code is not set

city

array[string]

optional

Shipment Ship From City

city_id

number

optional

address_line

string

optional

Shipment Ship From Address Line

Example:

Mecca Street

street_number

string

optional

Shipment Ship From Street Number

block

string

optional

Shipment Ship From Block

postal_code

string

optional

Shipment Ship From Postal Code

geo_coordinates

object

optional

packages

array [object {5}]

required

Shipment package details.

name

string

optional

Shipment Packages Name

Example:

Package 1

sku

string

optional

Shipment Packages SKU

Example:

SKU-123-456

price

object

optional

quantity

integer

optional

Shipment Packages Quantity

Example:

weight

object

optional

Examples

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

created_at

object

required

Date and time of shipment creations.

type

enum<string>

required

Shipment type.

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

Shipment courier name.

Example:

Semsa

courier_logo

string

required

Shipment courier logo.

Example:

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

external_company_name

string

optional

The name of the shipping company for shipments created via the API.

shipping_number

string

required

Shipment shipping number.

Example:

192837465

tracking_number

string

required

Shipment tracking number

Example:

918273645

pickup_id

number

required

Shipment pickup unique identifier.

trackable

boolean

required

Whether or not the shipment is trackable.

Example:

true

tracking_link

string

required

Shipment tracking link

Example:

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

label

object

required

Shipment label details.

payment_method

enum<string>

required

Shipment payment method

Allowed values:

codpre_paid

Example:

cod

source

string

required

Shipment source.

Example:

dashboard

status

enum<string>

required

Shipment status.

Allowed values:

createdin_progressin_transitreceived_at_final_hubto_be_reattemptedreattemptedunable_to_deliverdeliveringdeliveredpartially_deliveredshippedcancelledlostdamagedreturn_to_originreturn_in_progress

Example:

in_progress

total

object

required

Shipment total.

cash_on_delivery

object

required

Shipment cash on delivery details.

is_international

boolean

required

Whether or not the shipment is shipped internationally

Example:

true

total_weight

object

required

Shipment total weight.

packages

array [object {8}]

required

Shipment packages details.

ship_from

object

required

Shipment source details.

ship_to

object

required

Shipment destination details.