Order Notes - Zid Docs

The Add Order Comment API allows shipping and fulfilment partners to post real-time shipment updates directly to an order’s activity.

Partners can add up to 20 comments per order, each limited to 100 characters.

Comments are non-editable and include the app name for clarity.

These updates are visible to merchants in the order activity dashboard, improving communication and speeding up fulfilment-related issue resolution.

🔑Scopes

orders.read_write - Orders Read & Write

curl --location --request POST 'https://api.zid.sa/v1v1/managers/store/orders/123456/add-order-comment' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIxMTciLCJqdGkiOiJhMTg5ZTg3MmYxMzhkMWVhYjU5MjVkMDkyMGE5NmI0YjliNjg0Y2E2ZTdmM2M2MjljZWYxNmQ4NDJjMmJlYmVhMjI4YTdmMTA0ZWQ4NWE5NCIsImlhdCI6MTY3OTU3Njk5OS41NjY4NzcsIm5iZiI6MTY3OTU3Njk5OS41NjY4OCwiZXhwIjoxNzExMTk5Mzk5LjQ4NjE1Mywic3ViIjoiMTgyNDc1Iiwic2NvcGVzIjpbInRoaXJkLXBhcnRpZXMtYXBpcyJdfQ.i07ef09nVNXGZF-g-QXpNoS2vlFQK_zntAqAMS4Az2XD2EyMLhxLZZRL-QlR11zUPqMmXjMAl_4ooKa3M3zkfZQ6Ga6qStvamk8RnC_39VUx0lfN2A4k65ERZpqwrMy6-t3dE99zay3aicIdNvbgi0zeuMSE5Tn99u-2AtSRa8ffbfAcYPPXacHrhdmlYzdiZS_x_skovFEow1E-nDjdL1WHqO92XdZ7RfNLkiYFTjZlZmM_UruvioaR3q6TXJbqRK_ZrziivezL8ohIQ2SBosUp58I29rlKzvlw_R2j0rKKYZbdxYDaxAHOISmOFKAlO66k7dNevAHI3s4uGIjoGA6ZXHknccWPLLLiaAQ0r64HV8GowW5dg2rhZNurJGDTnLlBQ6F-ql42ptHzSAfzzi576CEoN3gMVpgXcbntUY3reETkFsTBPUjeSuMpANMioXAA0GRp3Ut-84fTnrWxqsCW1WVUIx33HvmfCGPXIdkaCCWoA6G6KXo04MtFbKXQmXkK9esQWI-rqdVnMD3zSR3g3yFHZSL1U-mZeNja03706Rav1ordsRNOtRwtLuoRRbk9KasbUpEwqq4Ao9lqZZwRIjdEw-pQtnUT8V53fhmuuRIefCLFO7eGEtGUnh9o6Uh_pgi6AB6uSlnN9GEMGgI1alqvMmTjxvC-HHt0V-Y' \ --header 'X-manager-Token: eyJpdiI6ImdmbVQ5ZTFZWm5hRkdvbmFTQ2o2ZkE9PSIsInZhbHVlIjoiMDVXVU1yQWFaTDgvMEZwYW5JWGR1QVZCQ3hFUzQxQ2t3a1oxOGR2QWhEays3N28zeldtaytKU1pzL2tHQU9jT2dZMlZCcnBsUEp1TmcxTG1SWlBnMDVLc0R3dlpGZENsY0s2Y1RwNHpEbVpYbGtjYlVITVpzcy8rNHBkQmxqZExsZW01REJkZmdQb3FmZmNTWTZXZ2JWRitmRWpWSnRZU0NOcTFvRGdjRU9Obk5TZDZRL2FCRHdobytwK3JVZUsrbWJ3RmtmUHlOcEZMcENzUENxUEkrUHFZZTdPQ043S0xtczF0d1k1ekZlaz0iLCJtYWMiOiI0ZDM4MDk3NDMwZDRhZjNkOGI0MzU1ODdmZGVmNGJiNzFmYTE2ZTZjYWM1Njc0NTQ0NmIwMjY1NWMxZWY4ZDQyIiwidGFnIjoiIn0::' \ --header 'Accept-Language: en' \ --header 'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.82 Safari/537.36' \ --header 'store-id: 123' \ --header 'role: Manager' \ --header 'Content-Type: application/json' \ --data-raw '{ "comment": "Your detailed shipment progress message here" }'

{ "status": "object", "order": { "id": 25304285, "code": "8OVNEhyqcf", "store_id": 251073, "order_url": "https://zid.store/osama/o/6IJWXOYLuR/inv", "store_name": "Osama's Store", "shipping_method_code": "custom", "store_url": "https://zid.store/osama/", "order_status": { "name": "Delivery in progress", "code": "new" }, "currency_code": "KWD", "is_marketplace_order": false, "customer": { "id": "2083543", "name": "Osama", "email": "example.user@email.com", "mobile": "+966501234567", "note": " ", "verified": "1", "type": "individual" }, "shipping": { "method": { "id": "SHM-123456", "name": "Express Delivery", "code": "EXP_DEL", "estimated_delivery_time": "3-5 Business Days", "icon": "https://cdn.example.com/icons/shipping/express_delivery.png", "is_system_option": false, "waybill": "WB-12345678", "had_errors_while_fetching_waybill": false, "waybill_tracking_id": "TRACK-12345678", "has_waybill_and_packing_list": false, "tracking": { "number": "TRACK-12345678", "status": "In Transit", "url": "https://example.com/track?number=TRACK-12345678" }, "order_shipping_status": null, "inventory_address": [ "string" ], "courier": "FedEx", "return_shipment": "RET-12345678" }, "address": { "formatted_address": "Masked Address", "street": "Masked Street", "district": "Masked District", "city": { "id": 1, "name": "Other" }, "country": { "id": 184, "name": "السعودية", "code": "SA" } } }, "payment": { "method": { "name": "بطاقة مدى البنكية", "code": "zidpay", "type": "cc", "payment_network": "Visa" }, "invoice": [ { "code": "sub_totals_before_vat", "value": "0.00000000000000", "value_string": "0.000 KWD", "title": "المجموع غير شامل الضريبة" } ] }, "is_potential_fraud": false, "created_at": "2023-07-04 09:12:36", "updated_at": "2023-07-04 09:14:28", "invoice_link": "https://zid-testing-907587157081.s3-accelerate.amazonaws.com/pdf/order_44834593.pdf", "products_count": 1, "products_sum_total_string": "30.00 SAR", "language": "ar", "histories": [ { "order_status_id": 1, "order_status_name": "جديد", "changed_by_id": 37, "changed_by_type": "عميل", "changed_by_details": { "action": "تم إنشاء الطلب .", "by": "Ahmed Al-Saud", "comment": "Manually created after size-change request." }, "comment": "تم إنشاء الطلب .", "created_at": "2023-07-04 09:12:36", "humanized_created_at": "منذ شهر" } ], "is_reactivated": false, "return_policy": "Returns are accepted within 14 days of receipt.", "packages_count": 1, "invoice_settings": { "is_order_notifications_enabled": true } }, "message": { "type": "object", "code": "200", "name": "Success", "description": "Order details retrieved successfully." } }

Request

Path Params

order_Id

string

required

The unique identifier of the order for which the comment is being added.

Example:

123456

Header Params

string

optional

Specifies the Media Types acceptable for the client. In this case, it signals that the client expects a response in the JSON format.

Example:

application/json

Authorization

string

optional

The Authorization token is a unique key given to the third-party application (Partner) by Zid. It is used to authenticate the API requests made by the Partner application. The token verifies the partner's identity and ensures they have permission to access Zid's API but does not provide any specific user or store information. It should be included in the header of API requests when the partner application needs to access Zid's API.

Example:

Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIxMTciLCJqdGkiOiJhMTg5ZTg3MmYxMzhkMWVhYjU5MjVkMDkyMGE5NmI0YjliNjg0Y2E2ZTdmM2M2MjljZWYxNmQ4NDJjMmJlYmVhMjI4YTdmMTA0ZWQ4NWE5NCIsImlhdCI6MTY3OTU3Njk5OS41NjY4NzcsIm5iZiI6MTY3OTU3Njk5OS41NjY4OCwiZXhwIjoxNzExMTk5Mzk5LjQ4NjE1Mywic3ViIjoiMTgyNDc1Iiwic2NvcGVzIjpbInRoaXJkLXBhcnRpZXMtYXBpcyJdfQ.i07ef09nVNXGZF-g-QXpNoS2vlFQK_zntAqAMS4Az2XD2EyMLhxLZZRL-QlR11zUPqMmXjMAl_4ooKa3M3zkfZQ6Ga6qStvamk8RnC_39VUx0lfN2A4k65ERZpqwrMy6-t3dE99zay3aicIdNvbgi0zeuMSE5Tn99u-2AtSRa8ffbfAcYPPXacHrhdmlYzdiZS_x_skovFEow1E-nDjdL1WHqO92XdZ7RfNLkiYFTjZlZmM_UruvioaR3q6TXJbqRK_ZrziivezL8ohIQ2SBosUp58I29rlKzvlw_R2j0rKKYZbdxYDaxAHOISmOFKAlO66k7dNevAHI3s4uGIjoGA6ZXHknccWPLLLiaAQ0r64HV8GowW5dg2rhZNurJGDTnLlBQ6F-ql42ptHzSAfzzi576CEoN3gMVpgXcbntUY3reETkFsTBPUjeSuMpANMioXAA0GRp3Ut-84fTnrWxqsCW1WVUIx33HvmfCGPXIdkaCCWoA6G6KXo04MtFbKXQmXkK9esQWI-rqdVnMD3zSR3g3yFHZSL1U-mZeNja03706Rav1ordsRNOtRwtLuoRRbk9KasbUpEwqq4Ao9lqZZwRIjdEw-pQtnUT8V53fhmuuRIefCLFO7eGEtGUnh9o6Uh_pgi6AB6uSlnN9GEMGgI1alqvMmTjxvC-HHt0V-Y

X-manager-Token

string

optional

This token is used to authenticate and access information related to the store. It is obtained through an OAuth mechanism and is required to perform operations on the store's data. The X-Manager-Token should be included in the header of API requests that require store-related information.

Example:

eyJpdiI6ImdmbVQ5ZTFZWm5hRkdvbmFTQ2o2ZkE9PSIsInZhbHVlIjoiMDVXVU1yQWFaTDgvMEZwYW5JWGR1QVZCQ3hFUzQxQ2t3a1oxOGR2QWhEays3N28zeldtaytKU1pzL2tHQU9jT2dZMlZCcnBsUEp1TmcxTG1SWlBnMDVLc0R3dlpGZENsY0s2Y1RwNHpEbVpYbGtjYlVITVpzcy8rNHBkQmxqZExsZW01REJkZmdQb3FmZmNTWTZXZ2JWRitmRWpWSnRZU0NOcTFvRGdjRU9Obk5TZDZRL2FCRHdobytwK3JVZUsrbWJ3RmtmUHlOcEZMcENzUENxUEkrUHFZZTdPQ043S0xtczF0d1k1ekZlaz0iLCJtYWMiOiI0ZDM4MDk3NDMwZDRhZjNkOGI0MzU1ODdmZGVmNGJiNzFmYTE2ZTZjYWM1Njc0NTQ0NmIwMjY1NWMxZWY4ZDQyIiwidGFnIjoiIn0::

Accept-Language

string

optional

Preferred language for the response. Defaults to en if not specified.

Example:

User-Agent

string

optional

The User-Agent header contains information about the user agent (browser or app) making the request. It allows the server to provide a tailored response depending on the user agent's capabilities and preferences.

Example:

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.82 Safari/537.36

store-id

integer

optional

The unique identifier of the store where the order belongs (integer).

Example:

123

role

string

optional

The role of the user initiating the request.

Example:

Manager

Body Params application/json

comment

string

required

The detailed shipment progress message to be added to the order. This comment will be visible to merchants in the order activity.

<= 100 characters

Example:

Your detailed shipment progress message here

Examples

Responses

🟢200OK

application/json

Body

status

string | null

optional

The status of the response.

Example:

object

order

object

required

Detailed information about the order.

integer

required

The unique identifier for the order.

Example:

25304285

code

string

optional

The code associated with the order.

Example:

8OVNEhyqcf

store_id

integer

optional

The unique identifier for the store where the order was placed.

Example:

251073

order_url

string <uri>

optional

The URL link to the order's invoice.

Example:

https://zid.store/osama/o/6IJWXOYLuR/inv

store_name

string

optional

The name of the store.

Example:

Osama's Store

shipping_method_code

string

optional

The code representing the shipping method used for the order.

Example:

custom

store_url

string <uri>

optional

The URL link to the store.

Example:

https://zid.store/osama/

order_status

object

required

The current status of the order.

currency_code

string

optional

The code representing the currency used for the order.

Example:

KWD

is_marketplace_order

boolean

optional

Indicates whether the order originates from a marketplace platform.

Default:

false

customer

object

required

Information about the customer who placed the order.

shipping

object

required

Shipping details for the order.

payment

object

required

Payment details for the order.

is_potential_fraud

boolean

optional

Flags the order as potentially fraudulent.

Default:

false

created_at

string <date-time>

optional

The date and time when the order was created.

Example:

2023-07-04 09:12:36

updated_at

string <date-time>

optional

The date and time when the order was last updated.

Example:

2023-07-04 09:14:28

invoice_link

string <uri>

optional

URL to the downloadable PDF invoice for the order.

Example:

https://zid-testing-907587157081.s3-accelerate.amazonaws.com/pdf/order_44834593.pdf

products_count

integer

optional

The total number of products in the order.

Example:

products_sum_total_string

string

optional

The total sum of all products in the order in a human-readable format.

Example:

30.00 SAR

language

string

optional

The language used to display the order's page.

Example:

histories

array [object {8}]

optional

A list of historical records associated with the order.

is_reactivated

boolean

optional

Indicates if the order was previously canceled and reactivated.

Example:

false

return_policy

string

optional

Description of the return policy.

Example:

Returns are accepted within 14 days of receipt.

packages_count

integer

optional

The number of packages in the order.

Example:

invoice_settings

object

optional

message

object

optional

Message about the response status.

type

string

optional

The type of the message.

Example:

object

code

string | null

optional

The code associated with the message.

Example:

200

name

string | null

optional

The name of the message.

Example:

Success

description

string | null

optional

A detailed description of the message.

Example:

Order details retrieved successfully.