Yotpo Loyalty

The Yotpo Loyalty integration brings your loyalty program data into a Marketing project from Data hub. Use it to segment customers on points, VIP tier, and expiry dates, and to trigger scenarios from loyalty events such as coupons, tier changes, and referrals.

Bloomreach imports each customer's current loyalty data once, then keeps it current in real time. To set it up, authorize the Bloomreach app once in Yotpo.

Prerequisites

Before you begin, ensure you have the following.

Yotpo

• An active Yotpo Loyalty program on any Yotpo plan.
• A Yotpo user with Integrations access (Owner, Admin, Manager, or Staff (Legacy)) who can authorize apps for the store in the Yotpo integrations center.

Data hub and Marketing

• Permission in Data hub to create and manage Yotpo integrations and to start imports.
• Permission in the Marketing project to create API groups, read API keys, and read project schemas. Setup creates a private API group, so projects without these permissions are disabled in the project list.
• A customer ID in the project for the Yotpo email address. Setup offers only IDs that already exist.
• Room under the project's customer property limit. The settings show the integration's usage.

Set up the integration

You can start from Data hub or from Yotpo.

1. In Bloomreach, go to Data hub > Integrations.
2. Click + Add new integration and select Yotpo.
3. Enter a name for the integration and choose the Marketing project that receives the loyalty data.
4. Click Connect Yotpo and authorize the Bloomreach app in Yotpo within 15 minutes. If the attempt expires, click Connect Yotpo again.

In Yotpo:

1. Choose the store you want to connect and click Continue.
2. Wait for Yotpo to return you to Data hub. Bloomreach creates the integration only after Yotpo confirms, and stores the access token encrypted.

Once the setup is complete, the Data hub page shows your Yotpo account ID and you can configure the following:

When you're done, click Save to start importing data.

Data import

Saving starts the first import and the real-time sync of your Yotpo Loyalty data.

When you save:

• Bloomreach creates a private event stream in the project.
• The import starts once the webhooks are registered.
• The page shows a running count of customers.
• Webhooks flow during the import, and newer webhook data always wins.
• After the import, each webhook that names a customer carries their full loyalty state, so any loyalty activity refreshes their properties.
• Bloomreach keeps the newest value of each property, based on Yotpo's publish time.
• Enabled topics are also tracked as events.

Add birthday, anniversary, and referral link for existing customers

Yotpo's customer API doesn't return birthday, anniversary, or the personal referral link, so the import skips them. To add them for customers who were in Yotpo before you connected, import them from a Yotpo customer export. You can add any other Yotpo field the integration doesn't send the same way.

Export customers from Yotpo

1. In Yotpo Loyalty, go to Customers.
2. Click Export all. Yotpo emails you the file.

The export includes the following columns:

• birth_month, birth_day, and birth_year
• Month, day, and year for the anniversary
• referral_link

The year columns are empty when the customer didn't provide a year.

Prepare the file

Add these columns to the file before you import it:

In a spreadsheet, use this formula to build birthday:

=(DATE(IF(AND(ISNUMBER(birth_year), birth_year >= 1900), birth_year, 1904), birth_month, birth_day) - DATE(1970, 1, 1)) * 86400 + 43200

For example:

• 12 June 1990 becomes 645192000.
• 12 June without a year becomes -2068718400.

Import the file

1. Import the file as a customer import. For more information, see Import customers.
2. Tag the email column with the customer ID you mapped to Email in the integration.
3. Map update_timestamp as the update timestamp.
4. Name the properties with your integration prefix, for example loyalty_birthday, loyalty_anniversary_date, and loyalty_referral_link.
5. Set the type of the two date columns to date.

Manage the integration

The integration page in Data hub shows the connection and import status. Changes to your settings apply from the next webhook after you save.

• Import again: re-reads every customer after a finished import.
• Retry import: resumes a failed import where it stopped, or starts over if the settings changed.
• Remove: revokes Bloomreach access in Yotpo, which stops the webhooks. You can connect the store again afterward. Removing an integration doesn’t delete any data, it only disconnects your Yotpo account.

Limitations

Yotpo program and store

• Only Yotpo Loyalty is supported. Yotpo Reviews and actions that change Yotpo data, such as awarding points, aren't included.
• You can connect one integration per Yotpo store. If another integration holds the store, the connection fails with an already connected message.
• You can connect several Yotpo stores to the same Marketing project. We recommend a different prefix for each store.
• The new member reward event is tracked only when the New Member Reward earning rule is active in Yotpo.

Imported data

• Customers without an email address are skipped.
• Yotpo's customer API doesn't return birthday, anniversary, or the personal referral link, so the import doesn't include them. They fill in from webhooks as customers become active. To add them for existing customers, see Add birthday, anniversary, and referral link for existing customers.
• The next expiring batch of points is in neither the Yotpo customer API nor the customer export.

Settings

• Identifiers and the consent category can't change after the first import.
• The prefix is fixed once you save, unless the import failed.
• Turning a property or event off stops future updates. Data already sent stays.
• Events can be turned on or off, but not renamed or remapped.
• New fields stay off until you turn them on.

Consents and personal data

• With a consent category mapped, Yotpo loyalty program opt-ins and opt-outs are tracked as consent events in real time. The first import also records the current opt-in of existing members. Later imports don't repeat it.
• A Yotpo opt-in means the customer joined the loyalty program, not that they agreed to receive marketing email. Map loyalty opt-ins to a dedicated consent category, not to your email marketing category, so they don't count as marketing consent.
• The integration processes personal data, and events carry email addresses.

Events and delivery

• During a large import, real-time updates for that store can arrive late.

Changes from the existing Yotpo integration

This integration replaces the existing Yotpo Loyalty integration in Marketing. Before you switch, check these changes. For the existing setup, see Yotpo Loyalty.

• Event and property names change. Only the consent event keeps its name. For example, yotpo_loyalty_points_balance becomes loyalty_points_balance.
• The integration_type value changes from yotpo_loyalty to yotpo.
• You need to choose the consent category again.
• A mapped External Customer ID becomes an identifier and can merge profiles that share it.

Troubleshooting

Connection to Yotpo failed

Bloomreach can't reach Yotpo. Click Connect Yotpo to authorize again. Your settings stay.

Disconnected

Disconnected means the app was removed in Yotpo, so nothing syncs. Remove the integration and create it again, or contact Bloomreach Support.

Already connected warning message

Another integration already holds the Yotpo store, and a store can have only one integration. A Yotpo store can have only one integration, which prevents duplicate data. If you see this message, the store is already connected to another integration.

Birthday, anniversary, or referral link is empty

These fields aren't part of the first import, because Yotpo's customer API doesn't return them. They fill in as customers become active. To add them for existing customers, see Add birthday, anniversary, and referral link for existing customers.

Next steps

Your Yotpo Loyalty data now flows into your Marketing project. From day one, you can segment on points balance, VIP tier, and points expiry date. Events add triggers for scenarios such as:

• Points expiry: remind customers how many points expire and when.
• Inactive customers: nudge customers who are close to a reward or can already claim one.
• Coupons: send the code the coupon event carries from a redemption, campaign, or VIP tier reward.
• VIP tiers: congratulate customers on a new tier, and warn them 30, 14, or 7 days before it expires.
• Referrals: send the referred friend an invite and a reminder, and thank the referrer after the friend's qualifying purchase.
• Birthdays and anniversaries: send reward messages when Yotpo issues the reward.
• Joining and leaving: welcome customers when they join the program and win them back when they leave.

Invite and reminder events are tracked on the referred friend, so you can email the friend. Completed referrals are tracked on the referrer.