Introduction to Orders and Fulfillments

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_date (required)

datetime

Where the order was cancelled, the date on which it was cancelled.

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).

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).

external_id

string

The merchant's unique ID for the fulfillment.

fulfillment_date

datetime

The date the fulfillment was created.

Required for sending review requests.

status

string

The status of the fulfillment.
Valid values:

• pending
• open
• success
• cancelled
• error
• failure

Required for sending review requests (must be set to "success").

yotpo_id

integer

The ID generated by Yotpo for the fulfillment. This field is read-only.

shipment_info

object

The shipping info object. See Shipment info below.

fulfilled_items

array of objects

Information about the specific items fulfilled (i.e. product and quantity). Items within an order may be fulfilled separately. All fullfillment 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.

Providing a fulfillment with an external product ID that is not included in the order will result in a bad request.

created_at

datetime

The time the fulfillment was first synced to Yotpo. This field is read-only.

updated_at

datetime

The time the fulfillment was last updated in Yotpo. This field is read-only.

shipment_status

string

The current shipment status of the fulfillment.
Valid values:

• label_printed
• label_purchased
• attempted_delivery
• ready_for_pickup
• confirmed
• in_transit
• out_for_delivery
• delivered
• failure

tracking_company

string

The name of the tracking company.

tracking_url

string

The URL of the tracking page for the shipment.

tracking_number

string

The tracking number as provided by the shipping company.

external_product_id

string

The merchant's unique ID for the product.

quantity

integer

The quantity actually fulfilled.