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

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

shipment_id

integer | null

optional

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

courier_id

integer

required

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

Example:

1723506348

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

shipment_type

enum<string>

required

Shipment Type.

Allowed values:

returnshipment

Example:

shipment

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

Example

{
  "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"
      }
    }
  ]
}

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 '{
    "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"
            }
        }
    ]
}'

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:

creatingcreatedpendingdeliveredreturnedin_progresscancelleddelivering

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.

meta

object

required

"Metadata" is data that describes other data, providing details on its creation, format, and context.

billing_account

enum<string>

required

The type of the company billing account

Allowed values:

sallamerchant

Example

{
  "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"
  }
}

🟠422Error Validation