Introduction to Customers

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

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

FieldTypeDescription
external_idstringThe identifier of the customer in the shop.
email / customer_emailstringThe email address of the customer.
phone_numberstringThe phone number of the customer in E.164 format.

This number will be used for SMS messaging.
first_namestringThe first name of the customer.
last_namestringThe last name of the customer.
genderstringValid values:
- F (Female)
- M (Male)
- Other
account_created_atdatetimeThe date the account was originally created in the store. Must be in ISO 8601 format (in UTC).
account_updated_atdatetimeThe timestamp when the customer's account was last updated. Must be in ISO 8601 format (in UTC).
account_statusstringThe status of the store account.
Valid values:
- enabled
- disabled
- invited
- declined
default_languagestringThe default language of the customer's account in ISO 639-1 format.
default_currencystringThe default currency for this customer. Must be in ISO 4217 format. See currency codes
channelsobjectAn object containing the customer's marketing consent and timestamp for SMS and email channels.
channels.sms.marketing.consentstringThe SMS marketing consent status for the customer. Possible values: "subscribed", "unsubscribed", "never_subscribed".
channels.sms.marketing.timestampdatetimeThe timestamp for when the customer's SMS marketing consent status was last updated. ISO 8601 format (in UTC).
channels.email.marketing.consentstringThe email marketing consent status for the customer. Possible values: "subscribed", "unsubscribed", "never_subscribed".
channels.email.marketing.timestampdatetimeThe timestamp when the customer's email marketing consent status was last updated. ISO 8601 format (in UTC).
channels.email.marketing.suppressions.suppression_reasonstringThe reason for email suppression (e.g., "Bounced", "Spam Complaint", etc.).
channels.email.marketing.suppressions.timestampdatetimeThe timestamp when the email suppression was applied. ISO 8601 format (in UTC).
tagsstringA comma-separated list of tags associated with the customer (e.g., "vipgold, loyal").
addressobjectAn object containing the customer's address information.
listsarrayAn array of lists the customer belongs to, each containing an ID and a timestamp.
custom_propertiesjsonThe custom customer properties that enrich the customer profile. For example, skin type, hair color, etc.

Yotpo Reviews

FieldTypeDescription
yotpo_ugcobjectAn object containing the customer's user-generated content information.
yotpo_ugc.total_reviewsintegerThe total number of reviews submitted by the customer
yotpo_ugc.avg_product_ratingintegerThe average product rating given by the customer
yotpo_ugc.avg_site_ratingfloatThe average rating of the site/store given by the customer
yotpo_ugc.total_avg_ratingfloatThe total average rating given by the customer (combining products and site/store ratings)
yotpo_ugc.sentiment_avg_sitedoubleThe total average sentiment score given by the customer (combining products and site/store scores). Learn more
yotpo_ugc.top_topicslistAn array of top topics (themes) mentioned in all of the customer's reviews
yotpo_ugc.last_star_ratingintegerThe star rating of the customer's last review
yotpo_ugc.last_review_datedatetimeThe timestamp for when the customer last submitted a review. ISO 8601 format (in UTC)
yotpo_ugc.last_sentimentdoubleThe sentiment score of the customer's last review

Yotpo Loyalty & Referrals

FieldTypeDescription
yotpo_loyaltyobjectAn object containing the customer's loyalty and referrals information
yotpo_loyalty.points_earnedintegerThe total number of loyalty points earned by the customer
yyotpo_loyalty.points_balanceintegerThe current balance of loyalty points for the customer
yotpo_loyalty.last_seen_atdatetimeThe 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_redemptionsintegerThe total number of times the customer has redeemed loyalty points
yotpo_loyalty.total_points_redeemedintegerThe total number of loyalty points redeemed by the customer
yotpo_loyalty.vip_tier_namestringThe name of the customer's current VIP tier status (e.g., "Gold", "Silver", etc.).
yotpo_loyalty.successful_referralsintegerThe total number of successful referrals made by the customer
yotpo_loyalty.referrals_made_and_clickedintegerThe total number of referrals made by the customer and clicked on by others
yotpo_loyalty.is_referred_by_other_customerbooleanIndicates whether the customer was referred by another customer
yotpo_loyalty.points_expire_datedatetimeThe timestamp when the customer's loyalty points are set to expire. ISO 8601 format (in UTC)
yotpo_loyalty.credit_balance_amountintegerThe amount of store credit available to the customer in the default currency of the store
yotpo_loyalty.credit_balance_customer_currencystringThe store credit amount in the customer's preferred currency
yotpo_loyalty.is_opt_inbooleanIndicates whether the customer has opted into the loyalty program
yotpo_loyalty.opt_in_datedatetimeThe timestamp for when the customer opted into the loyalty program. ISO 8601 format (in UTC)
yotpo_loyalty.opt_out_datedatetimeThe timestamp for when the customer opted out of the loyalty program. ISO 8601 format (in UTC)
yotpo_loyalty.has_store_accountbooleanIndicates whether the customer has a store account
yotpo_loyalty.referred_by_customerstringThe email address of the customer who referred this customer to the loyalty program
yotpo_loyalty.vip_entry_datedatetimeThe timestamp for when the customer entered the VIP tier. ISO 8601 format (in UTC)
yotpo_loyalty.vip_expiration_datedatetimeThe timestamp for when the customer's VIP tier membership is set to expire. ISO 8601 format (in UTC)

Yotpo SMS

FieldTypeDescription
yotpo_smsobjectAn object containing the customer's SMS information
yotpo_sms.last_engageddatetimeThe timestamp for when the customer was last engaged via SMS. ISO 8601 format (in UTC)
yotpo_sms.last_converteddatetimeThe timestamp for when the customer last converted via SMS. ISO 8601 format (in UTC)
yotpo_sms.response_messagesarrayAn array of response messages from SMS campaigns, each containing an ID, keyword, flow ID, and timestamp
yotpo_sms.campaignsarrayAn array of SMS campaigns, each containing an ID, conversion status, and click status
yotpo_sms.flowsarrayAn array of SMS flows, each containing an ID, open status, conversion status, and click status
yotpo_sms.last_sentdatetimeThe timestamp for when the last SMS was sent to the customer. ISO 8601 format (in UTC)

Yotpo Email

FieldTypeDescription
yotpo_emailobjectAn object containing the customer's email information
yotpo_email.last_sentdatetimeThe timestamp for when the customer's last email was sent. ISO 8601 format (in UTC)
yotpo_email.last_promotional_sentdatetimeThe timestamp for when the customer's last promotional email was sent. ISO 8601 format (in UTC)
yotpo_email.last_delivereddatetimeThe timestamp for when the customer last opened an email. ISO 8601 format (in UTC)
yotpo_email.last_engageddatetimeThe timestamp for when the customer was last engaged via email. ISO 8601 format (in UTC)
yotpo_email.last_converteddatetimeThe timestamp for when the customer last converted via email. ISO 8601 format (in UTC)
yotpo_email.last_spamdatetimeThe timestamp for when the customer's last email was marked as spam. ISO 8601 format (in UTC)
yotpo_email.campaignsarrayAn array of email campaigns, each containing an ID, open status, and click status
yotpo_email.flowsarrayAn array of email flows, each containing an ID and conversion status

Yotpo Subscriptions

FieldTypeDescription
yotpo_subscriptionsarrayAn array of active subscriptions, each containing external product and variant IDs
yotpo_subscriptions.paused_subscriptionsarrayAn array of paused subscriptions, each containing external product and variant IDs
yotpo_subscriptions.failed_subscriptionsarrayAn array of failed subscriptions, each containing external product and variant IDs
yotpo_subscriptions.expired_subscriptionsarrayAn array of expired subscriptions, each containing external product and variant IDs
yotpo_subscriptions.canceled_subscriptionsarrayAn array of canceled subscriptions, each containing external product and variant IDs