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.

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.