What you can build

Most integrations combine a few of the paths below. Each path is marked with the token it needs:

• Store token: for your own store, or a store you work on. Generate an access token from the store ID and API secret, then send it in the X-Yotpo-Token header.
• App token: for app partners building one app for many merchants. You get a token per store when a merchant installs your app; see Authenticating with OAuth 2.0.
• Public: storefront endpoints that need only the store ID, so you can call them from browser code.

Sync orders so review requests go out (store token)

Send each order and its fulfillment. Yotpo sends review requests only after a fulfillment with status: success and a fulfillment_date.

• Start with: Sync an order and its fulfillment
• Go deeper: Order custom properties (including suppress_review_request), Idempotency for safe retries
• Reference: Create order, Update order, Create order fulfillment, Retrieve orders

📘

Sending everything in one call

Send aggregated order info takes the order, customer, products and fulfillments in a single request, and creates products that don't exist yet.

Sync your product catalog (store token)

Products come first: orders and reviews refer to them by external_id.

• Start with: Initial store sync
• Go deeper: Product identifiers, Working with entity identifiers
• Reference: Create product, Update product, Retrieve products, Create product variant, Create collection, Add product to collection

Sync customers (store token)

Customers are created or updated by external_id or email, so the same call is safe to re-run in a sync job.

• Start with: Initial store sync (step 2)
• Go deeper: Customer properties, including the Reviews and Loyalty summaries
• Reference: Create or update customer, Retrieve customers

Install your app and make your first call (app token)

Every partner app starts here: the merchant installs your app, you exchange the install code for an access token, and you call the merchant's store.

• Start with: Authenticating with OAuth 2.0, then Generate Access Token.
• Then: send the token in the X-Yotpo-Token header. Working with entity identifiers explains how to go from the merchant's product or order IDs to Yotpo IDs.
• Before launch: support both ways to uninstall, your own button (Remove Application) and the App Disconnected event. Then certify and launch your integration.

Show reviews and star ratings on a storefront (public)

Render reviews in your own components: product pages, category pages, search results, mobile apps and recommendation widgets.

• Start with: Display product reviews on a product page and Show star ratings across a category page.
• Add: Search and filter reviews, Show an AI review summary and smart topics, Show a featured reviews carousel.
• Guides: Search & Merchandising, Product Recommendations, Mobile Apps.
• Reference: Retrieve product reviews, Retrieve bottomline scores.

Show loyalty points on product pages (public)

Show "Earn X points" for each product and variant, based on the store's loyalty earning rules.

• Start with: Show loyalty points on a product page.
• Reference: Product Potential Points. For points that include a signed-in shopper's VIP tier, Authenticated Product Potential Points.

Make reviews readable by search engines and AI crawlers (public)

Put ratings and reviews in the page source so search engines and AI assistants can read them.

• Start with: Add review content for AI crawlers.
• Reference: Retrieve LLM schema.

Bring reviews and Q&A into your platform (app token)

Use review content in emails and flows, show it next to customer records, or analyze it in a BI tool or CDP.

• Guides: Email Marketing & Communications, Service Desk & CRM Integrations, BI, Analytics, and CDP.
• Reference: All Reviews, Product Reviews, Top Reviews, Best Reviews, Best Sentences, Retrieve all questions, Create New Comment.

Read orders, products and customers (app token)

Read the merchant's store data, and update fulfillments so review requests go out at the right time.

• Guides: Shipping & Returns, Common Objects.
• Reference: Retrieve orders, Retrieve order fulfillments, Update order fulfillment, Retrieve products, Retrieve customers, Create or Update Customer. Each reference page shows the app partners host and path.

Reward loyalty actions (app token)

Award points for actions that happen in your product, and show shoppers their balance and referral link.

• Guides: On-site Engagement & Lead Capture, Influencer & Affiliate Marketing.
• Reference: Record Loyalty Customer Action, Adjust Loyalty Customer Points, Retrieve Loyalty Customer Details by Email.

React to events with webhooks (store or app token)

Get review, loyalty and app events pushed to your HTTPS endpoint instead of polling.

• Start with: Set up webhooks end to end. App partners create a target and a filter once for the app, then a store subscription per store.
• Go deeper: About webhooks, Ignoring duplicate events, Webhook events for every event name and payload.
• Reference: Create target, Create filter, Create subscription, Retrieve subscriptions

Migrate from the V1 API (store token)

Move V1 purchase and product calls to their V3 equivalents. V1 calls already accept the same access token in the X-Yotpo-Token header.

• Start with: Migrating from V1 to V3
• Go deeper: About authentication, Orders, Products
• Reference: Generate access token, Create order, Create product