Update Order - Salla Merchants APIs

This endpoint allows you to update a specific order by passing the order_id as a path parameter.

Tip

For a darfted order, you have no restrictions to update any field.

You can update the order based on the following five details:

Object	Description
Customer	It can be modified if there's no associated `customer` or if the customer is `guest`.
Receiver	It can be modified if the order status isn't marked as `completed`.
Shipping	It can be modified if the order status isn't marked as `completed`.
Payments	It can be modified if the order status is set to `pending`.
Coupon	It can be modified if the order status isn't marked as `completed`.

Deprecation Notice

The variables data.checkout_url and data.rating_link will be deprecated by May 25, 2025. Moving forward, they will be accessible under the urls object as data.urls.checkout and data.urls.rating.

The variables, items.codes and items.files, are deprecated. We recommend using instead the data.urls.digital_content variable.

Scopes

orders.read_write - Orders Read & Write

Request

Authorization

Add the parameter

Authorization

to Headers，whose value is to concatenate the Token after the Bearer.

Example:

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

Path Params

order_id

integer

required

Order ID. Get a list of Order IDs from here

Example:

3155923424

Body Params application/json

customer

object

optional

Required if you are updating the customer details only

integer

optional

Customer unique ID. List of Customer ID can be found here

name

string

optional

Customer full name

mobile

string

optional

The numerical contact information belonging to a customer that allows communication via telephone, without country code.

string

optional

Email address of the customer used for electronic communication.

receiver

object

optional

Required if you are updating the receiver details only

name

string

optional

The name of the individual or entity to whom a shipment has been sent or delivered. It identifies the recipient or destination for the shipped items.

country_code

string

optional

A code that represents the specific destination country to which a the order has been sent or is being delivered.

phone

string

optional

The phone number associated with the individual or entity to whom a shipment has been sent or delivered.

string

optional

The email address associated with the individual or entity to whom a shipment has been sent or delivered.

notify

boolean

optional

Whether or not to notify the receiver of the order update

delivery_method

string

optional

Required if you are updating the delivery_method details only

branch_id

integer

optional

A unique identifier associated with a specific branch. List of Branch ID can be found here

courier_id

integer

optional

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

ship_to

object

optional

country

integer

optional

Shipment Ship To Country

city

integer

optional

Shipment Ship To City

block

string

optional

Shipment Ship To Block

street_number

string

optional

Shipment Ship To Street Number

address

string

optional

Shipment Ship To Address

address_line

string

optional

Shipment Ship To Address Line

postal_code

string

optional

Shipment Ship To Postal Code

geo_coordinates

object

optional

payment

object

optional

Required if you are updating the payment details only

status

string

optional

The payment status

method

string

optional

The way a customer chooses to pay for a product or service.

store_bank_id

integer

optional

Bank ID of the store.

receipt_image_path

string

optional

The URL link of the receipt image

accepted_methods

array[string]

optional

Accepted methods of payments

cash_on_delivery

object

optional

coupon_code

string

optional

Required if you are updating the coupon_code details only . List of Coupon code can be found here

employees

array[integer]

optional

The employees' ID assigned to orders. List of employees' ID can be found here

Example

// Customer object details to update

{
    "customer": {
        "id": 1209983424,
        "name": "new name",
        "mobile": "+966566666666",
        "email": "[email protected]"
    }
}

// Reciever object details to update

{
    "receiver": {
        "name": "i am the one",
        "country_code": "SA",
        "phone": "966566666666",
        "email": "[email protected]",
        "notify": false
    }
}

// Shipping object details to update

{
    "delivery_method": "shipping",
    "branch_id": 203948803,
    "courier_id": 1433878184,
    "ship_to": {
        "country": 1473353380,
        "city": 1939592358,
        "block": "Apt. 836",
        "street_number": "8230",
        "address": "24453 Rosalinda Well",
        "address_line": "West",
        "postal_code": "51434",
        "geo_coordinates": {
            "lat": 79.0225,
            "lng": 53.5041
        }
    }
}

// Payment object details to update

{
    "payment": {
        "status": "paid",
        "method": "bank",
        "store_bank_id": 234234,
        "receipt_image_path": "url",
        "accepted_methods": [
            "bank",
            "credit_card"
        ],
        "cash_on_delivery": {
            "amount": 10,
            "currency": "SAR"
        }
    }
}

// Attach Coupon variable detail to update 

{
    "coupon_code": "CO123123"
}

// Assign Order to one employee or more

{
  "employees": [1764372897, 187291202]
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

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 (Order)

optional

Detailed structure of the Order model object showing its fields and data types.

number

required

A unique alphanumeric code or identifier assigned to a specific order. List of orders can be found here

cart_reference_id

number

required

A unique alphanumeric code or identifier assigned to a specific order cart.

reference_id

number

required

A specific alphanumeric identifier associated with an order.

urls

object

required

Customer and Admin urls.

date

object (Date)

required

Date and time of the order.

updated_at

object (Date)

required

source

enum<string>

required

The source of the order.

Allowed values:

storelandingforgotten_basketabandoned-cartcampaigndashboardbuy_as_giftmahly-appbuy_nowone-clickcomplete_order

draft

boolean

required

Whether or not the order 's status is set to draft

read

boolean

required

Whether or not the Merchant has read the order

source_device

string

required

The machine or device used when the customer placed the order.

source_details

object

required

Order source details.

status

object (NewOrderStatus)

required

Order status.

is_price_quote

boolean

required

Whether or not to quote order price.

payment_method

string

required

The specific payment option chosen by a customer to pay for a product or service as part of an order.

receipt_image

string

required

Order's image receipt.

currency

string

required

The currency in which order costs and prices are expressed and processed.

amounts

object

required

Order amounts.

exchange_rate

object

required

The order exchange rate.

can_cancel

boolean

required

The option to enable order cancellation by the store customer.
True value should be set if the order status is in under review and in progress, as according to the store settings.

show_weight

boolean

required

Whether or not to show the weight value.

can_reorder

boolean

required

Whether or not to enable reorder .

is_pending_payment

boolean

required

The option of displaying order is pending payment to the customer when the order status is payment_pending.

rating_link

string

deprecated

The rating URL to review the order.
🛑 The variable is to be deprecated; use data.urls.rating variable instead.

checkout_url

string

deprecated

The checkout URL to settle payments related to the order
🛑 The variable is to be deprecated; use data.urls.checkout variable instead.

pending_payment_ends_at

integer

required

Last date allowed to customer to pay the order.

total_weight

string

required

Total weight value

shipping

object

required

Order Shipping details.

shipments

array [object {22}]

required

Order shipment details.

pickup_branch

object (Branch)

required

Order pickup branch details.

shipment_branch

object (ShipmentBranch)

required

Order shipment branch details.

customer

object (Customer)

required

Customer details.

items

array [object {16}]

required

bank

object

required

tags

object (OrderTag)

required

Order tag details.

store

object

required

Order store details.

Example

{
    "status": 200,
    "success": true,
    "data": {
        "id": 289032373,
        "reference_id": 27922,
        "urls": {
            "customer": "https://store_support.test/ar/engTest/order/zAB3exRyLdXv5WpqNyMrGg4p7Ej8ZKlN",
            "admin": "/orders/order/zAB3exRyLdXv5WpqNyMrGg4p7Ej8ZKlN",
            "digital_content": "https://salla.sa/dev-k9dn7fok0vih4p70/orders/digital/lm6bowYMnmA9eyWdLkJza153vyZnMb85QO0GZ7NxDlVKXB4grqR82jEN",
            "rating": "https://store-test.com/rating-link",
            "checkout": "https://store-test.com/checkout-link"
        },
        "date": {
            "date": "2022-10-17 18:58:07.000000",
            "timezone_type": 3,
            "timezone": "Asia/Riyadh"
        },
        "source": "dashboard",
        "source_device": "desktop",
        "source_details": {
            "type": "dashboard",
            "value": null,
            "device": "desktop",
            "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36",
            "ip": null
        },
        "first_complete_at": null,
        "status": {
            "id": 1298199463,
            "name": "تم التنفيذ",
            "slug": "completed"
        },
        "payment_method": "waiting",
        "currency": "SAR",
        "amounts": {
            "sub_total": {
                "amount": 60.22,
                "currency": "SAR"
            },
            "shipping_cost": {
                "amount": 40,
                "currency": "SAR"
            },
            "cash_on_delivery": {
                "amount": 0,
                "currency": "SAR"
            },
            "tax": {
                "percent": "15.00",
                "amount": {
                    "amount": 15.03,
                    "currency": "SAR"
                }
            },
            "discounts": [],
            "total": {
                "amount": 115.25,
                "currency": "SAR"
            }
        },
        "shipping": {
            "id": 1830458757,
            "app_id": null,
            "company": "لبيه",
            "logo": "https://cdn.salla.sa/jKxK/md4Pv5jeLEX52zWTboKSVr8VmlX5tNbiu9YF00C0.png",
            "receiver": {
                "name": "Mohammed Test",
                "email": "[email protected]",
                "phone": "96652318526"
            },
            "shipper": {
                "name": "Riyadh",
                "company_name": "Test Store",
                "email": "",
                "phone": "0555555555"
            },
            "pickup_address": {
                "country": "السعودية",
                "country_code": "SA",
                "city": "Riyadh",
                "shipping_address": "7687 طريق الملك فهد الفرعي,الملك فهد,12262, 7687 طريق الملك فهد الفرعي، الملك فهد، الرياض 12262 3010، السعودية, Riyadh,السعودية",
                "street_number": "7687 طريق الملك فهد الفرعي",
                "block": "الملك فهد",
                "postal_code": "12262",
                "geo_coordinates": {
                    "lat": 24.694018,
                    "lng": 46.6521887
                }
            },
            "address": {
                "country": "SA",
                "country_code": "SA",
                "city": "الرياض",
                "shipping_address": " شارع 123، الحي 132 1111،, 1111,, الرياض, السعودية",
                "street_number": "123",
                "block": "132",
                "postal_code": "1111",
                "geo_coordinates": {
                    "lat": 0,
                    "lng": 0
                }
            },
            "shipment": {
                "id": "SAIF2485",
                "pickup_id": null,
                "tracking_link": "https://api.shipengine.com/v1/labels/498498496/track",
                "label": {
                    "format": "pdf",
                    "url": "https://salla-dev.s3.eu-central-1.amazonaws.com/pZQq/shipping-policy/27922-1xMHJgGZHszfEGLd7NM5WVAMM7IBmfcwrR3sMI4j.pdf"
                }
            },
            "policy_options": [],
            "shipment_reference": 242712593,
            "branch_id": 1723506348
        },
        "shipments": [
            {
                "id": 649964784,
                "created_at": null,
                "type": "shipment",
                "courier_id": 802226618,
                "courier_name": "أوتو",
                "courier_logo": "https://salla-dev-portal.s3.eu-central-1.amazonaws.com/uploads/LUZaDEGwzFRDJKO7XVLXtix71Zb8Z2vBt6xwHrwZ.png",
                "shipping_number": null,
                "tracking_number": null,
                "pickup_id": null,
                "trackable": false,
                "tracking_link": null,
                "label": null,
                "payment_method": "cod",
                "source": "store",
                "status": "in_progress",
                "total": {
                    "amount": 175.47,
                    "currency": "SAR"
                },
                "cash_on_delivery": {
                    "amount": 0,
                    "currency": "SAR"
                },
                "is_international": true,
                "total_weight": {
                    "value": 0.2,
                    "units": "kg"
                },
                "packages": [
                    {
                        "item_id": 2077288690,
                        "external_id": null,
                        "quantity": 1,
                        "weight": {
                            "value": 0.2,
                            "units": "kg"
                        }
                    }
                ],
                "ship_from": {
                    "type": "branch",
                    "name": "المستودع الرئيسي التجريبي",
                    "email": "",
                    "phone": "966555855555",
                    "country": "السعودية",
                    "city": "Medina",
                    "address_line": "3391 حسين بين عبدلله بين ضميرا,مسجد الدرع,00000, 3391 حسين بين عبدلله بين ضميرا, الدرق موثق, مدينة 42313 8700, سعودي عربية, Medina,السعودية",
                    "street_number": "3391 حسين بين عبدلله بين ضميرا",
                    "block": "مسجد الدرع",
                    "postal_code": "00000",
                    "latitude": 24.524655575978006,
                    "longitude": 39.56918120384216,
                    "branch_id": 1790435930
                },
                "ship_to": {
                    "type": "address",
                    "name": "Test",
                    "email": "[email protected]",
                    "phone": "96652318526",
                    "country": "الامارات",
                    "city": "أبو ظبي",
                    "address_line": " شارع ijaz street، الحي Shakhbout city 70633،, villa 24,, أبو ظبي, الامارات",
                    "street_number": "ijaz street",
                    "block": "Shakhbout city",
                    "postal_code": "70633",
                    "latitude": 0,
                    "longitude": 0
                },
                "meta": {
                    "app_id": 846904320,
                    "policy_options": {
                        "dimensions": {
                            "length": "",
                            "width": "",
                            "height": ""
                        }
                    }
                }
            }
        ],
        "can_cancel": false,
        "show_weight": true,
        "can_reorder": true,
        "is_pending_payment": true,
        "pending_payment_ends_at": 0,
        "total_weight": "١١ كجم",
        "rating_link": "https://store-test.com/rating-link",
        "checkout_url": "https://store-test.com/checkout-link",
        "shipment_branch": [
            {
                "id": 1469878560,
                "name": "الفرع الرئيسي",
                "status": "active",
                "is_default": true,
                "type": []
            },
            {
                "id": 1723506348,
                "name": "Riyadh",
                "status": "active",
                "is_default": false,
                "type": []
            },
            {
                "id": 1723506348,
                "name": "Riyadh",
                "status": "active",
                "is_default": false,
                "type": []
            }
        ],
        "customer": {
            "id": 2107468057,
            "first_name": "Mohammed",
            "last_name": "Test",
            "mobile": 555555555,
            "mobile_code": "+966",
            "email": "[email protected]",
            "urls": {
                "customer": "https://store_support.test/ar/engTest/profile",
                "admin": "/customers/V04NBbJQ8P3gDaKRrVV1wEYG7oKxqjLX",
                "digital_content": "https://salla.sa/dev-k9dn7fok0vih4p70/orders/digital/lm6bowYMnmA9eyWdLkJza153vyZnMb85QO0GZ7NxDlVKXB4grqR82jEN"
            },
            "avatar": "https://salla-dev.s3.eu-central-1.amazonaws.com/customer_profiles/pz010MJLCJUi6kCzBChndZ7ZCFDWLmKSp5MYXE1A.png",
            "gender": "male",
            "birthday": {
                "date": "1998-08-07 00:00:00.000000",
                "timezone_type": 3,
                "timezone": "Asia/Riyadh"
            },
            "city": "مكة",
            "country": "السعودية",
            "country_code": "SA",
            "currency": "SAR",
            "location": "امام النوري",
            "updated_at": {
                "date": "2022-12-29 13:20:13.000000",
                "timezone_type": 3,
                "timezone": "Asia/Riyadh"
            }
        },
        "items": [
            {
                "id": 951850235,
                "name": "فحم سداسي - 10 كيلو",
                "sku": "6285579005111",
                "quantity": 1,
                "currency": "SAR",
                "weight": 10,
                "weight_label": "١٠ كجم",
                "amounts": {
                    "price_without_tax": {
                        "amount": 45.22,
                        "currency": "SAR"
                    },
                    "total_discount": {
                        "amount": 0,
                        "currency": "SAR"
                    },
                    "tax": {
                        "percent": "15.00",
                        "amount": {
                            "amount": 6.78,
                            "currency": "SAR"
                        }
                    },
                    "total": {
                        "amount": 45.22,
                        "currency": "SAR"
                    }
                },
                "notes": "",
                "product": {
                    "id": 268564496,
                    "type": "product",
                    "promotion": {
                        "title": "يدوم مدة طويلة !",
                        "sub_title": null
                    },
                    "quantity": 1057,
                    "status": "sale",
                    "is_available": true,
                    "sku": "6285579005111",
                    "name": "فحم سداسي - 10 كيلو",
                    "price": {
                        "amount": 52,
                        "currency": "SAR"
                    },
                    "sale_price": {
                        "amount": 0,
                        "currency": "SAR"
                    },
                    "currency": "SAR",
                    "url": "https://store_support.test/ar/engTest/epXbG",
                    "thumbnail": "https://salla-dev.s3.eu-central-1.amazonaws.com/pZQq/BVD74rxrvAmpmtUGQeqD9J6oinsl0hfQRoFqO7Lu.jpg",
                    "has_special_price": false,
                    "regular_price": {
                        "amount": 52,
                        "currency": "SAR"
                    },
                    "calories": null,
                    "mpn": "",
                    "gtin": "",
                    "description": "فحم طبيعي 100% غير ضار بالصحة داخل عبوة 6 كيلو مناسب للشواء أو التدفئة.",
                    "favorite": null,
                    "features": {
                        "availability_notify": {
                            "email": true,
                            "sms": true,
                            "mobile": false
                        }
                    },
                    "starting_price": null
                },
                "options": [],
                "images": [],
                "codes": [],
                "files": []
            },
            {
                "id": 177812420,
                "name": "الو ايفا بديل الزيت بالصبار",
                "sku": "62230043780581",
                "quantity": 1,
                "currency": "SAR",
                "weight": 1,
                "weight_label": "١ كجم",
                "amounts": {
                    "price_without_tax": {
                        "amount": 15,
                        "currency": "SAR"
                    },
                    "total_discount": {
                        "amount": 0,
                        "currency": "SAR"
                    },
                    "tax": {
                        "percent": "15.00",
                        "amount": {
                            "amount": 2.25,
                            "currency": "SAR"
                        }
                    },
                    "total": {
                        "amount": 15,
                        "currency": "SAR"
                    }
                },
                "notes": "",
                "product": {
                    "id": 762341264,
                    "type": "product",
                    "promotion": {
                        "title": null,
                        "sub_title": null
                    },
                    "quantity": 224,
                    "status": "sale",
                    "is_available": true,
                    "sku": "62230043780581",
                    "name": "الو ايفا بديل الزيت بالصبار",
                    "price": {
                        "amount": 17.25,
                        "currency": "SAR"
                    },
                    "sale_price": {
                        "amount": 0,
                        "currency": "SAR"
                    },
                    "currency": "SAR",
                    "url": "https://store_support.test/ar/engTest/nvrjb",
                    "thumbnail": "https://salla-dev.s3.eu-central-1.amazonaws.com/pZQq/AiNlkYjFO0uSwbPmBcaCQKMiIGmUsKAY25gUiiT7.jpg",
                    "has_special_price": false,
                    "regular_price": {
                        "amount": 17.25,
                        "currency": "SAR"
                    },
                    "calories": null,
                    "mpn": null,
                    "gtin": null,
                    "description": "ALOE EVA OIL REPLACEMENT 1",
                    "favorite": null,
                    "features": {
                        "availability_notify": {
                            "email": true,
                            "sms": true,
                            "mobile": false
                        }
                    },
                    "starting_price": null
                },
                "options": [],
                "images": [],
                "codes": [],
                "files": []
            }
        ],
        "product_reservations": [
            {
                "id": 1289748598,
                "from": "01:10",
                "to": "01:40",
                "date": "2023-04-18"
            }
        ],
        "bank": null,
        "tags": [
            {
                "id": 525144736,
                "name": "MultiShipments"
            }
        ]
    }
}

🟠422Error Validation

🟠404Not Found

🟠401unauthorized