Create Order - Salla Merchant APIs

This endpoint allows you to create an order related to your store directly from this endpoint.

Alert

When creating an order, you must send either the customer_id variable or the receiver object, or both.

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

Body Params application/json

customer

object

optional

number

optional

Customer ID. Required if both variables customer.mobile and customer.name are not in the request. List of customer ID can be found here.

mobile

string

optional

Customer Mobile. Required if the variable customer.id is not in the request.

Example:

+9665305305300

name

string

optional

Customer Name. Required if the variable customer.id is not in the request.

string

optional

Customer Email. Required if the variable customer.id is not in the request.

receiver

object

optional

name

string

optional

Receiver Name

country

string

optional

Receiver Country. Fetch a list of country codes using this endpoint.

phone

string

optional

Receiver Phone

Example:

+9665305305300

string

optional

Receiver Email

notify

boolean

optional

Whether or not to notify Receiver

country_code

string

optional

Receiver Country Code

Example:

payment

object

optional

status

enum<string>

required

Payment Status

Allowed values:

paidpending_payment

method

enum<string>

optional

Payment Methods. Required if the variable status value is set to paid

Allowed values:

credit_cardmadabankcod

bank_id

number

optional

Bank ID. Required if the variable method value is set to bank

receipt_image_path

string

optional

Receipt Image Path. Required if the variable method value is set to bank

Example:

https://example.com/order/receipt.pdf

accepted_methods

enum<string>

optional

Payment Accepted Methods by the store. Required if the variable status value is set to pending_payment

Allowed values:

credit_cardmadabankcod

cash_on_delivery

object

optional

Cash on Delivery details. Required if the variable method value is set to cod

delivery_method

enum<string>

optional

Delivery Method. This variable is required if one or more products require shipping

Allowed values:

pickupshippingnull

branch_id

number

optional

Branch ID. Required if the variable delivery_method value is set to pickup. List of branches can be found here.

courier_id

string

optional

Courier ID. Required if the variable delivery_method value is set to shipping. List of shipping companies can be found here

ship_to

object

optional

Ship to destination details. Required if the variable delivery_method value is shipping

country

number

optional

Ship to destination country. Fetch a list of country codes using this endpoint.

city

number

optional

Ship to destination city. Fetch a list of city codes using this endpoint.

block

string

optional

Ship to destination block

street_number

string

optional

Ship to destination street number

address_line

string

optional

Ship to destination address line

postal_code

number

optional

Ship to destination postal code

geo_coordinates

object

optional

products

array [object {5}]

optional

identifier_type

enum<string>

optional

Product identifier type value

Allowed values:

idsku

identifier

string | number

optional

identifier value

if the variable identifier_type value is set to sku, then the datatype of this variable will be string

if the variable identifier_type value is set to id, then the datatype of this variable will be number

quantity

number

required

Product quantity value

options

array [object {2}]

optional

Product options details. Required if the product has advanced options

donating_amount

integer

optional

Product donating amount. Require if the store is of type جمعيات خيرية | charity

coupon_code

string

optional

Coupon code value

Example

{
    "customer": {
        "id": 1209983424,
        "name": "new name",
        "mobile": "+966566666666",
        "email": "[email protected]"
    },
    "receiver": {
        "name": "i am the one",
        "country_code": "SA",
        "phone": "966566666666",
        "email": "[email protected]",
        "notify": false
    },
    "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": {
        "status": "paid",
        "method": "bank",
        "store_bank_id": 234234,
        "receipt_image_path": "url",
        "accepted_methods": [
            "bank",
            "credit_card"
        ],
        "cash_on_delivery": {
            "amount": 10,
            "currency": "SAR"
        }
    },
    "products": [
        {
            "identifier_type": "id",
            "identifier": 892907448,
            "quantity": 1,
            "options": [
                {
                    "id": 1626535321,
                    "value": [
                        "96445177"
                    ]
                }
            ]
        },
        {
            "identifier_type": "id",
            "identifier": 728473534,
            "quantity": 1
        },
        {
            "identifier_type": "sku",
            "identifier": "sku123",
            "quantity": 1
        }
    ]
}

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.

Examples

Example 1Example 2Example 3

{
    "status": 200,
    "success": true,
    "data": {
        "id": 1275404514,
        "reference_id": 40497223,
        "urls": {
            "customer": "https://salla.sa/dev-wofftr4xsra5xtlv/order/Rowq4JLlxVenM8ELG5X1vzOPYXyjGpQ0",
            "admin": "https://s.salla.sa/orders/order/Rowq4JLlxVenM8ELG5X1vzOPYXyjGpQ0",
            "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-06-16 14:41:05.000000",
            "timezone_type": 3,
            "timezone": "Asia/Riyadh"
        },
        "source": "dashboard-api",
        "source_device": "desktop",
        "source_details": {
            "type": "dashboard-api",
            "value": null,
            "device": "desktop",
            "user-agent": "PostmanRuntime/7.29.0",
            "ip": null
        },
        "first_complete_at": null,
        "status": {
            "id": 566146469,
            "name": "بإنتظار المراجعة",
            "slug": "under_review"
        },
        "payment_method": "credit_card",
        "currency": "SAR",
        "amounts": {
            "sub_total": {
                "amount": 0,
                "currency": "SAR"
            },
            "shipping_cost": {
                "amount": 0,
                "currency": "SAR"
            },
            "cash_on_delivery": {
                "amount": 0,
                "currency": "SAR"
            },
            "tax": {
                "percent": "0.00",
                "amount": {
                    "amount": 0,
                    "currency": "SAR"
                }
            },
            "discounts": [],
            "total": {
                "amount": 0,
                "currency": "SAR"
            }
        },
        "shipping": [],
        "can_cancel": true,
        "can_reorder": true,
        "is_pending_payment": false,
        "rating_link": "https://mtjr.at/vIMPNgXhOm",
        "checkout_url": "https://salla.sa/dev-nzzxsxjwinegxaa4/checkout/209nryYWDg2Xoqd1VOJaGLwKvrRY8l08vmA708NkE3zM6BlRe4bZxj5b",
        "pending_payment_ends_at": 75598,
        "shipment_branch": [],
        "customer": {
            "id": 1438395499,
            "first_name": "صالح",
            "last_name": "4",
            "mobile": 540090076,
            "mobile_code": "+966",
            "email": "",
            "urls": {
                "customer": "https://salla.sa/dev-wofftr4xsra5xtlv/profile",
                "admin": "https://s.salla.sa/customers/Y7GXy5K8j9Qw1lrAKz3WLPkOq4omVNR2",
                "digital_content": "https://salla.sa/dev-k9dn7fok0vih4p70/orders/digital/lm6bowYMnmA9eyWdLkJza153vyZnMb85QO0GZ7NxDlVKXB4grqR82jEN"
            },
            "avatar": "https://store-test.com/cp/assets/images/avatar_male.png",
            "gender": "",
            "birthday": null,
            "city": "",
            "country": "السعودية",
            "country_code": null,
            "currency": "SAR",
            "location": "",
            "updated_at": {
                "date": "2022-05-23 09:37:10.000000",
                "timezone_type": 3,
                "timezone": "Asia/Riyadh"
            }
        },
        "items": [
            {
                "id": 510046883,
                "name": "تي شيرت بلاك",
                "sku": "996754231",
                "quantity": 1,
                "currency": "SAR",
                "weight": 12,
                "amounts": {
                    "price_without_tax": {
                        "amount": 55,
                        "currency": "SAR"
                    },
                    "total_discount": {
                        "amount": 0,
                        "currency": "SAR"
                    },
                    "tax": {
                        "percent": "0",
                        "amount": {
                            "amount": 0,
                            "currency": "SAR"
                        }
                    },
                    "total": {
                        "amount": 55,
                        "currency": "SAR"
                    }
                },
                "notes": "",
                "product": {
                    "id": 784769282,
                    "type": "product",
                    "promotion": {
                        "title": "New",
                        "sub_title": "Collection 2020"
                    },
                    "status": "sale",
                    "is_available": true,
                    "sku": "996754231",
                    "name": "تي شيرت بلاك",
                    "price": {
                        "amount": 55,
                        "currency": "SAR"
                    },
                    "sale_price": {
                        "amount": 0,
                        "currency": "SAR"
                    },
                    "currency": "SAR",
                    "url": "https://salla.sa/dev-wofftr4xsra5xtlv/t-shirt-blue-collection-2020/p784769282",
                    "thumbnail": "https://cdn.salla.sa/bYQEn/uUTgTrRihqRAGXy0jEV8DcJ3D8j4v6PPtwRpkCdz.png",
                    "has_special_price": false,
                    "regular_price": {
                        "amount": 55,
                        "currency": "SAR"
                    },
                    "calories": null,
                    "mpn": "45343",
                    "gtin": "14643439",
                    "favorite": null
                },
                "options": [],
                "images": [],
                "codes": [],
                "files": []
            }
        ],
        "bank": null,
        "tags": []
    }
}

🟠422Error Validation

🟠401Unauthorized