About orders

Sync your store orders to Yotpo.

📘

Orders endpoints are available for Reviews and SMS Marketing.

  • For Reviews, use orders to help generate more reviews from past shoppers.
  • For SMS Marketing, use orders to trigger messaging automations.

Order endpoints

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.

FieldTypeDescription
external_idstringThe merchant's unique ID for the order.
yotpo_idlongThe ID generated by Yotpo for the order. This value is read-only.
order_namestringThe 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_datedatetimeThe 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_tokenstringThe ID of the checkout that is associated with the order.
payment_methodstringThe payment method used to pay for the order. For example, "Visa".
Max. length: 64 characters
total_pricedoubleThe sum of all line item prices, discounts, shipping, taxes, and tips. Uses the shop currency.
subtotal_pricedoubleThe price of the order after discounts but before shipping, taxes, and tips. Uses the shop currency.
currencystringThe currency in which the order was made. Must be valid ISO code of 3 characters. See currency codes
landing_site_urlstringThe URL for the page where the buyer landed when they entered the shop.
payment_statusstringThe status of payments associated with the order.
Valid values:
- pending
- authorized
- partially_paid
- paid
- partially_refunded
- refunded
- voided
cancellationobjectThe cancellation info object.
See cancellation properties below.
customerobjectInformation about the customer.
See customer checkout information object description
billing_addressobjectThe billing address for this order.
See address object description
shipping_addressobjectThe shipping address for this order. See address object description
custom_propertiesobjectA key-value set of additional properties. See custom properties below.

Max. properties: 100
fulfillmentsarray of objectsLine 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_itemsarray of objectsEach 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_atdatetimeThe time the order was first synced to Yotpo. This value is read-only.
updated_atdatetimeThe 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.

FieldTypeDescription
cancellation_date
(required)
datetimeWhere 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 nameTypeDescription
suppress_review_requestbooleanWhen 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_usedbooleanIndicates if a coupon was used in the purchase (review metadata).
delivery_typestringThe type of shipping or delivery used (review metadata).
customer_statestringThe state the customer is located in (review metadata).
Max. length: 64 characters
customer_countrystringThe 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_addressstringThe customer's home address (review metadata).
customer_phonenumberstringThe customer's phone number in E.164 format (review metadata).
Max. length: 64 characters
customstringAny 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 nameTypeDescription
suppress_review_requestbooleanWhen set to TRUE, prevents Yotpo from sending out automatic review requests for specific products in an order.
colorstringThe color of the line item's product (review metadata).
sizestringThe size of the line item's product (review metadata).
vendorstringThe vendor of the line item's product (review metadata).
materialstringThe material of the line item's product (review metadata).
modelstringThe model of the line item's product (review metadata).
coupon_usedbooleanIndicates if a coupon was used in the purchase of the specific line item (review metadata).
customstringAny 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.