Salla Docs
Merchant API
  • Merchant API
  • Salla OAuth 2.0
Partner APIs
  • App API
  • Shipment API
Storefront
  • Twilight Engine
  • Twilight SDK
  • Web Components
  • Change Log
Salla CLI
Merchant API
  • Merchant API
  • Salla OAuth 2.0
Partner APIs
  • App API
  • Shipment API
Storefront
  • Twilight Engine
  • Twilight SDK
  • Web Components
  • Change Log
Salla CLI
Salla - Opensource
Salla - Developers Community
  1. Shipments
  • Publish App
  • Change Log
  • Getting Started
  • Migration to the New API
  • Shipping Management
    • Create App
    • App Cycle
    • Setup App
    • Test App
  • Order Fulfilment
    • Create App
    • App Cycle
    • Setup App
    • Test App
  • Shipments
    • Create Shipment
      POST
    • List Shipments
      GET
    • Update Shipment Details
      PUT
    • Shipment Details
      GET
    • Cancel Shipments
      POST
    • Return Shipments
      POST
    • Shipment Tracking
      GET
  • Shipping Companies
    • List Shipping Companies
      GET
    • Shipping Company Details
      GET
  1. Shipments

Create Shipment

Production
https://api.salla.dev/admin/v2
Production
https://api.salla.dev/admin/v2
POST
https://api.salla.dev/admin/v2
/shipments
Shipments
Last modified:2025-02-05 08:33:34
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
Provide your bearer token in the
Authorization
header when making requests to protected resources.
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:
2
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
ship_to
object 
optional
Shipment destination details.
name
string 
required
Shipment Ship To Name
Example:
username
email
string 
required
Shipment Ship To Email
Example:
username@gmailcom
phone
string 
required
Shipment Ship To Phone
Example:
555-555-555
country_id
string 
required
Shipment Ship To Country. Find a complete list of countries here.
Example:
1473353380
city_id
string 
required
Shipment Ship To CityFind a complete list of cities here.
Example:
123
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 
optional
ship_from
object 
optional
Shipment source details.
type
string 
optional
Shipment Ship From Type
Example:
address
name
string 
optional
Shipment Ship From Name
Example:
Username
email
string 
optional
Shipment Ship From Email
Example:
[email protected]
phone
string 
optional
Shipment Ship From Phone
Example:
555-555-555
country
string 
optional
Shipment Ship From Country
Example:
Saudi Arabia
city
string 
optional
Shipment Ship From City
Example:
Mecca
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
latitude
number 
optional
Shipment Ship From Latitude
Example:
10.2345
longitude
number 
optional
Shipment Ship From Longitude
Example:
54.321
branch_id
integer 
optional
Shipment Ship From Branch ID
Example:
194309
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:
2
weight
object 
optional
Example
{
  "shipment_id": 0,
  "courier_id": 1723506348,
  "order_id": 28475601,
  "external_company_name": "string",
  "overwrite_exists_pending": true,
  "shipment_type": "return",
  "policy_options": {
    "boxes": 2
  },
  "payment_method": "cod",
  "cash_on_delivery": {
    "amount": 200,
    "currency": "SAR"
  },
  "ship_to": {
    "name": "username",
    "email": "username@gmailcom",
    "phone": "555-555-555",
    "country_id": "1473353380",
    "city_id": "123",
    "address_line": "Tahlia Street",
    "street_number": "120",
    "block": "Block AB",
    "postal_code": "1000",
    "geo_coordinates": {
      "lat": 10.1234,
      "lng": 43.2105
    }
  },
  "ship_from": {
    "type": "address",
    "name": "Username",
    "email": "[email protected]",
    "phone": "555-555-555",
    "country": "Saudi Arabia",
    "city": "Mecca",
    "address_line": "Mecca Street",
    "street_number": "string",
    "block": "string",
    "postal_code": "string",
    "latitude": 10.2345,
    "longitude": 54.321,
    "branch_id": 194309
  },
  "packages": [
    {
      "name": "Package 1",
      "sku": "SKU-123-456",
      "price": {
        "amount": 200,
        "currency": "sar"
      },
      "quantity": 2,
      "weight": {
        "value": 3,
        "units": "kg"
      }
    }
  ]
}

Request samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://api.salla.dev/admin/v2/shipments' \
--header 'Content-Type: application/json' \
--data-raw '{
    "shipment_id": 0,
    "courier_id": 1723506348,
    "order_id": 28475601,
    "external_company_name": "string",
    "overwrite_exists_pending": true,
    "shipment_type": "return",
    "policy_options": {
        "boxes": 2
    },
    "payment_method": "cod",
    "cash_on_delivery": {
        "amount": 200,
        "currency": "SAR"
    },
    "ship_to": {
        "name": "username",
        "email": "username@gmailcom",
        "phone": "555-555-555",
        "country_id": "1473353380",
        "city_id": "123",
        "address_line": "Tahlia Street",
        "street_number": "120",
        "block": "Block AB",
        "postal_code": "1000",
        "geo_coordinates": {
            "lat": 10.1234,
            "lng": 43.2105
        }
    },
    "ship_from": {
        "type": "address",
        "name": "Username",
        "email": "[email protected]",
        "phone": "555-555-555",
        "country": "Saudi Arabia",
        "city": "Mecca",
        "address_line": "Mecca Street",
        "street_number": "string",
        "block": "string",
        "postal_code": "string",
        "latitude": 10.2345,
        "longitude": 54.321,
        "branch_id": 194309
    },
    "packages": [
        {
            "name": "Package 1",
            "sku": "SKU-123-456",
            "price": {
                "amount": 200,
                "currency": "sar"
            },
            "quantity": 2,
            "weight": {
                "value": 3,
                "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
id
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": "anim",
  "success": false,
  "data": [
    {
      "id": -32645125.3234493,
      "order_id": 93507000.57084745,
      "order_reference_id": null,
      "created_at": {
        "date": "2024-02-12T14:09:27.127Z",
        "timezone_type": 70745330,
        "timezone": "America/Sao_Paulo"
      },
      "type": "shipment",
      "courier_id": 8948698,
      "courier_name": "esse numquam doloribus",
      "courier_logo": "cupidatat fugiat qui id tempor",
      "shipping_number": "velit est",
      "tracking_number": "sint ad minim cillum",
      "pickup_id": null,
      "trackable": true,
      "tracking_link": "https://high-level-footstep.name",
      "label": {
        "format": "2024-02-13T00:46:47.084Z",
        "url": "http://wasteful-facet.name"
      },
      "payment_method": "pre_paid",
      "source": "tempor",
      "status": "delivered",
      "total": {
        "amount": -87094298.04461335,
        "currency": "SHP"
      },
      "cash_on_delivery": {
        "amount": 42126404.63522267,
        "currency": "ILS"
      },
      "is_international": false,
      "total_weight": {
        "value": -57799137.09990661,
        "units": "mollit laboris fugiat pariatur consectetur"
      },
      "packages": [
        {
          "item_id": 62924221,
          "external_id": null,
          "name": "explicabo dolores nesciunt",
          "sku": "dolore non sed est incididunt",
          "price": {
            "amount": 88829593.05470765,
            "currency": "SOS"
          },
          "quantity": -32542040,
          "weight": {
            "value": 38160911,
            "units": "kg"
          }
        }
      ],
      "ship_from": {
        "type": "id",
        "name": "laudantium ullam earum",
        "email": "[email protected]",
        "phone": "(065) 723-2847",
        "country": "ليبيريا",
        "city": "عجمان",
        "address_line": "Excepteur",
        "street_number": null,
        "block": null,
        "postal_code": null,
        "latitude": 8.5867,
        "longitude": -69.9668,
        "branch_id": -1346031
      },
      "ship_to": {
        "type": "dolor veniam dolor",
        "name": "eligendi accusantium eum",
        "email": "[email protected]",
        "phone": "453.850.0142 x8168",
        "country": "بهماس",
        "city": "الإسكندرية",
        "address_line": "ad sunt dolor",
        "street_number": "37934 جادة بركات",
        "block": "sunt aliquip deserunt Ut",
        "postal_code": "Duis sit do proident occaecat",
        "latitude": -39.1654,
        "longitude": 93.9262
      },
      "meta": {
        "app_id": 3349694,
        "policy_options": {
          "shipment_content_type": [
            "document"
          ],
          "packaging_type": [
            "pallet"
          ],
          "boxes": -69384132
        }
      },
      "billing_account": "merchant"
    }
  ]
}
🟠422Validation Error
Modified at 2025-02-05 08:33:34
Previous
Shipments
Next
List Shipments