Order - Zid Docs

Currency Handling for Orders

When the store currency, order currency, and the currency of the shipping address (for cash on delivery) are different, partners must convert the order total to the appropriate currency. The order details already provide both the currency type and the conversion rate, making it easy to apply the conversion when necessary. This ensures that the correct amount is processed smoothly, even when multiple currencies are involved.

Email Handling in Webhook Payloads for Shipping Partners
Some webhook payloads may include placeholder email addresses that are not deliverable. These addresses are operational placeholders and will not reach customers.

Order

integer

optional

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

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

optional

The URL link to the store.

Example:

https://zid.store/osama/

order_status

object (OrderStatus)

optional

name

string

required

The human-readable status name of the order. This string is displayed on the order's page and the Merchant dashboard.

Example:

Delivery in progress

code

enum<string>

required

The status code of the order. Each code represents a specific state of the order:

new: The order has been recently created.

failed: The order transaction failed.

refunded: The order has been refunded (typically by the merchant).

reversed: The order payment has been reversed (typically by the payment provider or the bank).

chargeback: A chargeback has been initiated for the order.

expired: The order has expired due to non-payment.

processed: The order has been processed.

voided: The order has been voided.

ready: The order is ready for shipment.

10.

reverse_in_progress: The order is in the process of being reversed.

11.

preparing: The order is being prepared for shipment.

12.

indelivery: The order is currently in delivery.

13.

delivered: The order has been delivered.

14.

cancelled: The order has been cancelled.

15.

denied: The order has been denied.

16.

canceledReversal: The reversal of the order has been canceled.

Allowed values:

newfailedrefundedreversedchargebackexpiredprocessedvoidedreadyprocessingReversepreparinginDeliverydeliveredcancelleddeniedcanceledReversal

Example:

delivered

currency_code

string

optional

The code representing the currency used for the order.

Example:

KWD

is_marketplace_order

boolean

optional

The is_marketplace_order property indicates whether the order originates from a marketplace. When set to true, it signifies that the order was placed through a third-party marketplace platform rather than directly through the store's website.

Default:

false

customer

object (OrderCustomer)

optional

string

required

The unique identifier of the customer who placed the order.

Example:

2083543

name

string

optional

The name of the customer. (Masked if is_marketplace_order is true)

Example:

Osama

string

optional

The email address of the customer. (Masked if is_marketplace_order is true)

Example:

example.user@email.com

mobile

string

optional

The phone number of the customer. (Masked if is_marketplace_order is true)

Example:

+966501234567

note

string

optional

Any note for the customer.

Example:

" "

verified

string

required

Indicates if the customer’s account is verified. (1 for verified, 0 otherwise)

Example:

type

string

required

Specifies the type of customer, such as "individual" or "business."

Example:

individual

shipping

object (OrderShipping)

optional

method

object (OrderShippingMethod)

optional

address

object (OrderShippingAddress)

optional

products

object

optional

is_external_product

boolean

optional

Default:

true

null

optional

Set to null if is_external_product is true.

parent_id

null

optional

Set to null if is_external_product is true.

parent_name

string

optional

Example:

سماعات بلوتوث

sku

string

required

A unique stock-keeping unit identifier for the product.

Example:

Z.3.1726750799757576

barcode

null

required

The barcode number associated with the product.

custom_fields

array[string]

required

An array of custom attributes or metadata associated with the product.

quantity

string

optional

Example:

weight

string

optional

Example:

150

net_price_with_additions

string

optional

Example:

price_with_additions

string

optional

Example:

net_sale_price

null

required

The net sale price of the product after discounts.

gross_sale_price

null

required

The gross sale price of the product before discounts.

price_before

null

required

The product price before any discounts or adjustments.

total_before

null

required

The total value for the product line before adjustments.

gross_additions_price

null

required

The gross price of additional items associated with the product.

tax_percentage

string

required

The percentage of tax applied to the product.

Example:

0.12

tax_amount_string_per_item

string

required

The tax amount per item as a formatted string.

Example:

0.000 KWD

images

array[string]

required

An array of image URLs for the product with various sizes (e.g., thumbnail, small, medium, large).

has_different_consignee

boolean

optional

Indicates if the consignee is different from the customer.

Example:

false

is_guest_customer

boolean

optional

Indicates if the order was placed by a guest customer.

Example:

false

is_gift_order

boolean

optional

Indicates if the order is a gift.

Example:

false

gift_card_details

object

optional

Details of any gift card associated with the order.

card_design

string

optional

The design of the gift card.

Example:

Birthday Theme

gift_message

string

optional

A message associated with the gift card.

Example:

Happy Birthday, Ahmed! Wishing you all the best.

media_link

string

optional

A link to any media associated with the gift card, such as an image or video.

Example:

https://example.com/gift_card_image.jpg

receiver_name

string

optional

The name of the person receiving the gift card.

Example:

Ahmed Al-Salem

sender_name

string

optional

The name of the person sending the gift card.

Example:

Fatima Al-Rashed

is_quick_checkout_order

boolean

required

ndicates whether the order was placed using a quick checkout feature.

Default:

false

order_total

string

optional

The total amount of the order.

Example:

6.00000000000000

order_total_string

string

optional

The total amount of the order in a human-readable format.

Example:

6.00 KWD

has_different_transaction_currency

boolean

optional

Indicates if the transaction currency is different from the order currency.

Example:

true

transaction_reference

string

optional

The reference number for the transaction.

Example:

TRN-123456

transaction_amount

number

optional

The amount of the transaction.

Example:

transaction_amount_string

string

optional

The amount of the transaction in a human-readable format.

Example:

60.00 SAR

issue_date

string

optional

The date and time when the order was issued.

Example:

04-07-2023 | 12:12 م

payment_status

enum<string>

optional

The payment status of the order.

paid: Payment has successfully completed.

pending: Payment is still pending or hasn't been made yet.

refunded: Payment has been refunded to the Customer.

voided: Payment has been voided or canceled.

Allowed values:

paidpendingrefundedvoided

Example:

paid

is_potential_fraud

boolean

required

Flags the order as potentially fraudulent.

Default:

false

payment_status_change

object

optional

Indicates the most recent change in the payment status of the order,
by specifiying the previous (old) and the updated (new) payment statuses.
This field is particularly relevant for webhook events like order.payment_status.update.
The new status will be paid for successful payments.
The unpaid status represents any payment status other than paid,
including pending, refunded, and voided.
This categorization aligns with the merchant's view of payment statuses
on the Merchant Dashboard.

old

enum<string>

optional

The previous payment status of the order (e.g., 'unpaid').

Allowed values:

paidunpaid

new

enum<string>

optional

The updated payment status of the order (e.g., 'paid').

Allowed values:

paidunpaid

source

enum<string>

optional

The human-readable name indicating the source where the order was created. This field is localized and provides a description of the sale channel, e.g., "Store" or "المتجر الإلكتروني".

Allowed values:

MazeedMazeed ServicesMerchant AdminOrder ApiStoreStore AppZidPOSOthers

Example:

Store

source_code

enum<string>

optional

The code indicating the source or channel of the order. This can be one of several predefined values:

pos: Point of Sale (typically used in physical stores).

catalog: Order was made through a product catalog or online storefront.

md. Order was made from the Merchant Dashboard.

mazeed_marketplace: Order was made through Mazeed.

mazeed: Order was made at the Merchant's Store, but the Customer was redirected from Mazeed to the Merchant's Store.

mobile_app: Order was made through the store's mobile application.

api: Order was made through an API call, typically from third-party integrations or apps.

Allowed values:

poscatalogmdmazeedmazeed_marketplacemobile_appapi

Example:

catalog

is_reseller_transaction

boolean

optional

Indicates if the order was made by a reseller intending to sell the products to end consumers, rather than for personal use.

Example:

false

created_at

string

optional

The date and time when the order was created.

Example:

2023-07-04 09:12:36

updated_at

string

optional

The date and time when the order was last updated.

Example:

2023-07-04 09:14:28

is_on_demand

boolean

required

Specifies if the order is part of an on-demand request.

Default:

false