Use Orders and fulfillments endpoints to sync orders and fulfilments to Yotpo.
Orders endpoints are available for Reviews.
- Help generate more reviews from past shoppers
- Use order fulfillments to time review requests
Orders and fulfillments endpoints
- Retrieve Orders - Retrieve a list of all available orders
- Retrieve Order Fulfillments - Retrieve a list of fulfillments for an order
- Update Order Fulfillment - Update an order fulfillment
Orders 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. |
Orders 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. |
Orders 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). |
Order fulfillment properties
Listed below are all of the available properties for fulfillments. 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 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 info
| Field | Type | Description |
|---|---|---|
| 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. |
Fulfilled Items
| Field | Type | Description |
|---|---|---|
| external_product_id | string | The merchant's unique ID for the product. |
| quantity | integer | The quantity actually fulfilled. |
Please note:
You can display a maximum of 10 metadata-related filters on-site at any time.