📘
Orders endpoints are available for Yotpo Reviews.

Use orders to help generate more reviews from past shoppers

Order endpoints

Create order - Create an order in your Yotpo store
Update order - Update an order in your Yotpo store
Retrieve orders - Retrieve a list of orders for your Yotpo store
Retrieve orders by ID - Retrieves all of the details of a specific order using its Yotpo ID

Order properties

Listed below are all of the available properties for orders. To see which properties are required per endpoint, refer to the endpoint pages below.

Field	Type	Description
external_id	string	The merchant's unique ID for the order.
yotpo_id	long	The ID generated by Yotpo for the order. This value is read-only.
order_name	string	The human-readable identifier of the order that will be used when communicating with the customer, for example, for review requests. If omitted, the `external_id` will be used for external communication.
order_date	datetime	The date the order was created in the store. It is not possible to send an automatic email request for orders older than 6 months.
checkout_token	string	The ID of the checkout that is associated with the order.
payment_method	string	The payment method used to pay for the order. For example, "Visa". Max. length: 64 characters
total_price	double	The sum of all line item prices, discounts, shipping, taxes, and tips. Uses the shop currency.
subtotal_price	double	The price of the order after discounts but before shipping, taxes, and tips. Uses the shop currency.
currency	string	The currency in which the order was made. Must be valid ISO code of 3 characters. See currency codes
landing_site_url	string	The URL for the page where the buyer landed when they entered the shop.
payment_status	string	The status of payments associated with the order. Valid values: pending authorized partially_paid paid partially_refunded refunded voided
cancellation	object	The cancellation info object. See cancellation properties below.
customer	object	Information about the customer. See customer checkout information object description
billing_address	object	The billing address for this order. See address object description
shipping_address	object	The shipping address for this order. See address object description
custom_properties	object	A key-value set of additional properties. See custom properties below. Max. properties: 100
fulfillments	array of objects	Line items within an order may be fulfilled separately. All fulfillment actions related to the order can be synced to Yotpo. This allows Yotpo to trigger messaging automations or product review requests at the right moment. We'll send out review requests only for fulfilled orders. You can set your order status by using the same order creation endpoint, or as a separate API call. Make sure you include the following fields: fulfillment_date, fulfillment_status=success Providing a fulfillment with an external product ID that is not included in the order will result in a bad request. See order fulfillments Max. objects: 100
line_items	array of objects	Each order consists of one or more line items. A line item describes the products purchased and the desired quantity. The external product ID provided in a line item must refer to a product already synced to Yotpo. Providing an unknown ID will result in a bad request. Each line item included in an order must refer to a unique product ID. To indicate that an order includes more than 1 item of the same product, use the quantity field. Line items can be added to an existing order using the update order endpoint. Line items cannot be removed from an order after they are created. To indicate that a line item was canceled (in case of partial order fulfillment), you can update the order fulfillments array, and mark the cancelled items with a "canceled" fulfillment status. See line item object description Max. objects: 500
created_at	datetime	The time the order was first synced to Yotpo. This value is read-only.
updated_at	datetime	The time the order was last updated in Yotpo. This value is read-only.

Cancellation properties

These are properties relating to when an order is cancelled.

Field	Type	Description
cancellation_date (required)	datetime	Where the order was cancelled, the date on which it was cancelled.

Custom properties

You can use custom properties to do the following:

Suppress review requests for orders or specific products in an order
Sync reviews metadata upon order creation, allowing shoppers to filter reviews according to each custom property type
Pre-sort and/or pre-filter your Reviews Widget according to the properties you configure
Reflect this data in-line within each review

Order custom properties:

These are custom properties related to the order. If you want to update custom properties for a customer or product, you should refer to the relevant endpoints.

Property name	Type	Description
suppress_review_request	boolean	When set to TRUE, prevents Yotpo from sending out automatic review requests for a specific order. To suppress review requests for specific products, add this flag only to the relevant line items. See line item custom properties below.
coupon_used	boolean	Indicates if a coupon was used in the purchase (review metadata).
delivery_type	string	The type of shipping or delivery used (review metadata).
customer_state	string	The state the customer is located in (review metadata). Max. length: 64 characters
customer_country	string	The country the customer is located in (review metadata). Must be valid ISO code of 2 characters. Default value: US. See country codes Max. length: 64 characters Required if you are using Google seller ratings and gather site reviews from outside of the US.
customer_address	string	The customer's home address (review metadata).
customer_phonenumber	string	The customer's phone number in E.164 format (review metadata). Max. length: 64 characters
custom	string	Any other information you want to link to the order (review metadata).

Line item custom properties:

These are custom properties related to the line item of the order.

Property name	Type	Description
suppress_review_request	boolean	When set to TRUE, prevents Yotpo from sending out automatic review requests for specific products in an order.
color	string	The color of the line item's product (review metadata).
size	string	The size of the line item's product (review metadata).
vendor	string	The vendor of the line item's product (review metadata).
material	string	The material of the line item's product (review metadata).
model	string	The model of the line item's product (review metadata).
coupon_used	boolean	Indicates if a coupon was used in the purchase of the specific line item (review metadata).
custom	string	Any other information you want to link to the line item (review metadata).

🚧
Please note:

You can display a maximum of 10 metadata-related filters on-site at any time.