Update Shipment Details - Salla Merchants APIs

This endpoint allows you to update specific Shipment Details by providing the ID of the shipment you want to update its details.

Breaking Change Notice

Effective January 20th, 2025, the status variable will be a required field in the request payload.

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 ********************

Path Params

shipment_id

number

required

Shipment ID. Get a list of Shipment IDs from here

Example:

362985662

Body Params application/json

tracking_link

string

optional

A URL that provides a link to the tracking information for the shipment.

Example:

https://xyz-shipping.com/v1/labels/498498496/track

shipment_number

string

required

A unique identifier for the shipment that distinguishes it from other shipments.

Example:

846984645

tracking_number

string

optional

A unique identifier for the tracking information associated with the shipment.

Example:

54563653

status

enum<string>

required

The current status of the shipment.

Effective January 20th, 2025, the status variable will be a required field in the request payload.

Allowed values:

createdin_progressdeliveringdeliveredshippedcancelled

Example:

delivered

status_note

string

optional

The note field provides additional shipment information relevant factors, as it is used to clarify the shipment status and provide context.

Example:

Parcel has been picked up by our logistics partner

pdf_label

string

optional

A PDF label that contains information about the shipment, such as the sender's and recipient's address, tracking number, and other relevant details.

Example:

https://xyz-shipping/v1/downloads/10/F91fByOB-0aJJadf7JLeww/label-63563751.pdf

cost

integer

optional

The actual cost of the shipment that the Merchant will be charged for, which is calculated per the shipping company's actual costs. Ensure to include VAT in the cost.

Example:

external_company_name

string

optional

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

Example

{
  "order_id": 76587644,
  "tracking_link": "https://api.shipengine.com/v1/labels/498498496/track",
  "shipment_number": "846984645",
  "tracking_number": "54563653",
  "status": "delivered",
  "status_note": "Parcel has been picked up by our logistics partner",
  "pdf_label": "https://api.shipengine.com/v1/downloads/10/F91fByOB-0aJJadf7JLeww/label-63563751.pdf",
  "cost": 40
}

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 **object** for use in a RESTful API for querying shipment data.

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

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 object for use in a RESTful API for querying shipment data.

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,
      "name": "DHL",
      "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": {
      "id": 566146469,
      "name": "بإنتظار المراجعة",
      "slug": "under_review"
    },
    "total": {
      "amount": 7000,
      "currency": "SAR"
    },
    "cash_on_delivery": {
      "amount": 15,
      "currency": "SAR"
    },
    "packages": [
      {
        "name": "Apple Watch",
        "sku": "6ytrrhrhr",
        "price": {
          "amount": "1000.00",
          "currency": "SAR"
        },
        "quantity": 2,
        "weight": {
          "value": "0.10",
          "unit": "kg"
        }
      },
      {
        "name": "Apple Iphone 14 Pro Max",
        "sku": "6ytrrhrhr3332",
        "price": {
          "amount": "5000.00",
          "currency": "SAR"
        },
        "quantity": 1,
        "weight": {
          "value": "0.50",
          "unit": "kg"
        }
      }
    ],
    "ship_from": {
      "type": "branch",
      "branch_id": 1723506348,
      "name": "Riyadh",
      "email": null,
      "phone": "0555555555",
      "country": "السعودية",
      "city": "الرياض",
      "address_line": "7687 طريق الملك فهد الفرعي، الملك فهد، الرياض 12262 3010، السعودية",
      "street_number": "7687 طريق الملك فهد الفرعي",
      "block": "الملك فهد",
      "postal_code": "12262",
      "geo_coordinates": {
        "lat": "24.7431373",
        "lng": "46.6570741"
      }
    },
    "ship_to": {
      "type": "address",
      "name": "Username",
      "email": "[email protected]",
      "phone": "050-948-0868",
      "country": "السعودية",
      "city": "الرياض",
      "address_line": "شارع عبدالله  سنابل السلام  مكة  السعوديه",
      "street_number": "2345",
      "block": "السلام",
      "postal_code": "95128",
      "geo_coordinates": {
        "lat": "21.382590509685",
        "lng": "39.773191030685"
      }
    },
    "meta": {
      "app_id": null,
      "policy_options": {
        "boxes": 2
      }
    },
    "billing_account": "salla"
  }
}

🟠422Validation Error