List Shipments - Salla Merchants APIs

You can list all shipments related to your store directly from this endpoint. Also, it allows you to filter them using by shipping company slug.

Scopes

shipping.read- Shipping Read Only

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Query Params

order_id

integer

optional

Order ID. Get a list of Order IDs from here

Example:

1743861419

courier_id

integer

optional

Courier ID. Get a list of Courier IDs from here

Example:

1723506348

courier_slug

string

optional

Courier Slug. Get a list of Courier Slugs from here

Example:

smsa

status

string

optional

Shipment Status; value can be one of the listed enum variables

Example:

delivered

shipment_type

string

optional

Shipment Type; value can either "shipment" or "return"

Example:

shipment

payment_method

string

optional

Payment Method; value can either "pre_paid" or "cod"

Example:

pre_paid

from_date

string

optional

Shipment starting date range

Example:

2024-11-29

to_date

string

optional

Shipment ending date range

Example:

2024-12-29

ship_to[country_id]

integer

optional

Shipment Country Destination. Get a list of Country IDs from here

Example:

1473353380

ship_to[country_code]

string

optional

Shipment Country Code Destination. Get a list of Country Codes from here

Example:

ship_to[city_id]

integer

optional

Shipment City Destination. Get a list of City IDs from here

Example:

566146469

ship_from[country_id]

integer

optional

Shipment Country Origin. Get a list of Country IDs from here

Example:

1473353380

ship_from[country_code]

string

optional

Shipment Country Code Origin. Get a list of Country Codes from here

Example:

ship_from[city_id]

integer

optional

Shipment City Origin. Get a list of City IDs from here

Example:

566146469

source

string

optional

Shipment Source; value can be one of the listed enum variables

Example:

api

per_page

integer

optional

Shipments limit per page

Example:

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200Success

application/json

Body

This schema describes a model for a shipment response, including details about shipments made by a courier service, their associated orders, and shipment properties like ID, type, courier, tracking info, payment method, source, and status, as well as package details like name, SKU, price, quantity, and weight. Other info, such as creation date, currency, and trackability, is also included in the response, returned as **an array of objects** for use in a RESTful API for querying shipment data.

status

string

optional

Response Status Code

Example:

200

success

boolean

optional

Whether or not the response was successful

Example:

true

data

array [object {27}]

optional

number

optional

This field refers to a unique identifier for the shipment.

Example:

987654321

order_id

number

optional

This field refers to the unique identifier for the order associated with the shipment.

Example:

123456789

order_reference_id

number | null

optional

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

created_at

object

optional

type

enum<string>

optional

Shipment Type

Allowed values:

returnshipment

Example:

shipment

courier_id

integer

optional

Shipment Courier ID. Find a complete list of Shipment companies here

Example:

1723506348

courier_name

string

optional

Shipment Courier Name

Example:

Semsa

courier_logo

string

optional

Shipment Courier Logo

Example:

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

shipping_number

string

optional

Shipment Shipping Number

Example:

192837465

tracking_number

string

optional

Shipment Tracking Number

Example:

918273645

pickup_id

null

optional

Shipment Pickup ID

Example:

10954392

trackable

boolean

optional

Whether or not the shipment is trackable

Example:

true

tracking_link

string

optional

Shipment Tracking Link

Example:

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

label

object

optional

payment_method

enum<string>

optional

Shipment Payment Method

Allowed values:

codpre_paid

Example:

cod

source

string

optional

Shipment Source

Example:

dashboard

status

enum<string>

optional

Shipment Status

Allowed values:

creatingcreatedpendingdeliveredreturnedin_progresscancelleddelivering

Example:

in_progress

total

object

optional

cash_on_delivery

object

optional

is_international

boolean

optional

Whether the shipment is shipped internationally

Example:

true

total_weight

object

optional

packages

array [object {7}]

optional

ship_from

object

optional

ship_to

object

optional

meta

object

optional

billing_account

enum<string>

optional

The type of the company billing account

Allowed values:

sallamerchant

pagination

object

optional

Example

{
  "status": 200,
  "success": true,
  "data": [
    {
      "id": 362985662,
      "order_id": 560695738,
      "order_reference_id": 48927,
      "created_at": {
        "date": "2023-01-18 09:35:03.000000",
        "timezone_type": 3,
        "timezone": "Asia/Riyadh"
      },
      "type": "return",
      "courier_id": 814202285,
      "courier_name": "DHL",
      "courier_logo": "https://company.com/logo.png",
      "shipping_number": "0",
      "tracking_number": "0",
      "pickup_id": null,
      "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": 0,
        "currency": "SAR"
      },
      "cash_on_delivery": {
        "amount": "10.70",
        "currency": "SAR"
      },
      "meta": {
        "app_id": null,
        "policy_options": []
      },
      "ship_from": {
        "type": "address",
        "name": "Username",
        "email": "[email protected]",
        "phone": "055-555-555",
        "country_id": 1939592358,
        "country_code": "KW",
        "city": "ABBASIYA",
        "city_id": 1313869267,
        "address_line": "2345,السلام,95128, شارع عبدالله  سنابل السلام  مكة  السعوديه, RIYADH,السعودية",
        "street_number": "2345",
        "block": "السلام",
        "postal_code": "95128",
        "latitude": 21.382590509685,
        "longitude": 39.773191030685
      },
      "ship_to": {
        "type": "branch",
        "name": "Riyadh",
        "email": "",
        "phone": "0555555555",
        "country_id": 1939592358,
        "country_code": "KW",
        "city": "ABBASIYA",
        "city_id": 1313869267,
        "address_line": "7687 طريق الملك فهد الفرعي,الملك فهد,12262, 7687 طريق الملك فهد الفرعي، الملك فهد، الرياض 12262 3010، السعودية, الرياض,السعودية",
        "street_number": "7687 طريق الملك فهد الفرعي",
        "block": "الملك فهد",
        "postal_code": "12262",
        "latitude": 24.7431373,
        "longitude": 46.6570741,
        "branch_id": 1723506348
      },
      "packages": [],
      "billing_account": "salla"
    },
    {
      "id": 362985663,
      "order_id": 560695739,
      "order_reference_id": 48928,
      "created_at": {
        "date": "2023-01-16 23:37:59.000000",
        "timezone_type": 3,
        "timezone": "Asia/Riyadh"
      },
      "type": "return",
      "courier_id": 814202285,
      "courier_name": "DHL",
      "courier_logo": "https://company.com/logo.png",
      "shipping_number": "23424234354434",
      "tracking_number": "23424234354434",
      "pickup_id": null,
      "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"
      },
      "meta": {
        "app_id": null,
        "policy_options": []
      },
      "ship_from": {
        "type": "branch",
        "name": "Riyadh",
        "email": "",
        "phone": "0555555555",
        "country": "السعودية",
        "country_id": 1939592358,
        "country_code": "KW",
        "city": "ABBASIYA",
        "city_id": 1313869267,
        "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": "السعودية",
        "country_id": 1939592358,
        "country_code": "KW",
        "city": "ABBASIYA",
        "city_id": 1313869267,
        "address_line": " شارع 2345، الحي السلام 95128،, شارع عبدالله  سنابل السلام  مكة  السعوديه,, الرياض, السعودية",
        "street_number": "2345",
        "block": "السلام",
        "postal_code": "95128",
        "latitude": 21.382590509685,
        "longitude": 39.773191030685
      },
      "packages": [
        {
          "name": "منتج تجريبي",
          "sku": "6ytrrhrhr",
          "price": {
            "amount": "50.00",
            "currency": "SAR"
          },
          "quantity": 2,
          "weight": {
            "value": "1.00",
            "unit": "kg"
          }
        }
      ],
      "billing_account": "salla"
    },
    {
      "id": 362985660,
      "order_id": 560695732,
      "order_reference_id": 48922,
      "created_at": {
        "date": "2023-01-16 23:26:15.000000",
        "timezone_type": 3,
        "timezone": "Asia/Riyadh"
      },
      "type": "shipment",
      "courier_id": 814202285,
      "courier_name": "DHL",
      "courier_logo": "https://company.com/logo.png",
      "shipping_number": "0",
      "tracking_number": "0",
      "pickup_id": null,
      "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"
      },
      "meta": {
        "app_id": null,
        "policy_options": {
          "boxes": 2
        }
      },
      "ship_from": {
        "type": "branch",
        "name": "Riyadh",
        "email": "",
        "phone": "0555555555",
        "country": "السعودية",
        "country_id": 1939592358,
        "country_code": "KW",
        "city": "ABBASIYA",
        "city_id": 1313869267,
        "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": "السعودية",
        "country_id": 1939592358,
        "country_code": "KW",
        "city": "ABBASIYA",
        "city_id": 1313869267,
        "address_line": " شارع 2345، الحي السلام 95128،, شارع عبدالله  سنابل السلام  مكة  السعوديه,, الرياض, السعودية",
        "street_number": "2345",
        "block": "السلام",
        "postal_code": "95128",
        "latitude": 21.382590509685,
        "longitude": 39.773191030685
      },
      "packages": [
        {
          "name": "منتج تجريبي",
          "sku": "6ytrrhrhr",
          "price": {
            "amount": "50.00",
            "currency": "SAR"
          },
          "quantity": 2,
          "weight": {
            "value": "1.00",
            "unit": "kg"
          }
        }
      ],
      "billing_account": "salla"
    }
  ],
  "pagination": {
    "count": 3,
    "total": 32,
    "perPage": 3,
    "currentPage": 1,
    "totalPages": 11,
    "links": {
      "next": "https://company.com/shipments?page=2"
    }
  }
}

🟠422Error Validation