Use Customers endpoints to sync store customers to Yotpo. You can sync information such as contact details, order history, and whether the customer agreed to receive marketing messaging.
Good to know
- While you can create customers explicitly using the below endpoints, in certain scenarios customer records can also be enriched implicitly by Yotpo after interacting with a customer. For example, Yotpo will automatically enrich customer records for shoppers who reviewed a product or engaged with Loyalty features.
- To manage subscriptions for various types of messaging, for example, SMS messaging, review requests, etc., dedicated endpoints should be used.
Customer endpoints
- Create or Update Customer - Create/update a customer in the Yotpo platform
- Create or Update Custom Customer Event - Allows the sending of Yotpo customer events in order to trigger flows and update customers in Yotpo SMS & Email
- Retrieve Customers - Retrieve a list of past and existing customers as they appear in Yotpo SMS & Email
- Retrieve Customer Details by Email - Retrieve details for a specific customer for Yotpo Reviews and Yotpo Loyalty & Referrals (updates every 24 hours)
- Retrieve Customer Details by Date - Retrieve all customers that were updated since a specific date for Yotpo Reviews and Yotpo Loyalty & Referrals (updates every 24 hours)
- Retrieve Loyalty Customer Details by Email - Retrieve a customer record from Yotpo Loyalty & Referrals (updated in real-time)
Customer properties
Please note that support for given operators and fields is highly specific to each endpoint. Not all properties are relevant for every endpoint, and some field names may differ slightly across endpoints.
General customer properties
| Field | Type | Description |
|---|---|---|
| external_id | string | The identifier of the customer in the shop. |
| email / customer_email | string | The email address of the customer. |
| phone_number | string | The phone number of the customer in E.164 format. This number will be used for SMS messaging. |
| first_name | string | The first name of the customer. |
| last_name | string | The last name of the customer. |
| gender | string | Valid values: - F (Female) - M (Male) - Other |
| account_created_at | datetime | The date the account was originally created in the store. Must be in ISO 8601 format (in UTC). |
| account_updated_at | datetime | The timestamp when the customer's account was last updated. Must be in ISO 8601 format (in UTC). |
| account_status | string | The status of the store account. Valid values: - enabled - disabled - invited - declined |
| default_language | string | The default language of the customer's account in ISO 639-1 format. |
| default_currency | string | The default currency for this customer. Must be valid ISO code of 3 characters. See currency codes |
| accepts_sms_marketing | boolean | A flag indicating whether the customer chose to accept SMS marketing messages. Please note that whether or not the customer is ultimately subscribed to messaging may be determined by additional factors. |
| accepts_email_marketing | boolean | A flag indicating whether the customer chose to accept email marketing messages. Please note that whether or not the customer is ultimately subscribed to messaging may be determined by additional factors. |
| channels | object | An object containing the customer's marketing consent and timestamp for SMS and email channels. |
| channels.sms.marketing.consent | string | The SMS marketing consent status for the customer. Possible values: "subscribed", "unsubscribed", "never_subscribed". |
| channels.sms.marketing.timestamp | datetime | The timestamp for when the customer's SMS marketing consent status was last updated. ISO 8601 format (in UTC). |
| channels.email.marketing.consent | string | The email marketing consent status for the customer. Possible values: "subscribed", "unsubscribed", "never_subscribed". |
| channels.email.marketing.timestamp | datetime | The timestamp when the customer's email marketing consent status was last updated. ISO 8601 format (in UTC). |
| channels.email.marketing.suppressions.suppression_reason | string | The reason for email suppression (e.g., "Bounced", "Spam Complaint", etc.). |
| channels.email.marketing.suppressions.timestamp | datetime | The timestamp when the email suppression was applied. ISO 8601 format (in UTC). |
| tags | string | A comma-separated list of tags associated with the customer (e.g., "vipgold, loyal"). |
| address | object | An object containing the customer's address information. |
| lists | array | An array of lists the customer belongs to, each containing an ID and a timestamp. |
| custom_properties | json | The custom customer properties that enrich the customer profile. For example, skin type, hair color, etc. |
Yotpo Reviews
| Field | Type | Description |
|---|---|---|
| yotpo_ugc | object | An object containing the customer's user-generated content information. |
| yotpo_ugc.total_reviews | integer | The total number of reviews submitted by the customer |
| yotpo_ugc.avg_product_rating | integer | The average product rating given by the customer |
| yotpo_ugc.avg_site_rating | float | The average rating of the site/store given by the customer |
| yotpo_ugc.total_avg_rating | float | The total average rating given by the customer (combining products and site/store ratings) |
| yotpo_ugc.sentiment_avg_site | double | The total average sentiment score given by the customer (combining products and site/store scores). Learn more |
| yotpo_ugc.top_topics | list | An array of top topics (themes) mentioned in all of the customer's reviews |
| yotpo_ugc.last_star_rating | integer | The star rating of the customer's last review |
| yotpo_ugc.last_review_date | datetime | The timestamp for when the customer last submitted a review. ISO 8601 format (in UTC) |
| yotpo_ugc.last_sentiment | double | The sentiment score of the customer's last review |
Yotpo Loyalty & Referrals
| Field | Type | Description |
|---|---|---|
| yotpo_loyalty | object | An object containing the customer's loyalty and referrals information |
| yotpo_loyalty.points_earned | integer | The total number of loyalty points earned by the customer |
| yyotpo_loyalty.points_balance | integer | The current balance of loyalty points for the customer |
| yotpo_loyalty.last_seen_at | datetime | The timestamp when the customer was last seen or engaged with the loyalty program. This includes making a purchase with your store. ISO 8601 format (in UTC) |
| yotpo_loyalty.total_redemptions | integer | The total number of times the customer has redeemed loyalty points |
| yotpo_loyalty.total_points_redeemed | integer | The total number of loyalty points redeemed by the customer |
| yotpo_loyalty.vip_tier_name | string | The name of the customer's current VIP tier status (e.g., "Gold", "Silver", etc.). |
| yotpo_loyalty.successful_referrals | integer | The total number of successful referrals made by the customer |
| yotpo_loyalty.referrals_made_and_clicked | integer | The total number of referrals made by the customer and clicked on by others |
| yotpo_loyalty.is_referred_by_other_customer | boolean | Indicates whether the customer was referred by another customer |
| yotpo_loyalty.points_expire_date | datetime | The timestamp when the customer's loyalty points are set to expire. ISO 8601 format (in UTC) |
| yotpo_loyalty.credit_balance_amount | integer | The amount of store credit available to the customer in the default currency of the store |
| yotpo_loyalty.credit_balance_customer_currency | string | The store credit amount in the customer's preferred currency |
| yotpo_loyalty.is_opt_in | boolean | Indicates whether the customer has opted into the loyalty program |
| yotpo_loyalty.opt_in_date | datetime | The timestamp for when the customer opted into the loyalty program. ISO 8601 format (in UTC) |
| yotpo_loyalty.opt_out_date | datetime | The timestamp for when the customer opted out of the loyalty program. ISO 8601 format (in UTC) |
| yotpo_loyalty.has_store_account | boolean | Indicates whether the customer has a store account |
| yotpo_loyalty.referred_by_customer | string | The email address of the customer who referred this customer to the loyalty program |
| yotpo_loyalty.vip_entry_date | datetime | The timestamp for when the customer entered the VIP tier. ISO 8601 format (in UTC) |
| yotpo_loyalty.vip_expiration_date | datetime | The timestamp for when the customer's VIP tier membership is set to expire. ISO 8601 format (in UTC) |
Yotpo SMS
| Field | Type | Description |
|---|---|---|
| yotpo_sms | object | An object containing the customer's SMS information |
| yotpo_sms.last_engaged | datetime | The timestamp for when the customer was last engaged via SMS. ISO 8601 format (in UTC) |
| yotpo_sms.last_converted | datetime | The timestamp for when the customer last converted via SMS. ISO 8601 format (in UTC) |
| yotpo_sms.response_messages | array | An array of response messages from SMS campaigns, each containing an ID, keyword, flow ID, and timestamp |
| yotpo_sms.campaigns | array | An array of SMS campaigns, each containing an ID, conversion status, and click status |
Yotpo Email
| Field | Type | Description |
|---|---|---|
| yotpo_email | object | An object containing the customer's email information |
| yotpo_email.last_sent | datetime | The timestamp for when the customer's last email was sent. ISO 8601 format (in UTC) |
| yotpo_email.last_promotional_sent | datetime | The timestamp for when the customer's last promotional email was sent. ISO 8601 format (in UTC) |
| yotpo_email.last_delivered | datetime | The timestamp for when the customer last opened an email. ISO 8601 format (in UTC) |
| yotpo_email.last_engaged | datetime | The timestamp for when the customer was last engaged via email. ISO 8601 format (in UTC) |
| yotpo_email.last_converted | datetime | The timestamp for when the customer last converted via email. ISO 8601 format (in UTC) |
| yotpo_email.last_spam | datetime | The timestamp for when the customer's last email was marked as spam. ISO 8601 format (in UTC) |
| yotpo_email.campaigns | array | An array of email campaigns, each containing an ID, open status, and click status |
| yotpo_email.flows | array | An array of email flows, each containing an ID and conversion status |
Yotpo Subscriptions
| Field | Type | Description |
|---|---|---|
| yotpo_subscriptions | array | An array of active subscriptions, each containing external product and variant IDs |
| yotpo_subscriptions.paused_subscriptions | array | An array of paused subscriptions, each containing external product and variant IDs |
| yotpo_subscriptions.failed_subscriptions | array | An array of failed subscriptions, each containing external product and variant IDs |
| yotpo_subscriptions.expired_subscriptions | array | An array of expired subscriptions, each containing external product and variant IDs |
| yotpo_subscriptions.canceled_subscriptions | array | An array of canceled subscriptions, each containing external product and variant IDs |