# Yotpo API documentation > All Yotpo APIs in one place: Yotpo API V3 (Core, Reviews storefront, Loyalty V3, privacy and webhooks), Loyalty API (V2), Reviews API (V1), the App partners API for apps that merchants install, and the legacy Core API V1. Categories in the sidebar are prefixed by group: "V3 ·", "Loyalty V2 ·", "Reviews V1 ·", "App partners ·" and "Core V1 ·". Every link below is the Markdown version of a page. Endpoint entries start with the HTTP method and full URL; webhook events start with `WEBHOOK` and the event name. ## Key facts - **Which API.** New store integrations (products, orders, customers, webhooks): Yotpo API V3. Showing reviews or loyalty points on a storefront: the V3 Reviews and Loyalty storefront endpoints. Loyalty programs (points, redemptions, referrals): Loyalty API (V2). Review moderation, exports, Q&A and Visual UGC: Reviews API (V1). An app many merchants install: App partners. - **Base URLs.** V3 Core: `https://api.yotpo.com/core/v3/stores/{store_id}/...`. Reviews V1: `https://api.yotpo.com`. Public storefront reads: `https://api-cdn.yotpo.com` (reviews) and `https://storefront.yotpo.com/loyalty` (loyalty points). Loyalty V2: `https://loyalty.yotpo.com/api/v2/...`. App partners: `https://developers.yotpo.com`. Use HTTPS only. - **Authentication.** - `api.yotpo.com` (V3, Reviews V1, Core V1): `POST https://api.yotpo.com/core/v3/stores/{store_id}/access_tokens` with `{"secret": ""}` returns `access_token`. Send it in the `X-Yotpo-Token` header. The same token works for V1 calls. Exceptions: Reviews Insights takes `Authorization: Bearer`, and Custom albums takes `utoken` as a query parameter. - Storefront endpoints need no token. - Loyalty V2: your Loyalty GUID and API key in the `x-guid` and `x-api-key` headers. - App partners: a per-store token from the OAuth 2.0 install flow, sent in `X-Yotpo-Token`. - **Pagination.** V3: `limit` (1 to 100, default 100) and `page_info`; pass `pagination.next_page_info` as `page_info`. Older APIs use `page` and `count` or their own cursors, shown on each endpoint. - **Errors.** Status codes and bodies differ by host; see https://docs.yotpo.com/docs/error-handling.md. There's no sandbox; see https://docs.yotpo.com/docs/testing-your-integration.md. - **Rate limits.** `api.yotpo.com`: 5 requests per second per store, shared by every integration on that store. App partners and Loyalty V2 have their own limits, listed in their guidelines. A `429` carries `Retry-After` (seconds). - **Webhooks.** Create a target (your HTTPS URL), a filter (event names) and a subscription. Every event name and payload: https://docs.yotpo.com/docs/topics.md. - **Privacy requests.** Reviews and Loyalty each have their own check, export and delete endpoints; see https://docs.yotpo.com/reference/about-privacy-api.md. ## Guides · V3 · Getting Started - [What you can build](https://docs.yotpo.com/docs/what-you-can-build.md): Pick the integration you need and follow its path from first call to full reference. - [How to use the Core API](https://docs.yotpo.com/docs/how-to-use.md): The Core API offers 2 different approaches, depending on the setup of your store: - [Guidelines & conventions](https://docs.yotpo.com/docs/guidelines-and-conventions.md): Before you start using the API, we recommend you review these guidelines. - [App key vs. Store ID](https://docs.yotpo.com/docs/store-id-app-key.md): The Store ID (app key) and API secret are unique codes for your account. - [Rate limiting](https://docs.yotpo.com/docs/rate-limiting.md): How to handle rate limits and avoid 429 errors when making API requests. - [Errors](https://docs.yotpo.com/docs/error-handling.md): Every status code the Yotpo APIs return, the real error bodies on each host, and what to do about each one. - [Testing your integration](https://docs.yotpo.com/docs/testing-your-integration.md): How to test against Yotpo without touching real shoppers, which calls have side effects, and a checklist before you go live. - [Idempotency](https://docs.yotpo.com/docs/idempotency.md): Prevent duplicate resources and ensure safe retries when creating orders, products, and customers. - [Working with entity identifiers](https://docs.yotpo.com/docs/working-with-entity-identifiers.md): Orders, products, product variants and collections already have their own IDs in the store's e-commerce platform. In Yotpo, each of them has two IDs: - [Working with custom properties](https://docs.yotpo.com/docs/working-with-custom-properties.md): Some Yotpo entities allow you to enrich the object with custom properties on top of the object schema. - [Connect to Yotpo's MCP Servers](https://docs.yotpo.com/docs/connect-to-yotpo-mcp.md): Connect Claude, Cursor and other MCP-compatible AI clients to Yotpo's MCP servers: the API docs MCP, to look up any Yotpo endpoint while you build, and the Discover MCP, to bring your store's content, analytics and… ## Guides · V3 · Common Objects - [About common objects](https://docs.yotpo.com/docs/common-objects.md): These are common Core API objects used across multiple API operations. - [GTIN](https://docs.yotpo.com/docs/gtin.md): GTINs (Global trade item numbers, often called barcodes) are used to match products with external sources. A main use case for this is syndicating product reviews to other platforms or Google PLA. - [Line item](https://docs.yotpo.com/docs/line-item.md) ## Guides · V3 · Webhooks & Events - [About Webhooks](https://docs.yotpo.com/docs/about-webhook-events.md): Webhooks send you Yotpo events as they happen, so you don't have to poll. For example: - [Webhook events](https://docs.yotpo.com/docs/topics.md): Every event you can subscribe to, with the exact name to put in a filter. ## Guides · Loyalty V2 · How-to Guides - [Integrate Loyalty with a custom or headless store](https://docs.yotpo.com/docs/custom-generic-implementation.md): Run Yotpo Loyalty & Referrals on a store built on a custom or unsupported platform. Send customers, orders and refunds from your server, set up reward codes, and show points in your own UI. ## Guides · Reviews V1 · Getting Started - [What you can build](https://docs.yotpo.com/docs/reviews-what-you-can-build.md): Pick what you want to build and follow the path. Each one starts with a short recipe and links to the guides and reference pages you need next. - [Guidelines & Conventions](https://docs.yotpo.com/docs/reviews-guidelines-and-conventions.md): A quick overview of base URLs, authentication, formats, pagination, rate limits, and error responses in the Yotpo UGC API. - [Store ID and API Secret](https://docs.yotpo.com/docs/finding-your-app-key-and-api-secret.md): Learn where to find the credentials required for authenticating with the Yotpo API. - [Authenticate and make your first call](https://docs.yotpo.com/docs/authenticate-and-make-your-first-call.md): Get an access token, learn which endpoints need it, and send it the way each API expects. - [Reviews V1 errors](https://docs.yotpo.com/docs/errors.md): The status codes the UGC API returns, the error bodies each part of the API sends, and how to handle each one. - [Testing your integration](https://docs.yotpo.com/docs/reviews-testing-your-integration.md): There's no sandbox, so every call reaches a real store. How to test without emailing shoppers or changing live data. ## Guides · Reviews V1 · Documentation - [Yotpo Headless Integration Guide (API-Based)](https://docs.yotpo.com/docs/yotpo-headless-integration-guide-api-based.md): This guide is for developers showing Yotpo reviews and star ratings through the API instead of the default Yotpo widgets. It fits custom headless storefronts (for example React, Vue or Hydrogen). - [Building Custom Reviews Widgets with the Yotpo APIs](https://docs.yotpo.com/docs/building-custom-reviews-widgets-with-the-yotpo-apis-v1-and-v3.md): A best-practices playbook for building your own star ratings, review lists, search, galleries, and review forms. Read with the V3 storefront API, write with v1. ## Guides · App partners · Getting Started - [Welcome](https://docs.yotpo.com/docs/welcome.md): Welcome to Yotpo's Developer Toolkit for Technology Partners! :rocket: :rocket: :rocket: - [Applying to become a Yotpo partner](https://docs.yotpo.com/docs/applying-to-become-a-yotpo-partner.md): To build an integration on top of Yotpo’s technology partner APIs, you’ll need to first apply to become a technology partner. - [Registering your integration & opening a test account](https://docs.yotpo.com/docs/registering-a-new-app.md): If you applied to become a technology partner and received approval from our team, you can now register your app/s and get credentials to use the technology partner APIs. - [Authenticating with OAuth 2.0](https://docs.yotpo.com/docs/authenticating.md): Whenever a shared merchant installs your integration (app) for the first time, a standard OAuth 2.0 flow will be initiated, in which: - [Certifying and launching your integration](https://docs.yotpo.com/docs/certifying-and-launching-your-integration.md): To certify and launch your integration officially in Yotpo, you will be asked to fill out a form with information about your company and the integration for our GTM and tech stakeholders to be able to drive success with… - [Ongoing Partnership & FAQ](https://docs.yotpo.com/docs/ongoing-partnership-faq.md): Once your integration was certified and officially released, we try to provide our official tech partners with the following ongoing benefits: - [Yotpo Postman Collection](https://docs.yotpo.com/docs/yotpo-postman-collection-1.md): Integrating with a new API can be challenging, but we're here to make it easier. Our Postman collection allows you to explore and interact with our API visually, accelerating your development process. ## Guides · App partners · Best Practice Guides - [Email Marketing & Communications](https://docs.yotpo.com/docs/email-marketing-communications.md): This guide details the most popular use cases for integrating reviews, visual user-generated content (UGC), and loyalty and referrals with your marketing communications platform. - [BI, Analytics, and CDP Best Practice Guide](https://docs.yotpo.com/docs/bi-analytics-and-cdp-best-practice-guide.md): This toolkit details how to integrate Yotpo’s products with your BI & Analytics or Customer Data Platform (CDP) to analyze and suggest insightful actions for merchants on both platforms. - [Search & Merchandising](https://docs.yotpo.com/docs/search-integration.md): This guide details how you can incorporate star ratings and top reviews into product results and search results to increase click-through rates and engagement. - [Service Desk & CRM Integrations](https://docs.yotpo.com/docs/service-desk-crm-integrations.md): This guide details the main integration use cases and APIs for Service Desk and CRM partners with Yotpo Reviews and Yotpo Loyalty. - [On-site Engagement & Lead Capture](https://docs.yotpo.com/docs/on-site-engagement-lead-capture.md): This guide details how you can integrate Yotpo Reviews and Yotpo Loyalty & Referrals with your On-site Engagement platform to allow merchants to create truly personalized consumer experiences and fully benefit from both… - [Product Recommendations](https://docs.yotpo.com/docs/product-recommendations.md): This guide details how you can integrate Yotpo Reviews and Yotpo Visual UGC with your Product Recommendation platform or features to add social proof to your experience and increase user engagement for shared merchants. - [Mobile Apps](https://docs.yotpo.com/docs/mobile-apps.md): This guide details the main integration use cases for mobile app integrations. - [Influencer & Affiliate Marketing](https://docs.yotpo.com/docs/influencer-affiliate-marketing.md): This guide details how you can integrate Yotpo Loyalty & Referrals and Yotpo Reviews with your influencer or affiliate marketing platform to ensure you’re engaging with the top tier of your customer base in a more… - [Shipping & Returns Best Practice Guide](https://docs.yotpo.com/docs/shipping-returns-best-practice-guide.md): This toolkit details how you can integrate Yotpo Reviews and Yotpo Loyalty & Referrals with your shipping or returns platform to create seamless consumer experiences that allow merchants to fully benefit from both… ## Recipes - [Authenticate and make your first call](https://docs.yotpo.com/recipes/authenticate-and-make-your-first-call.md): Generate an access token and make your first authenticated request in under a minute. - [Initial store sync](https://docs.yotpo.com/recipes/initial-store-sync.md): Connect your store to Yotpo: sync your first product and customer. - [Sync an order and its fulfillment](https://docs.yotpo.com/recipes/sync-an-order-and-its-fulfillment.md): Create an order and mark it as fulfilled; this powers review requests and purchase-based features. - [Set up webhooks end to end](https://docs.yotpo.com/recipes/set-up-webhooks-end-to-end.md): Get notified when things happen in Yotpo: create a target, filter the events you care about, and subscribe. - [Display product reviews on a product page](https://docs.yotpo.com/recipes/display-product-reviews-on-a-product-page.md): Fetch a product's reviews and star-rating summary, with no authentication needed: everything a PDP requires in two calls. - [Show star ratings across a category page](https://docs.yotpo.com/recipes/show-star-ratings-across-a-category-page.md): Fetch rating bottom lines for your whole catalog in bulk. One public call powers every product card. - [Search and filter reviews](https://docs.yotpo.com/recipes/search-and-filter-reviews.md): Free-text search plus score and photo filters to power a review-search UI on your product page. - [Show an AI review summary and smart topics](https://docs.yotpo.com/recipes/show-an-ai-review-summary-and-smart-topics.md): Display Yotpo's AI-generated review summary and topic chips on a product page, and let shoppers filter reviews by topic. - [Show a featured reviews carousel](https://docs.yotpo.com/recipes/show-a-featured-reviews-carousel.md): Pull Yotpo's top reviews for a product or your whole store to power a carousel on a product page or home page. - [Add review content for AI crawlers](https://docs.yotpo.com/recipes/add-review-content-for-ai-crawlers.md): Inject Yotpo's ready-made review markup into your product page HTML so search and AI crawlers can read it from the page source. - [Create a review](https://docs.yotpo.com/recipes/create-a-review.md): Submit reviews programmatically for custom review forms and post-purchase flows. - [Record an order and award points](https://docs.yotpo.com/recipes/record-an-order-and-award-points.md): The core loyalty loop: record an order and watch the points land. - [Create a customer record](https://docs.yotpo.com/recipes/create-a-customer-record.md): Create a loyalty profile with birthday and anniversary — the foundation for every campaign. - [Refund an order](https://docs.yotpo.com/recipes/refund-an-order.md): Record a refund against an order — earned points are adjusted automatically. - [Redeem points for a reward](https://docs.yotpo.com/recipes/redeem-points-for-a-reward.md): Fetch the available redemption options, then redeem—the reward code is returned in the response. - [Record a custom action](https://docs.yotpo.com/recipes/record-a-custom-action.md): Award points for anything — surveys, reviews, app installs — via custom action campaigns. - [Run a referral flow](https://docs.yotpo.com/recipes/run-a-referral-flow.md): Register a referrer and send them referral invitations. - [Show loyalty points on a product page](https://docs.yotpo.com/recipes/show-loyalty-points-on-a-product-page.md): Show shoppers how many loyalty points each variant earns, in one public call with no token. ## API reference · V3 · Getting Started - [Welcome](https://docs.yotpo.com/reference/welcome.md): Everything you need before your first Core API call. - [About authentication](https://docs.yotpo.com/reference/authentication.md): One access token authenticates every Yotpo API on api.yotpo.com: V3, Reviews V1 and Core V1. Generate it with your store ID and API secret, then send it in the X-Yotpo-Token header. - [Generate Access Token](https://docs.yotpo.com/reference/yotpo-authentication.md): `POST https://api.yotpo.com/core/v3/stores/{store_id}/access_tokens` This endpoint uses your Yotpo Store ID (app_key) and API secret to generate the API access token necessary to authenticate most of Yotpo's API calls. ## API reference · V3 · Orders & Fulfillments - [About orders](https://docs.yotpo.com/reference/orders.md): Sync your store orders to Yotpo. - [Create order](https://docs.yotpo.com/reference/create-order.md): `POST https://api.yotpo.com/core/v3/stores/{store_id}/orders` Creates an order in your Yotpo store. Is not possible to send automatic review request emails for orders that are older than six months. - [Update order](https://docs.yotpo.com/reference/update-order.md): `PATCH https://api.yotpo.com/core/v3/stores/{store_id}/orders/{yotpo_order_id}` Updates an order in your Yotpo store. - [Retrieve orders](https://docs.yotpo.com/reference/retrieve-orders.md): `GET https://api.yotpo.com/core/v3/stores/{store_id}/orders` Retrieves a list of orders for your Yotpo store. - [Retrieve order by ID](https://docs.yotpo.com/reference/retrieve-order-by-id.md): `GET https://api.yotpo.com/core/v3/stores/{store_id}/orders/{yotpo_order_id}` Retrieves all of the details of a specific order using its Yotpo ID. - [About order fulfillments](https://docs.yotpo.com/reference/order-fulfillments.md): Sync your store order fulfillments to Yotpo. Order fulfillments represent a group of one or more items in an order that are to be fulfilled from the same location. - [Create order fulfillment](https://docs.yotpo.com/reference/create-order-fulfillment.md): `POST https://api.yotpo.com/core/v3/stores/{store_id}/orders/{yotpo_order_id}/fulfillments` Creates an order fulfillment in your Yotpo store. - [Update order fulfillment](https://docs.yotpo.com/reference/update-order-fulfillment.md): `PATCH https://api.yotpo.com/core/v3/stores/{store_id}/orders/{yotpo_order_id}/fulfillments/{yotpo_fulfillment_id}` Updates an order fulfillment in your Yotpo store. - [Retrieve order fulfillments](https://docs.yotpo.com/reference/retrieve-order-fulfillments.md): `GET https://api.yotpo.com/core/v3/stores/{store_id}/orders/{yotpo_order_id}/fulfillments` Retrieves a list of fulfillments for an order in your Yotpo store. - [Retrieve fulfillment by ID](https://docs.yotpo.com/reference/retrieve-fulfillment-by-id.md): `GET https://api.yotpo.com/core/v3/stores/{store_id}/orders/{yotpo_order_id}/fulfillments/{yotpo_fulfillment_id}` Retrieves all fulfillments for a specific order using its Yotpo ID. - [About aggregated order info](https://docs.yotpo.com/reference/aggregated-order-info.md): In order to send Yotpo all relevant information regarding the order in one batch, you can use the Register purchase endpoint. - [Send aggregated order info](https://docs.yotpo.com/reference/send-aggregated-order-info.md): `POST https://api.yotpo.com/core/v3/stores/{store_id}/register_purchase` Sends all relevant order information to Yotpo in one batch. ## API reference · V3 · Products & Collections - [About products](https://docs.yotpo.com/reference/products.md): The Product entity allows you to keep your catalog in-sync with Yotpo. - [Create product](https://docs.yotpo.com/reference/create-product.md): `POST https://api.yotpo.com/core/v3/stores/{store_id}/products` Creates a new product within your product catalog. - [Update product](https://docs.yotpo.com/reference/update-product.md): `PATCH https://api.yotpo.com/core/v3/stores/{store_id}/products/{yotpo_product_id}` Update the product information in Yotpo. - [Retrieve products](https://docs.yotpo.com/reference/retrieve-products.md): `GET https://api.yotpo.com/core/v3/stores/{store_id}/products` Retrieves a list of all of your store's products. You can use this endpoint to resolve the Yotpo product ID in order to update it. - [Retrieve product by ID](https://docs.yotpo.com/reference/retrieve-product-by-id.md): `GET https://api.yotpo.com/core/v3/stores/{store_id}/products/{yotpo_product_id}` Retrieves all product information for a specific product using its Yotpo ID. - [About product variants](https://docs.yotpo.com/reference/product-variants.md): Sync your product variants to Yotpo. Add variants to your products in order to represent one version of a product with several options, for example, size, or color. - [Create product variant](https://docs.yotpo.com/reference/create-product-variant.md): `POST https://api.yotpo.com/core/v3/stores/{store_id}/products/{yotpo_product_id}/variants` Creates a new product variant within your product catalog. - [Update product variant](https://docs.yotpo.com/reference/update-product-variant.md): `PATCH https://api.yotpo.com/core/v3/stores/{store_id}/products/{yotpo_product_id}/variants/{yotpo_variant_id}` Updates a product variant within your product catalog. - [Retrieve product variants](https://docs.yotpo.com/reference/retrieve-product-variants.md): `GET https://api.yotpo.com/core/v3/stores/{store_id}/products/{yotpo_product_id}/variants` Retrieves a list of product variants within your product catalog. - [Retrieve product variant by ID](https://docs.yotpo.com/reference/retrieve-product-variant-by-id.md): `GET https://api.yotpo.com/core/v3/stores/{store_id}/products/{yotpo_product_id}/variants/{yotpo_variant_id}` Retrieves a product variant by store ID, product ID, and product variant ID. - [About collections](https://docs.yotpo.com/reference/collections.md): Sync your product collections to Yotpo. A collection is a grouping of products that you can use to make your store easier to browse. - [Create collection](https://docs.yotpo.com/reference/create-collection.md): `POST https://api.yotpo.com/core/v3/stores/{store_id}/collections` Creates a new collection within your product catalog. - [Update collection](https://docs.yotpo.com/reference/update-collection.md): `PATCH https://api.yotpo.com/core/v3/stores/{store_id}/collections/{yotpo_collection_id}` Updates a collection within your product catalog. - [Retrieve collections](https://docs.yotpo.com/reference/retrieve-collections.md): `GET https://api.yotpo.com/core/v3/stores/{store_id}/collections` Retrieves a list of all of your store's collections. - [Add product to collection](https://docs.yotpo.com/reference/add-product-to-collection.md): `POST https://api.yotpo.com/core/v3/stores/{store_id}/collections/{yotpo_collection_id}/products` Adds a product to a collection within your product catalog. - [Retrieve products in collection](https://docs.yotpo.com/reference/retrieve-products-in-collection.md): `GET https://api.yotpo.com/core/v3/stores/{store_id}/collections/{yotpo_collection_id}/products` Retrieves a paginated list of products from a collection in your product catalog. - [Remove product from collection](https://docs.yotpo.com/reference/remove-product-from-collection.md): `DELETE https://api.yotpo.com/core/v3/stores/{store_id}/collections/{yotpo_collection_id}/products` Removes a product from a collection within your product catalog. - [Retrieve list of collections for product](https://docs.yotpo.com/reference/retrieve-list-of-collections-for-product.md): `GET https://api.yotpo.com/core/v3/stores/{store_id}/products/{yotpo_product_id}/collections` Retrieves a paginated list of collections within your product catalog that a product belongs to. ## API reference · V3 · Customers - [About customers](https://docs.yotpo.com/reference/customers.md): Sync your store customers to Yotpo, to be used as contacts for messaging. - [Create or update customer](https://docs.yotpo.com/reference/create-customer.md): `PATCH https://api.yotpo.com/core/v3/stores/{store_id}/customers` Creates a customer in your Yotpo store. - [Retrieve customers](https://docs.yotpo.com/reference/retrieve-customers.md): `GET https://api.yotpo.com/core/v3/stores/{store_id}/customers` Retrieves a list of past and existing customers from your Yotpo store. Use this endpoint to check if a customer was registered successfully with Yotpo. ## API reference · V3 · Reviews - [Retrieve product reviews](https://docs.yotpo.com/reference/storefront-product-reviews.md): `GET https://api-cdn.yotpo.com/v3/storefront/store/{storeId}/product/{productId}/reviews` Retrieves storefront reviews for a specific product. - [Search product reviews](https://docs.yotpo.com/reference/storefront-product-reviews-search.md): `POST https://api-cdn.yotpo.com/v3/storefront/store/{storeId}/product/{productId}/reviews` Search or filter storefront reviews for a specific product. - [Retrieve product filters](https://docs.yotpo.com/reference/storefront-product-filters.md): `GET https://api-cdn.yotpo.com/v3/storefront/store/{storeId}/product/{productId}/productFilters` Retrieves product-level filters used for storefront review experiences. - [Retrieve product data](https://docs.yotpo.com/reference/storefront-product-data.md): `GET https://api-cdn.yotpo.com/v3/storefront/stores/{storeId}/products/{productId}/productData` Retrieves product-level data used for storefront review experiences. - [Retrieve reviews media](https://docs.yotpo.com/reference/storefront-reviews-media.md): `GET https://api-cdn.yotpo.com/v3/storefront/stores/{storeId}/products/{productId}/reviewsMedia` Retrieve media assets associated with product reviews. - [Retrieve top product reviews](https://docs.yotpo.com/reference/storefront-top-reviews.md): `GET https://api-cdn.yotpo.com/v3/storefront/store/{storeId}/product/{productId}/top_reviews` Retrieves top reviews for a product. - [Retrieve top store reviews](https://docs.yotpo.com/reference/storefront-store-top-reviews.md): `GET https://api-cdn.yotpo.com/v3/storefront/store/{storeId}/top_reviews` Retrieves top reviews for a store. - [Retrieve store reviews](https://docs.yotpo.com/reference/storefront-store-reviews.md): `GET https://api-cdn.yotpo.com/v3/storefront/store/{storeId}/reviews` Retrieves every review in the store, across all products, one page at a time. Review objects here use snake_case field names (`votes_up`, `created_at`), unlike the product reviews endpoint. - [Search store reviews](https://docs.yotpo.com/reference/storefront-store-reviews-search.md): `POST https://api-cdn.yotpo.com/v3/storefront/store/{storeId}/reviews` Search or filter storefront reviews for a specific store. - [Retrieve bottomline scores](https://docs.yotpo.com/reference/storefront-all-bottomlines.md): `GET https://api-cdn.yotpo.com/v3/storefront/stores/{storeId}/ratings` Retrieve bottomline scores for each product in a store. - [Retrieve product rating bottomline](https://docs.yotpo.com/reference/storefront-product-ratings.md): `GET https://api-cdn.yotpo.com/v3/storefront/store/{storeId}/product/{productId}/ratings` Retrieves rating bottomline information for a specific product. The same data is also served at `/v3/storefront/stores/{storeId}/products/{productId}/ratings`. - [Retrieve star distribution for a product](https://docs.yotpo.com/reference/storefront-star-distribution.md): `GET https://api-cdn.yotpo.com/v1/star_distribution/store/{storeId}/product/{productId}` Returns how many published reviews a product has at each star rating, from 1 to 5. The V3 reviews widget uses it for its rating breakdown. An unknown product ID returns zeros. No access token is needed. - [Retrieve promoted products for a store](https://docs.yotpo.com/reference/storefront-store-promoted-products.md): `GET https://api-cdn.yotpo.com/v3/storefront/store/{storeId}/promoted_products` Returns the products the store promotes in the Promoted Products widget, in display order. No access token is needed. Data is cached on Yotpo's CDN, so changes can take time to appear. - [Retrieve promoted products for a product page](https://docs.yotpo.com/reference/storefront-product-promoted-products.md): `GET https://api-cdn.yotpo.com/v3/storefront/store/{storeId}/product/{productId}/promoted_products` Returns the products to promote on a given product page, in display order. An unknown product ID returns the store-level list. No access token is needed. Data is cached on Yotpo's CDN, so changes can take time to appear. - [Retrieve gallery media](https://docs.yotpo.com/reference/storefront-gallery-media.md): `GET https://api-cdn.yotpo.com/v3/storefront/stores/{storeId}/widget_instance_id/{widgetInstanceId}/sorted_media` Returns the media in a Visual UGC gallery, in the order the merchant set. Send `source_album_id` for a custom gallery, or `external_product_id` for a product gallery. No access token is needed. - [Retrieve a gallery media item](https://docs.yotpo.com/reference/storefront-gallery-media-item.md): `GET https://api-cdn.yotpo.com/v3/storefront/stores/{storeId}/album_media/{albumMediaId}` Returns one media item from a Visual UGC gallery, with its caption, author and votes. Get the `albumMediaId` from Retrieve gallery media. No access token is needed. - [Retrieve AI review summary](https://docs.yotpo.com/reference/reviews-ai-summary.md): `GET https://api.yotpo.com/reviews/v3/stores/{storeId}/products/{productId}/reviews_summary` Returns the AI-written summary of a product's reviews: a one-paragraph summary, a summary per topic, and supporting quotes. Needs an access token. ## API reference · V3 · Loyalty - [Product Potential Points](https://docs.yotpo.com/reference/get-product-potential-points.md): `POST https://storefront.yotpo.com/loyalty/v3/stores/{store_id}/product_potential_points` Calculates the potential points a customer can earn for a product and its variants. Does not require customer authentication. Returns points based on general earning rules. - [Authenticated Product Potential Points](https://docs.yotpo.com/reference/get-customer-product-potential-points.md): `POST https://storefront.yotpo.com/loyalty/v3/stores/{store_id}/customer_product_potential_points` Calculates the potential points an authenticated customer can earn for a product and its variants. Requires customer authentication headers. Includes customer-specific multipliers (e.g. - [Get product potential earnings](https://docs.yotpo.com/reference/get-product-potential-earnings.md): `GET https://storefront.yotpo.com/loyalty/v3/stores/{store_id}/product_potential_earnings` Returns how many points a shopper would earn by buying a product at a given price, for "Earn X points" messages on product pages. No shopper login or access token is needed. - [Get customer product potential earnings](https://docs.yotpo.com/reference/get-customer-product-potential-earnings.md): `GET https://storefront.yotpo.com/loyalty/v3/stores/{store_id}/customer_product_potential_earnings` Returns how many points a logged-in shopper would earn by buying a product at a given price, with their VIP tier multiplier applied. Authenticate the shopper with the three `X-Customer` headers. - [Retrieve referral programs](https://docs.yotpo.com/reference/loyalty-referral-programs.md): `GET https://storefront.yotpo.com/loyalty/v3/stores/{store_id}/referrals/programs` Returns the store's referral programs: rewards for the friend and the advocate, landing pages and validation rules. The referral widgets use it. No access token is needed. - [List rewards (storefront)](https://docs.yotpo.com/reference/loyalty-storefront-redemption-options.md): `GET https://loyalty.yotpo.com/api/public/v1/redemption_options` Returns the rewards shoppers can redeem points for, for a rewards page or a redemption widget. It needs only your public Loyalty GUID, so you can call it from the browser. - [List VIP tiers (storefront)](https://docs.yotpo.com/reference/loyalty-storefront-vip-tiers.md): `GET https://loyalty.yotpo.com/api/public/v1/tiers` Returns your VIP tiers, lowest first, with what a shopper must do to enter, keep and regain each one. It needs only your public Loyalty GUID, so you can call it from the browser. - [List ways to earn (storefront)](https://docs.yotpo.com/reference/loyalty-storefront-campaigns.md): `GET https://loyalty.yotpo.com/api/public/v1/campaigns` Returns your live earning campaigns, for a "ways to earn" section. It needs only your public Loyalty GUID, so you can call it from the browser. - [Get VIP Tiers Program](https://docs.yotpo.com/reference/get-vip-tiers-program.md): `GET https://api.yotpo.com/loyalty/v3/stores/{store_id}/vip_tiers/programs/current` Returns the store's current VIP tiers program: its general settings and every tier with its criteria, rewards, and benefits. - [Get VIP Tiers Program Status](https://docs.yotpo.com/reference/get-vip-tiers-program-status.md): `GET https://api.yotpo.com/loyalty/v3/stores/{store_id}/vip_tiers/programs/current:status` Returns the status of the store's current VIP tiers program. Check that the program is ACTIVE before pushing customers to a tier. - [Push Customer to Tier](https://docs.yotpo.com/reference/push-customer-to-tier.md): `POST https://api.yotpo.com/loyalty/v3/stores/{store_id}/vip_tiers/customers/{customer_id}:push_to_tier` Manually assigns a customer to a VIP tier, either until a set end date or indefinitely. - [Reward Instances API](https://docs.yotpo.com/reference/retrieve-reward-instances.md): `GET https://loyalty.yotpo.com/v3/stores/{store_id}/reward_instances` The Reward Instances API allows merchants to retrieve details of coupon-based rewards issued to their customers. This API supports querying reward instances based on discount type, expiration, and usage status. ## API reference · V3 · Privacy - [About Privacy API](https://docs.yotpo.com/reference/about-privacy-api.md): Check for, retrieve and delete a shopper's personal data in Yotpo, for data subject requests such as GDPR and CCPA. - [Data exists](https://docs.yotpo.com/reference/data-exists.md): `GET https://api.yotpo.com/privacy/data/exists` A synchronous request that checks for existing account data (true/false) in the Yotpo system. - [User data](https://docs.yotpo.com/reference/fetch-user-data.md): `GET https://api.yotpo.com/privacy/data` An asynchronous request that retrieves existing user data in the Yotpo system. User data is sent as a JSON file to the account email address associated with your Yotpo account. - [GDPR Delete](https://docs.yotpo.com/reference/gdpr-delete.md): `DELETE https://api.yotpo.com/privacy/data` Deletes or anonymizes end-user data for given email address(es). Supports multiple emails per batch; requests are handled asynchronously. - [Data exists (Loyalty)](https://docs.yotpo.com/reference/loyalty-data-exists.md): `GET https://loyalty.yotpo.com/api/v2/privacy/data/exists` A synchronous request that checks for existing account data (true/false) in the Yotpo loyalty system. - [User data (Loyalty)](https://docs.yotpo.com/reference/loyalty-user-data.md): `GET https://loyalty.yotpo.com/api/v2/privacy/data` An asynchronous request that retrieves existing user data in the Yotpo loyalty system. User data is sent as a JSON file to the account email address associated with the Yotpo loyalty account. - [Anonymize user (Loyalty)](https://docs.yotpo.com/reference/loyalty-anonymize-user.md): `DELETE https://loyalty.yotpo.com/api/v2/privacy/data` As part of Global Data Regulation compliance, this endpoint removes and anonymizes end-user personal information collected by Yotpo. To learn more, click here. ## API reference · V3 · Webhooks & Events - [Create target](https://docs.yotpo.com/reference/create-target.md): `POST https://api.yotpo.com/core/v3/stores/{store_id}/webhooks/targets` Creates a webhook target or callback URL for listening to events. The webhook target can be used to listen to multiple events from multiple accounts. - [Retrieve targets](https://docs.yotpo.com/reference/retrieve-targets.md): `GET https://api.yotpo.com/core/v3/stores/{store_id}/webhooks/targets` Retrieves a list of all of your webhook targets. - [Retrieve target by ID](https://docs.yotpo.com/reference/retrieve-target-by-id.md): `GET https://api.yotpo.com/core/v3/stores/{store_id}/webhooks/targets/{yotpo_target_id}` Retrieves a webhook target using its Yotpo ID. - [Update target](https://docs.yotpo.com/reference/update-target.md): `PATCH https://api.yotpo.com/core/v3/stores/{store_id}/webhooks/targets/{yotpo_target_id}` Updates a webhook target. This webhook target can be used for listening to multiple events from multiple accounts. - [Delete target](https://docs.yotpo.com/reference/delete-target.md): `DELETE https://api.yotpo.com/core/v3/stores/{store_id}/webhooks/targets/{yotpo_target_id}` Deletes a webhook target. This webhook target can be used for listening to multiple events from multiple accounts, and so only unused webhook targets can be deleted. - [Create filter](https://docs.yotpo.com/reference/create-filter.md): `POST https://api.yotpo.com/core/v3/stores/{store_id}/webhooks/filters` Create a webhook filter. This webhook filter can be used with multiple webhook targets. An event type cannot be used twice in the same webhook filter. For every event name you can subscribe to, see Webhook events. - [Retrieve filters](https://docs.yotpo.com/reference/retrieve-filters.md): `GET https://api.yotpo.com/core/v3/stores/{store_id}/webhooks/filters` Retrieves a list of all of your webhook filters. - [Retrieve filter by ID](https://docs.yotpo.com/reference/retrieve-filter-by-id.md): `GET https://api.yotpo.com/core/v3/stores/{store_id}/webhooks/filters/{yotpo_filter_id}` Retrieves a webhook filter using its Yotpo ID. - [Update filter](https://docs.yotpo.com/reference/update-filter.md): `PATCH https://api.yotpo.com/core/v3/stores/{store_id}/webhooks/filters/{yotpo_filter_id}` Updates a webhook filter. This webhook filter can be used with multiple webhook targets. - [Delete filter](https://docs.yotpo.com/reference/delete-filter.md): `DELETE https://api.yotpo.com/core/v3/stores/{store_id}/webhooks/filters/{yotpo_filter_id}` Deletes a webhook filter. This webhook filter can be used with multiple webhook targets, so only unused webhook filters can be deleted. - [Create subscription](https://docs.yotpo.com/reference/create-subscription.md): `POST https://api.yotpo.com/core/v3/stores/{store_id}/webhooks/subscriptions` Combine the target and filter to create a subscription. - [Retrieve subscriptions](https://docs.yotpo.com/reference/retrieve-subscriptions.md): `GET https://api.yotpo.com/core/v3/stores/{store_id}/webhooks/subscriptions` Retrieves a list of all of your webhook subscriptions. - [Retrieve subscription by ID](https://docs.yotpo.com/reference/retrieve-subscription-by-id.md): `GET https://api.yotpo.com/core/v3/stores/{store_id}/webhooks/subscriptions/{yotpo_subscription_id}` Retrieves a webhook subscription using its Yotpo ID. - [Update subscription](https://docs.yotpo.com/reference/update-subscription.md): `PATCH https://api.yotpo.com/core/v3/stores/{store_id}/webhooks/subscriptions/{yotpo_subscription_id}` Updates a webhook subscription. - [Delete subscription](https://docs.yotpo.com/reference/delete-subscription.md): `DELETE https://api.yotpo.com/core/v3/stores/{store_id}/webhooks/subscriptions/{yotpo_subscription_id}` Deletes a webhook subscription. ## API reference · V3 · Review Events - [Review Created](https://docs.yotpo.com/reference/review-create.md): `WEBHOOK review_create` Sent when a new review is created. To receive it, add `review_create` to `events` when you create a filter, then subscribe the filter to your target. - [Review Updated](https://docs.yotpo.com/reference/review-updated.md): `WEBHOOK review_updated` Sent when: - A review is published. - A review is unpublished (rejected). - A reviewer verifies their email (for reviews written in the PDP Reviews Widget), and the review changes from anonymous to *verified reviewer*. - [Review Request Eligible on Fulfillment](https://docs.yotpo.com/reference/review-request-eligible-on-fulfillment.md): `WEBHOOK review_request.eligible.on_fulfillment` Sent when an order becomes eligible for a review request after it is fulfilled. Use it to send review requests from your own messaging platform. - [Review Request Eligible on Delivery](https://docs.yotpo.com/reference/review-request-eligible-on-delivery.md): `WEBHOOK review_request.eligible.on_delivery` Sent when an order becomes eligible for a review request after it is delivered. Use it to send review requests from your own messaging platform. ## API reference · V3 · Loyalty Events - [Coupon Earned](https://docs.yotpo.com/reference/swell-redemption-created.md): `WEBHOOK swell/redemption/created` Sent when a customer gets a coupon code, either by completing a campaign (for example a newsletter signup) or by redeeming points. Use it to email the coupon code to the customer. - [Custom Reward Redeemed](https://docs.yotpo.com/reference/loyalty-custom-reward-created.md): `WEBHOOK loyalty/custom/reward/created` Sent when a customer redeems points for a custom reward, or gets a custom reward for completing a campaign. - [Customer Birthday](https://docs.yotpo.com/reference/swell-customer-birthday.md): `WEBHOOK swell/customer/birthday` Sent on a customer's birthday. Use it to send a birthday email and tell the customer about any points or coupon from your Birthday campaign. - [Customer Birthday Captured](https://docs.yotpo.com/reference/swell-birthday-captured.md): `WEBHOOK swell/birthday/captured` Sent when a customer sets their birthday on your storefront, or when it's updated in Yotpo Loyalty. - [Customer Anniversary](https://docs.yotpo.com/reference/swell-customer-anniversary.md): `WEBHOOK swell/customer/anniversary` Sent on a customer's anniversary. Use it to send an anniversary email and tell the customer about any points or coupon from your Anniversary campaign. - [Customer Anniversary Captured](https://docs.yotpo.com/reference/swell-anniversary-captured.md): `WEBHOOK swell/anniversary/captured` Sent when a customer sets their anniversary on your storefront. To receive it, add `swell/anniversary/captured` to `events` when you create a filter, then subscribe the filter to your target. - [Donation Created](https://docs.yotpo.com/reference/loyalty-donation-created.md): `WEBHOOK loyalty/donation/created` Sent when a customer redeems points for a donation to a nonprofit through the Shopping Gives integration. - [Account Created](https://docs.yotpo.com/reference/swell-account-created.md): `WEBHOOK swell/account/created` Sent when a customer gets the reward for the New Member Reward earning rule. Use it to send a loyalty welcome email. - [Loyalty Opt In](https://docs.yotpo.com/reference/loyalty-opt-in.md): `WEBHOOK loyalty/opt_in` Sent when a customer opts in to the loyalty program. Opted-in customers can earn and redeem points and join tiers. - [Loyalty Opt Out](https://docs.yotpo.com/reference/loyalty-opt-out.md): `WEBHOOK loyalty/opt_out` Sent when a customer opts out of the loyalty program. Opted-out customers can't take part in any loyalty activity. - [Points Changed](https://docs.yotpo.com/reference/swell-points-changed.md): `WEBHOOK swell/points/changed` Sent every time a customer's points balance changes, with the balance before and after. Use it to keep a points balance in another system in sync. - [Points Earned](https://docs.yotpo.com/reference/swell-points-earned.md): `WEBHOOK swell/points/earned` Sent when a customer earns points. Use it to keep the customer's points balance up to date in your CRM or email platform. - [Points Reminder](https://docs.yotpo.com/reference/swell-points-reminder.md): `WEBHOOK swell/points/reminder` Sent after a set number of days of inactivity, when the customer is close to earning a reward. Use it to remind them. - [Points Expiration Reminder](https://docs.yotpo.com/reference/loyalty-expiration-reminder.md): `WEBHOOK loyalty/expiration/reminder` Sent when a customer's points are about to expire. Use it to remind them to use their points. - [Redemption Below Threshold](https://docs.yotpo.com/reference/swell-redemption-code-below-threshold.md): `WEBHOOK swell/redemption_code/below_threshold` Sent when a Custom Coupon reward is running low on uploaded codes: when the unused codes reach the reward's threshold, then half, a quarter and an eighth of it, and 0. - [Redemption Cancellation Request](https://docs.yotpo.com/reference/swell-point-redemption-cancellation-request.md): `WEBHOOK swell/point_redemption/cancellation_request` Sent when a customer asks to cancel a redemption and get their points back. The points are returned only after you approve the cancellation through the API. - [Redemption Reminder](https://docs.yotpo.com/reference/swell-redemption-reminder.md): `WEBHOOK swell/redemption/reminder` Sent after a set number of days of inactivity, when the customer has enough points for a reward. Use it to remind them. - [Referral Link Share](https://docs.yotpo.com/reference/swell-referral-share.md): `WEBHOOK swell/referral/share` Sent when a customer shares their referral link with friends. Use it to tell the friend that someone they know likes your store. - [Referral Link Share (2.0)](https://docs.yotpo.com/reference/yotpo-referral-shared.md): `WEBHOOK yotpo/referral/shared` Sent when a customer shares their referral link with friends. Use it to tell the friend that someone they know likes your store. - [Referral Share Reminder](https://docs.yotpo.com/reference/swell-referral-share-reminder.md): `WEBHOOK swell/referral/share/reminder` Sent when a referred friend hasn't made a purchase after a set number of days. Use it to remind them to use the referral link, so both customers get a reward. - [Referral Product Share Link](https://docs.yotpo.com/reference/loyalty-referral-product-share.md): `WEBHOOK loyalty/referral/product_share` Sent when a customer shares a product referral link. Use it to send the product share email from your own email platform. - [Referral Product Share Reminder](https://docs.yotpo.com/reference/loyalty-referral-product-share-reminder.md): `WEBHOOK loyalty/referral/product_share/reminder` Sent when a referred friend hasn't made a purchase after a set number of days. Use it to remind them to use the product referral link, so both customers get a reward. - [Referral Completed](https://docs.yotpo.com/reference/swell-referral-completed.md): `WEBHOOK swell/referral/completed` Sent when a customer refers a friend who meets your referral program's requirements. Use it to thank the customer for the referral. - [Referral Completed (2.0)](https://docs.yotpo.com/reference/yotpo-referral-completed.md): `WEBHOOK yotpo/referral/completed` Sent when a customer refers a friend who meets your referral program's requirements. Use it to thank the customer for the referral. - [Tier Earned](https://docs.yotpo.com/reference/swell-tier-earned.md): `WEBHOOK swell/tier/earned` Sent when a customer meets the requirements for a new tier. Use it to congratulate them on their new status. - [Tier Lost](https://docs.yotpo.com/reference/swell-tier-lost.md): `WEBHOOK swell/tier/lost` Sent when a customer no longer meets the requirements for their tier at the end of the period, or when they opt out of the loyalty program. - [Tier Status Changed](https://docs.yotpo.com/reference/swell-tier-status-changed.md): `WEBHOOK swell/tier/status/changed` Sent when a customer gets closer to or farther from keeping their current tier or reaching the next one. - [Tier Expiration Reminder](https://docs.yotpo.com/reference/yotpo-tier-expiration-reminder.md): `WEBHOOK yotpo/tier/expiration/reminder` Sent when a customer is at risk of losing their tier: 30, 14 and 7 days before it expires, depending on your settings, and only if they haven't met the requirements to keep it. Each reminder is sent once. - [CommerceCloud Integration Disabled](https://docs.yotpo.com/reference/loyalty-integrations-integration-disabled.md): `WEBHOOK loyalty/integrations/integration_disabled` Sent when the Salesforce Commerce Cloud integration is disabled because of authorization errors. ## API reference · Loyalty V2 · General - [Welcome](https://docs.yotpo.com/reference/loyalty-welcome.md): Everything you need before your first Loyalty API call. - [What you can build](https://docs.yotpo.com/reference/what-you-can-build.md): Pick what you want to build and follow the path. Each one starts with a recipe or a single call and links to the reference pages you need next. - [Authentication](https://docs.yotpo.com/reference/loyalty-authentication.md): How to authenticate with the Yotpo Loyalty API using your GUID and API key. - [Guidelines & Conventions](https://docs.yotpo.com/reference/loyalty-guidelines-and-conventions.md): Rate limits, errors, testing and usage conventions for the Yotpo Loyalty & Referrals API. - [Errors](https://docs.yotpo.com/reference/errors.md): The status codes the Loyalty API returns, the error bodies each part of the API sends, and how to handle each one. - [Testing your integration](https://docs.yotpo.com/reference/testing-your-integration.md): There's no sandbox, so every call reaches a real Loyalty program. How to test without changing real customers' points, sending emails or issuing live coupons. ## API reference · Loyalty V2 · Customers - [Create/Update Customer Record](https://docs.yotpo.com/reference/create-update-customer-records.md): `POST https://loyalty.yotpo.com/api/v2/customers` This endpoint both creates and updates a customer’s record in the Yotpo system. Use this primarily to notify Yotpo when you add a customer manually in your admin, or a customer changes their email address. - [Set Customer Birthday](https://docs.yotpo.com/reference/set-customer-birthday.md): `POST https://loyalty.yotpo.com/api/v2/customer_birthdays` Stores the customer's birthday, which birthday campaigns use to award points or rewards on the customer's birthday. day and month are required; year is optional. Calling again overwrites the stored birthday. - [Set/Update Customer Anniversary](https://docs.yotpo.com/reference/create-update-customer-anniversary.md): `POST https://loyalty.yotpo.com/api/v2/customer_anniversary` Stores or updates the customer's anniversary date — any date meaningful to your program (signup, first purchase, or a customer-provided date). Used by anniversary campaigns the way birthdays power birthday campaigns. - [Get Customer Anniversary](https://docs.yotpo.com/reference/get-customer-anniversary.md): `GET https://loyalty.yotpo.com/api/v2/customer_anniversary` Retrieves the customer's stored anniversary date, if one has been set. Pass an optional `campaign_id` to get the anniversary data as resolved for a specific anniversary campaign. - [Remove Customer Anniversary](https://docs.yotpo.com/reference/remove-customer-anniversary.md): `DELETE https://loyalty.yotpo.com/api/v2/customer_anniversary` Deletes the customer's stored anniversary. After removal, the customer no longer triggers anniversary-based campaigns. - [Fetch Customer Details](https://docs.yotpo.com/reference/fetch-customer-details.md): `GET https://loyalty.yotpo.com/api/v2/customers` This endpoint returns a customer record. Most commonly used to fetch a customer’s point balance and unique referral link. - [Fetch All Recently Updated Customers](https://docs.yotpo.com/reference/fetch-all-recently-updated-customers.md): `GET https://loyalty.yotpo.com/api/v2/customers/recent` Fetches a list of all the customers who were updated in the last 7 days, and their customer data registered in the Yotpo Loyalty database - [Get Customer Tags](https://docs.yotpo.com/reference/get-customer-tags.md): `GET https://loyalty.yotpo.com/api/v2/customer_tags` Retrieves the list of tags currently assigned to a customer. - [Add Customer Tags](https://docs.yotpo.com/reference/add-customer-tags.md): `PUT https://loyalty.yotpo.com/api/v2/customer_tags/add` Adds one or more tags to a customer. Duplicate tags (case-insensitive) are ignored. - [Remove Customer Tags](https://docs.yotpo.com/reference/remove-customer-tags.md): `PUT https://loyalty.yotpo.com/api/v2/customer_tags/remove` Removes one or more tags from a customer. Matching is case-insensitive. ## API reference · Loyalty V2 · Actions - [Record a Custom Action](https://docs.yotpo.com/reference/record-a-customer-action.md): `POST https://loyalty.yotpo.com/api/v2/actions` This endpoint records an action performed by a customer. It will apply the action to all active custom action campaigns and award the necessary points and/or discounts. - [Adjust a Customer's Point Balance](https://docs.yotpo.com/reference/adjust-a-customers-point-balance.md): `POST https://loyalty.yotpo.com/api/v2/points/adjust` Adds or removes points from a customer's balance outside of normal campaign earning — for goodwill credits, support resolutions, or corrections. The adjustment appears in the customer's points history. - [Remove a Customer from an Action Based VIP Tier](https://docs.yotpo.com/reference/removing-a-customer-from-an-action-based-vip-tier.md): `PUT https://loyalty.yotpo.com/api/v2/actions/cancel_all` Use this endpoint to revoke a customer's action based VIP tier status ## API reference · Loyalty V2 · Orders - [Create Order](https://docs.yotpo.com/reference/loyalty-create-order.md): `POST https://loyalty.yotpo.com/api/v2/orders` This endpoint records an order made by a customer. It will apply the order to all matching active campaigns and award the necessary points and/or discounts. ## API reference · Loyalty V2 · Refunds - [Create Refund](https://docs.yotpo.com/reference/create-refund.md): `POST https://loyalty.yotpo.com/api/v2/refunds` Send a new refund to the Yotpo API to adjust previously processed order. Requests are processed asynchronously. ## API reference · Loyalty V2 · Campaigns - [Get Active Campaigns](https://docs.yotpo.com/reference/get-active-campaigns.md): `GET https://loyalty.yotpo.com/api/v2/campaigns` This endpoint returns a list of campaigns available for customers to participate in. If you provide a particular customer we can return their current status and eligibility on each of the campaigns. ## API reference · Loyalty V2 · Redemption Options - [Upload Coupon Codes](https://docs.yotpo.com/reference/add-coupon-codes.md): `POST https://loyalty.yotpo.com/api/v2/redemption_codes` Uploads up to 10,000 coupon codes to a coupon-type redemption option's pool. Codes are handed out one per redemption as customers redeem the option — keep the pool topped up so redemptions never fail for lack of codes. - [Get Active Redemption Options](https://docs.yotpo.com/reference/fetch-active-redemption-options.md): `GET https://loyalty.yotpo.com/api/v2/redemption_options` This endpoint returns a list of redemption options available for customers to redeem. - [Get Redemption Code Data](https://docs.yotpo.com/reference/get-redemption-code-data.md): `GET https://loyalty.yotpo.com/api/v2/redemption_codes` This endpoint lets you fetch the email address of a customer who redeemed a discount by providing a `third party_id` or the discount `code`. ## API reference · Loyalty V2 · Point Redemptions - [Create Redemption](https://docs.yotpo.com/reference/create-redemption.md): `POST https://loyalty.yotpo.com/api/v2/redemptions` This endpoint will redeem a customer’s points for a particular redemption option. - [Approve Redemption Cancellation](https://docs.yotpo.com/reference/approve-redemption-cancellation.md): `POST https://loyalty.yotpo.com/api/v2/redemptions/{point_redemption_id}/cancellation_completed` This endpoint will confirm the Redemption Cancellation Request webhook so that the customer will receive their points from redemption back into their account. ## API reference · Loyalty V2 · Referrals - [Identify Referrer](https://docs.yotpo.com/reference/identify-referrer.md): `POST https://loyalty.yotpo.com/api/v2/referral/referrer` Finds or creates the customer as a referrer and returns their referral link along with their referral history — referral_receipts lists past sign-ups and completed referrals. - [Send Referral Emails](https://docs.yotpo.com/reference/send-referral-emails.md): `POST https://loyalty.yotpo.com/api/v2/referral/share` Sends referral invitations to a comma-separated list of addresses on the referrer's behalf. ## API reference · Loyalty V2 · VIP Tiers - [Fetch VIP Tiers](https://docs.yotpo.com/reference/fetch-vip-tiers.md): `GET https://loyalty.yotpo.com/api/v2/vip_tiers` Returns your program's configured VIP tiers, including each tier's ID — use it to display tier structure to customers or to look up the tier IDs other endpoints reference. ## API reference · Reviews V1 · General - [Welcome](https://docs.yotpo.com/reference/reviews-welcome.md): Introduction to the Yotpo UGC API: access reviews, photos, insights, and more. ## API reference · Reviews V1 · Reviews - Merchant - [About reviews (merchant)](https://docs.yotpo.com/reference/about-merchant-reviews.md): Reviews are the core content generated using Yotpo. Yotpo helps generate reviews that can later be displayed on the store's site and published on social networks. - [Create review](https://docs.yotpo.com/reference/create-review.md): `POST https://api.yotpo.com/v1/widget/reviews` This is the asynchronous method and is recommended for general use. - [Create review (synchronous)](https://docs.yotpo.com/reference/create-review-synchronous.md): `POST https://api.yotpo.com/reviews/dynamic_create` Note: This method is recommended for development only. - [Upload Images With Reviews Via API](https://docs.yotpo.com/reference/upload-images-with-reviews.md): `POST https://api.yotpo.com/images/process` Upload images to associate with a review using the image_upload_token received from the Create Reviews endpoint. - [Retrieve all reviews](https://docs.yotpo.com/reference/retrieve-all-reviews.md): `GET https://api.yotpo.com/v1/apps/{store_id}/reviews` Retrieves all reviews for your store (product and site reviews), with filters for date, review ID, user reference and deleted reviews. Returns up to 100 reviews per page (`count`); data can lag by about an hour. - [Retrieve a review by review ID](https://docs.yotpo.com/reference/retrieve-a-review-by-review-id.md): `GET https://api.yotpo.com/reviews/{review_id}` Retrieves a single review by its `review_id`. - [Retrieve reviews for a user using external user reference ID](https://docs.yotpo.com/reference/retrieve-reviews-for-a-specific-user.md): `GET https://api.yotpo.com/products/{store_id}/yotpo_global_reviews/reviews.json` This endpoint requires a Yotpo premium plan. - [Update incentivized reviews by review ID](https://docs.yotpo.com/reference/update-incentive-by-review-id-1.md): `PUT https://api.yotpo.com/v1/apps/{store_id}/reviews/incentivized_badge` Use this endpoint to update the review IDs of reviews that have been given incentives. - [About SEO](https://docs.yotpo.com/reference/about-seo.md): Rich snippets are extra pieces of information which are shown within Google search results to provide more information to the person running the search. - [Find if your yotpo.me Subdomain is available](https://docs.yotpo.com/reference/find-if-the-xxxxyotpome-subdomain-is-valid.md): `GET https://api.yotpo.com/apps/{store_id}/subomain_check/{subdomain}` The path segment is spelled `subomain_check`. This is the real route; `subdomain_check` returns `404`. - [Retrieve your reviews.me URL](https://docs.yotpo.com/reference/retrieve-your-reviewsme-url.md): `GET https://api.yotpo.com/v1/reviews_me/url/{store_id}/{product_id}` Reviews.me generates SEO friendly pages to be used in various SEO features, such as Rich Snippets ## API reference · Reviews V1 · Reviews - Storefront - [About reviews (storefront)](https://docs.yotpo.com/reference/about-storefront-reviews.md): Reviews are the core content generated using Yotpo. Yotpo helps generate reviews that can later be displayed on the store's site and published on social networks. - [Top Three 5-Star Reviews](https://docs.yotpo.com/reference/recent-5-star-reviews.md): `GET https://api.yotpo.com/apps/{store_id}/top_reviews` Retrieve the top three 5-star reviews per account. This endpoint will return the top three 5-star reviews (including unpublished reviews) based on Yotpo's smart algorithm in JSON or HTML format. - [Retrieve the reviews payload in HTML](https://docs.yotpo.com/reference/retrieve-the-reviews-payload-in-html.md): The methods parameter is an array of methods. Each method is a hash containing the method and parameters, which is an hash of the parameters for the method. - [Upvote or downvote reviews](https://docs.yotpo.com/reference/vote-on-reviews.md): `POST https://api.yotpo.com/reviews/{review_id}/vote/{vote_type}` Vote up or down on whether a particular review is helpful by `review_id`. - [Top mentioned topics](https://docs.yotpo.com/reference/top-mentioned-topics.md): `POST https://api-cdn.yotpo.com/v1/topic/{store_id}/topics.json` Retrieves top mentioned topics for a given product by product ID (`domain_key`). These topics are displayed as smart filters within your reviews widget. - [Retrieve LLM schema HTML for a product](https://docs.yotpo.com/reference/retrieve-llm-schema.md): `GET https://api-cdn.yotpo.com/v1/stores/{store_id}/products/{product_id}/llm-schema` Retrieve a product's user-generated content as an HTML snippet, built for server-side embedding on Product Detail Pages so LLM crawlers can index review content from the page source. ## API reference · Reviews V1 · Reviews Metadata - [About reviews metadata](https://docs.yotpo.com/reference/about-reviews-metadata.md): Leverage metadata collected upon order creation to allow shoppers to filter reviews according to customer, order, and/or product-related fields such as membership type, location, delivery type, order history, and more! - [Add metadata to an existing review](https://docs.yotpo.com/reference/add-metadata-to-an-existing-review.md): `POST https://api.yotpo.com/v1/apps/{store_id}/reviews/{review_id}/metadata` Use this endpoint to add metadata to an existing review. The `review_id` can be retrieved using the Retrieve all reviews endpoint. - [Get review metadata](https://docs.yotpo.com/reference/get-review-metadata-by-review-id.md): `GET https://api.yotpo.com/v1/apps/{store_id}/reviews/{review_id}/metadata` Use this endpoint to retrieve a review's order, customer, and product metadata by `review_id`. The `review_id` can be retrieved using the Retrieve all reviews endpoint. - [Retrieve review filters and values](https://docs.yotpo.com/reference/get-filters-and-values.md): `GET https://api.yotpo.com/v1/order/{store_id}/{product_id}/orders.json` If you're collecting orders metadata properties, this call can be used to retrieve all possible filter-types, and their corresponding values, for a specific product. - [Update existing review metadata](https://docs.yotpo.com/reference/update-existing-review-metadata.md): `PUT https://api.yotpo.com/v1/apps/{store_id}/reviews/{review_id}/metadata` Use this endpoint to update metadata associated with an existing review. The `review_id` can be retrieved using the Retrieve all reviews endpoint. Note: It is not possible to remove metadata. ## API reference · Reviews V1 · Questions and Answers (Q&A) - [About Q&A](https://docs.yotpo.com/reference/about-qa.md): Yotpo Social Q&A enables visitors and prospective buyers to get real-time answers from store owners and past buyers. - [Retrieve Q&A for a product](https://docs.yotpo.com/reference/reviews-retrieve-questions-and-answers-for-a-product.md): `GET https://api.yotpo.com/products/{store_id}/{sku}/questions` Retrieve questions and public answers for a given product using the product SKU number. - [Retrieve the bottom line for Q&A](https://docs.yotpo.com/reference/reviews-retrieve-the-bottom-line-for-questions-and-answers.md): `GET https://api.yotpo.com/products/{store_id}/{sku}/qna_bottomline` Retrieve the Bottom Line for a given product using the product SKU number. The Bottom Line will return the total questions and total answers for the desired product. - [Retrieve answered questions for a product](https://docs.yotpo.com/reference/retrieve-product-questions-storefront.md): `GET https://api-cdn.yotpo.com/v1/widget/{store_id}/products/{product_id}/questions` Returns a product's questions that have at least one published answer, newest first, with their answers and vote counts. This is what the V3 Q&A widget shows. No access token is needed. - [Retrieve all questions](https://docs.yotpo.com/reference/retrieve-all-questions.md): `GET https://api.yotpo.com/apps/{store_id}/questions.json` Retrieve all Questions for the designated account per Yotpo account API key. - [Retrieve a question](https://docs.yotpo.com/reference/retrieve-question.md): `GET https://api.yotpo.com/questions/{question_id}` Returns one question with all its answers, public and private, and the product it's about. - [Update a question](https://docs.yotpo.com/reference/update-question.md): `PUT https://api.yotpo.com/questions/{question_id}` Changes the text of a question, for example to fix a typo before you answer it. - [Archive or unarchive questions](https://docs.yotpo.com/reference/archive-questions.md): `POST https://api.yotpo.com/questions/archive` Archives or unarchives one or more of your store's questions in one call. Archived questions drop out of the list of new, unanswered questions in Yotpo, so use this to clear questions you won't answer. - [Create an answer to a question](https://docs.yotpo.com/reference/create-answer-for-question.md): `POST https://api.yotpo.com/questions/{question_id}/answers` Create a public or private Answer to a specific Question per `question_id`. - [Update an answer](https://docs.yotpo.com/reference/update-answer-for-question.md): `PUT https://api.yotpo.com/questions/{question_id}/answers/{answer_id}` Changes the text of an answer, or switches it between public and private. Send the fields inside a `comment` object. Fields sent inside `answer` are ignored, and the request still returns `200`. - [Delete an answer](https://docs.yotpo.com/reference/delete-answer-for-question.md): `DELETE https://api.yotpo.com/questions/{question_id}/answers/{answer_id}` Deletes an answer. If it was the question's only public answer, the question stops showing on your site. - [Create question (without confirmation email)](https://docs.yotpo.com/reference/draft-create-question-without-sending-confirmation-email.md): `POST https://api.yotpo.com/questions` Create and send a Question without sending your customer a confirmation email. - [Create question (with confirmation email)](https://docs.yotpo.com/reference/send-question-confirmation-mail.md): `POST https://api.yotpo.com/questions/send_confirmation_mail` Create and send a Question which requires email confirmation. - [Vote on answers](https://docs.yotpo.com/reference/vote-on-answers.md): `POST https://api.yotpo.com/answers/{answer_id}/vote/{vote_type}` Vote up or down on a particular answer to a question by answer_id. ## API reference · Reviews V1 · Visual UGC - [About Visual UGC](https://docs.yotpo.com/reference/about-visual-ugc.md): Visual UGC endpoints allow you to leverage user-generated photos and videos on your site, social pages, and ads. Check out the table below for an overview of each endpoint. - [Import images](https://docs.yotpo.com/reference/import-images.md): `POST https://api.yotpo.com/v1/widget/{store_id}/images/create_batch` Use this endpoint to seamlessly import an array of up to eight images to Yotpo. You may also leverage this endpoint to build your own custom widget. - [Import videos](https://docs.yotpo.com/reference/import-videos.md): `POST https://api.yotpo.com/v1/media_upload/video_bulk_upload` Use this endpoint to import videos to Yotpo's Visual Curation. Videos can be added to Custom Albums and Product Albums by including `videos.album_names` and `videos.domain_keys`, respectively. - [Get media](https://docs.yotpo.com/reference/get-media.md): `GET https://api.yotpo.com/v1/apps/{store_id}/images/export` Get user-generated photos and/or video by `source` and `media_type`. The media source could be from `review`, `import`, `onsite_upload`, or `social`. - [Custom albums](https://docs.yotpo.com/reference/get-custom-albums.md): `GET https://api.yotpo.com/albums/{store_id}` Fetches the names and ID's of all existing custom albums per account `app_key`. - [Photos by album](https://docs.yotpo.com/reference/photos-by-album.md): `GET https://api.yotpo.com/v1/widget/{store_id}/albums/by_name` Fetches the custom album payload including album images, tags, names, and ID's of all existing custom albums per account `app_key`. For Instagram media, the `post` object includes `post_id` and `post_link`. - [Product images](https://docs.yotpo.com/reference/product-images.md): `GET https://api.yotpo.com/v1/widget/{store_id}/albums/product/{product_id}` Use this endpoint to retrieve images curated to product albums. For Instagram media, the `post` object includes `post_id` and `post_link`. Use `post_id` to group media from the same Instagram post. - [Video upload errors](https://docs.yotpo.com/reference/video-upload-errors.md): `GET https://api.yotpo.com/v1/media_upload/errors` Request a list of failed video upload attempts. The response includes the uploader's `user_name`, `user_email`, `file_name`, video upload `source`, creation timestamp, and the reason the video failed to upload… ## API reference · Reviews V1 · Dynamic Coupons - [About dynamic coupons](https://docs.yotpo.com/reference/about-coupons.md): Coupons are a great way to encourage your customers to write reviews and to give them an incentive to return to your store as repeat shoppers. - [Delete a dynamic coupon action's codes](https://docs.yotpo.com/reference/delete-a-coupon-action.md): `POST https://api.yotpo.com/apps/{store_id}/coupons/unique/delete` Deletes the dynamic coupon codes uploaded for a coupon action (for example `map_review`). Deletion is processed asynchronously, so codes can still appear in Retrieve all dynamic coupon codes for a short time. - [Retrieve all dynamic coupon codes](https://docs.yotpo.com/reference/retrieve-all-unique-coupon-codes.md): `GET https://api.yotpo.com/apps/{store_id}/coupons/unique` Retrieves the dynamic coupon codes currently uploaded to your account. - [Retrieve dynamic coupon code statistics](https://docs.yotpo.com/reference/retrieve-unique-code-statistics.md): `GET https://api.yotpo.com/apps/{store_id}/coupons/unique/stats` Returns the number of uploaded dynamic coupon codes available per coupon action. - [Upload dynamic coupon codes](https://docs.yotpo.com/reference/upload-unique-coupon-codes.md): `POST https://api.yotpo.com/apps/{store_id}/coupons/unique` Uploads unique coupon codes for a review-request email (`coupon_action`, for example `map_review`). The response reports how many codes were accepted and any rejected codes (empty, duplicate, or wrong length). ## API reference · Reviews V1 · Email Analytics - [About analytics](https://docs.yotpo.com/reference/about-analytics.md): Email analytics endpoints allow you to retrieve data on review request emails, reminder emails, coupons, comments, and other correspondences sent through the Yotpo system. - [Email analytics](https://docs.yotpo.com/reference/email-analytics.md): `GET https://api.yotpo.com/analytics/v1/emails/{store_id}/{metric_name}` Retrieve aggregated data for email metrics based on the defined email type value and group data by metrics. - [Overview](https://docs.yotpo.com/reference/summary.md): `GET https://api.yotpo.com/analytics/v1/emails/{store_id}` View a summary of all metrics as an itemized list for a specified email type. Data can be segmented by email type and grouped by various metrics. - [Raw data](https://docs.yotpo.com/reference/raw-data.md): `GET https://api.yotpo.com/analytics/v1/emails/{store_id}/export/raw_data` Use this request to return detailed data about every email sent from Yotpo including the email recipient, when the email was received, order information, delivery success or failure, when the email was opened, clicks,… - [Export email analytics](https://docs.yotpo.com/reference/export-email-analytics.md): `GET https://api.yotpo.com/analytics/v1/emails/{store_id}/export/csv` Export your Email Analytics data in .csv format. We'll email you a detailed spreadsheet based on the queried parameters. ## API reference · Reviews V1 · Unsubscribers - [About unsubscribers](https://docs.yotpo.com/reference/about-unsubscribers.md): The unsubscriber API resource is used to manage mailing lists within the Yotpo system. - [Remove a set of email addresses from email distribution lists](https://docs.yotpo.com/reference/remove-a-set-of-email-addresses-from-email-distrib.md): `POST https://api.yotpo.com/apps/{store_id}/unsubscribers/mass_create` Unsubscribes email addresses from one or more Yotpo email types. Each key of `email_list` is an email type number from the Email types table and each value is an array of addresses. - [Re-add email addresses to email distribution lists](https://docs.yotpo.com/reference/re-add-email-addresses-to-email-distribution-lists.md): `DELETE https://api.yotpo.com/apps/{store_id}/unsubscribers/mass_delete` Re-adds email addresses to your mailing list that you added to your Yotpo email blocklist. Customers who organically unsubscribed from your mailing list will not be re-added. - [Retrieve a list of unsubscribers](https://docs.yotpo.com/reference/retrieve-a-list-of-unsubscribers.md): `GET https://api.yotpo.com/apps/{store_id}/unsubscribers` Retrieves the email addresses unsubscribed from Yotpo emails, with the email type each address is unsubscribed from. Paginate with `count` and `page`. ## API reference · Reviews V1 · Insights - [About Insights API](https://docs.yotpo.com/reference/about-insights-api.md): Before you get started, you'll need to get your authorization credentials ready. Insights API calls use the same access token as other Yotpo endpoints. - [Topics](https://docs.yotpo.com/reference/topics.md): `POST https://api.yotpo.com/insights/v1/topics` Retrieves topics mentioned in reviews. The response includes Insights data such as topic sentiment score, industry average, the number of opinions detected per topic, and the opinion polarity. - [Reviews per topic](https://docs.yotpo.com/reference/reviews.md): `POST https://api.yotpo.com/insights/v1/topics/reviews` Retrieves reviews on specific products according to topics. The response includes review data such as reviewer email, review id, title, content, star-rating, opinions, and can be filtered accordingly. - [Products](https://docs.yotpo.com/reference/reviews-products.md): `POST https://api.yotpo.com/insights/v1/products` Get the average star rating score, sentiment, sentiment change, organic reviews counts, and reviews sentiment distribution for specific products in your store. - [Reviews per product](https://docs.yotpo.com/reference/product-reviews.md): `POST https://api.yotpo.com/insights/v1/products/reviews` Get detailed organic reviews per product including top opinions and best sentences found within the review content. - [Product collections](https://docs.yotpo.com/reference/product-collections.md): `POST https://api.yotpo.com/insights/v1/topics/products` Get the average star rating score, sentiment, sentiment change, and reviews sentiment distribution for specific product collections in your store. ## API reference · App partners · App Developer API - [Table of Contents](https://docs.yotpo.com/reference/partners-table-of-contents.md): Endpoints are conveniently organized by section - Products, Reviews, and Webhook requests. - [Guidelines and Conventions](https://docs.yotpo.com/reference/partners-guidelines-and-conventions.md): Before you start using the API, we recommend you review these guidelines. - [Changelog](https://docs.yotpo.com/reference/partners-changelog.md): See the API changelog for the latest changes and updates to Yotpo APIs. - [Generate Access Token](https://docs.yotpo.com/reference/generate-a-token.md): `POST https://developers.yotpo.com/v2/oauth2/token` Exchange the temporary code from the merchant's install for an access token. See Authenticating with OAuth 2.0. - [Retrieve Token Info](https://docs.yotpo.com/reference/retrieve-token-info.md): `GET https://developers.yotpo.com/v2/{account_id}/info` Returns the store your access token is for and the scopes your app was granted. Use it to check a token before you call other endpoints. - [Remove Application](https://docs.yotpo.com/reference/remove-application.md): `DELETE https://developers.yotpo.com/v2/{account_id}/access_tokens/{access_token}` Use this endpoint to delete an existing access token and remove authorization to the Yotpo account. We recommend you use this call each time you uninstall an app. Once confirmed, this operation cannot be undone. - [Yotpo Postman Collection](https://docs.yotpo.com/reference/yotpo-postman-collection.md): Integrating with a new API can be challenging, but we're here to make it easier. Our Postman collection allows you to explore and interact with our API visually, accelerating your development process. ## API reference · App partners · Orders and Fulfillments - [Introduction to Orders and Fulfillments](https://docs.yotpo.com/reference/introduction-to-orders-and-fulfillments.md): Use Orders and fulfillments endpoints to sync orders and fulfilments to Yotpo. - [Retrieve Orders per Account](https://docs.yotpo.com/reference/partners-retrieve-orders.md): `GET https://developers.yotpo.com/v2/{account_id}/orders` Retrieves the orders Yotpo holds for the store, newest first by `order_date`. ## API reference · App partners · Products - [Introduction to Products](https://docs.yotpo.com/reference/partners-introduction-to-products.md): Use Products endpoints to retrieve data on products including product star-ratings, promoted products, product reviews, and more. - [All Products](https://docs.yotpo.com/reference/all-products.md): `GET https://developers.yotpo.com/v2/{account_id}/products` Retrieve paginated product data for your entire product catalog by `account_id`. - [Product Data](https://docs.yotpo.com/reference/product-data.md): `GET https://developers.yotpo.com/v2/{account_id}/products/{external_product_id}` Retrieve product data by `product_id`. This call returns product data such as product identifiers, average score, total review count, and more. - [Promoted Products](https://docs.yotpo.com/reference/promoted-products.md): `GET https://developers.yotpo.com/v2/{account_id}/promoted_products` Yotpo's smart algorithm automatically promotes your most popular products by purchase date, star rating, number of reviews, and manually selected products. ## API reference · App partners · Reviews - [Introduction to Reviews](https://docs.yotpo.com/reference/introduction-to-reviews.md): Use Reviews endpoints to retrieve reviews data including top reviews, reviews by review ID, and more. - [All Reviews](https://docs.yotpo.com/reference/all-reviews.md): `GET https://developers.yotpo.com/v2/{account_id}/reviews` Retrieve reviews data per account as a paginated response. This call will return reviews metrics such as review `id`, star-ratings `score`, `votes_up` or `votes_down`, review `content`, product identifiers, and more. - [Product Reviews](https://docs.yotpo.com/reference/product-review.md): `GET https://developers.yotpo.com/v2/{account_id}/products/{external_product_id}/reviews` Retrieve product reviews for a specific product using the `external_product_id`. - [Product Star Rating](https://docs.yotpo.com/reference/bottomline.md): `GET https://developers.yotpo.com/v2/{account_id}/star_rating/products/{external_product_id}` Retrieve the average star-rating and review count for a specific product by `external_product_id`. - [Review by Review ID](https://docs.yotpo.com/reference/reviews-id.md): `GET https://developers.yotpo.com/v2/{account_id}/reviews/{review_id}` Retrieve a specific review by `review_id`. - [Top Reviews](https://docs.yotpo.com/reference/top-reviews.md): `GET https://developers.yotpo.com/v2/{account_id}/top_reviews` This endpoint automatically retrieves the top reviews from your Yotpo reviews based on the star rating. - [Best Reviews](https://docs.yotpo.com/reference/best-reviews.md): `POST https://developers.yotpo.com/v2/{account_id}/best_reviews` Leveraging Yotpo's Insights engine, 'Best reviews' are identified, parsed, and extracted based on the number of distinct positive topics and opinions within your reviews. - [Best Sentences](https://docs.yotpo.com/reference/best-sentences.md): `POST https://developers.yotpo.com/v2/{account_id}/best_sentences` This endpoint automatically retrieves the very best sentences from your Yotpo reviews, so you can leverage the social proof of top customer testimonials at key conversion points throughout the buyer journey! You define… - [Publish/Unpublish Reviews](https://docs.yotpo.com/reference/publishunpublish-reviews.md): `POST https://developers.yotpo.com/v2/{store_id}/moderation/reviews` This API allows you to publish or reject one or multiple reviews to the onsite widgets. ## API reference · App partners · Customers - [Introduction to Customers](https://docs.yotpo.com/reference/introduction-to-customers.md): 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. - [Create or Update Customer](https://docs.yotpo.com/reference/create-or-update-customer.md): `PATCH https://developers.yotpo.com/core/v3/stores/{store_id}/customers` Create or update customer in the Yotpo platform - [Retrieve Loyalty Customer Details by Email](https://docs.yotpo.com/reference/retrieve-loyalty-customer-details-by-email.md): `POST https://developers.yotpo.com/loyalty/v3/stores/{store_id}/customers` Retrieve a customer record from Yotpo Loyalty & Referrals (updated in real-time). ## API reference · App partners · Loyalty & Referrals - [Retrieve Earning Rules](https://docs.yotpo.com/reference/retrieve-earning-rules.md): `GET https://developers.yotpo.com/loyalty/v3/stores/{store_id}/earning_rules` Lists the store's loyalty earning rules: the ways customers earn points, such as making a purchase, creating an account or completing a custom action. - [Adjust Loyalty Customer Points](https://docs.yotpo.com/reference/adjust-loyalty-customer-points.md): `POST https://developers.yotpo.com/loyalty/v3/stores/{store_id}/points/adjust` Adds or removes points from a customer's balance outside of normal campaign earning: for goodwill credits, support resolutions, or corrections. The adjustment appears in the customer's points history. - [Record Loyalty Customer Action](https://docs.yotpo.com/reference/record-loyalty-customer-action.md): `POST https://developers.yotpo.com/loyalty/v3/stores/{store_id}/custom_actions` This endpoint records an action performed by a customer. It will apply the action to all active custom action campaigns and award the necessary points and/or discounts. ## API reference · App partners · Comments for Reviews - [Create New Comment](https://docs.yotpo.com/reference/comment-on-a-review.md): `POST https://developers.yotpo.com/v2/{account_id}/reviews/{review_id}/comment` Use this call to create a new comment on a published review by `review_id`. The `review_id` can be found using All Reviews. - [Retrieve Existing Comment](https://docs.yotpo.com/reference/get-comment-by-review-id.md): `GET https://developers.yotpo.com/v2/{account_id}/reviews/{review_id}/comment` Use this endpoint to retrieve a comment and its related metadata by `review_id`. The `review_id` can be found using All Reviews. - [Update Existing Comment](https://docs.yotpo.com/reference/update-a-comment-on-a-review-1.md): `PUT https://developers.yotpo.com/v2/{account_id}/reviews/{review_id}/comment` Use this call to update (edit) an existing comment on a published review. You can find the `review_id` using the All Reviews endpoint. - [Delete Comment](https://docs.yotpo.com/reference/delete-a-comment-on-a-review.md): `DELETE https://developers.yotpo.com/v2/{account_id}/reviews/{review_id}/comment` Use this endpoint to delete an existing comment on a published review. ## API reference · App partners · Q&A - [Retrieve Questions and Answers for a Product](https://docs.yotpo.com/reference/partners-retrieve-questions-and-answers-for-a-product.md): `GET https://api.yotpo.com/products/{store_id}/{sku}/questions` Retrieve questions and public answers for a given product using the product SKU. - [Retrieve the Bottom Line for Questions and Answers](https://docs.yotpo.com/reference/partners-retrieve-the-bottom-line-for-questions-and-answers.md): `GET https://api.yotpo.com/products/{store_id}/{sku}/qna_bottomline` Retrieve the total number of questions and answers for a product, using the product SKU. - [Create an Answer](https://docs.yotpo.com/reference/create-an-answer.md): `POST https://developers.yotpo.com/v2/{account_id}/questions/{question_id}/answers` Posts the store's answer to a question by `question_id`. A question takes one answer from the store: if it already has one, the call returns `400`. - [Retrieve Q&A by Question ID](https://docs.yotpo.com/reference/retrieve-qa-by-question-id.md): `GET https://developers.yotpo.com/v2/{account_id}/questions/{question_id}` Retrieve a specific Q&A question and its answers by `question_id`. - [Update an Answer](https://docs.yotpo.com/reference/update-an-answer.md): `PUT https://developers.yotpo.com/v2/{account_id}/questions/{question_id}/answers/{answer_id}` Change the text of an answer, or make it public or private. - [Delete an Answer](https://docs.yotpo.com/reference/delete-an-answer.md): `DELETE https://developers.yotpo.com/v2/{account_id}/questions/{question_id}/answers/{answer_id}` Use this endpoint to delete an answer to a specific question by `question_id`. ## API reference · App partners · Yotpo Webhooks - [Webhook events](https://docs.yotpo.com/reference/yotpo-events.md): Each event is characterized by a tenant type, which signifies the proprietor of the event data. - [Create target](https://docs.yotpo.com/reference/partners-create-target.md): `POST https://developers.yotpo.com/core/v3/applications/{application_id}/webhooks/targets` Creates a webhook target or callback URL for listening to events. The webhook target can be used to listen to multiple events from multiple accounts. - [Retrieve targets](https://docs.yotpo.com/reference/partners-retrieve-targets.md): `GET https://developers.yotpo.com/core/v3/applications/{application_id}/webhooks/targets` Retrieves a list of all of your webhook targets. - [Retrieve target by ID](https://docs.yotpo.com/reference/partners-retrieve-target-by-id.md): `GET https://developers.yotpo.com/core/v3/applications/{application_id}/webhooks/targets/{yotpo_target_id}` Retrieves a webhook target using its Yotpo ID. - [Update target](https://docs.yotpo.com/reference/partners-update-target.md): `PATCH https://developers.yotpo.com/core/v3/applications/{application_id}/webhooks/targets/{yotpo_target_id}` Updates a webhook target. This webhook target can be used for listening to multiple events from multiple accounts. - [Delete target](https://docs.yotpo.com/reference/partners-delete-target.md): `DELETE https://developers.yotpo.com/core/v3/applications/{application_id}/webhooks/targets/{yotpo_target_id}` Deletes a webhook target. This webhook target can be used for listening to multiple events from multiple accounts, and so only unused webhook targets can be deleted. - [Create filter](https://docs.yotpo.com/reference/partners-create-filter.md): `POST https://developers.yotpo.com/core/v3/applications/{application_id}/webhooks/filters` Create a webhook filter. This webhook filter can be used with multiple webhook targets. An event type cannot be used twice in the same webhook filter. - [Retrieve filters](https://docs.yotpo.com/reference/partners-retrieve-filters.md): `GET https://developers.yotpo.com/core/v3/applications/{application_id}/webhooks/filters` Retrieves a list of all of your webhook filters. - [Retrieve filter by ID](https://docs.yotpo.com/reference/partners-retrieve-filter-by-id.md): `GET https://developers.yotpo.com/core/v3/applications/{application_id}/webhooks/filters/{yotpo_filter_id}` Retrieves a webhook filter using its Yotpo ID. - [Update filter](https://docs.yotpo.com/reference/partners-update-filter.md): `PATCH https://developers.yotpo.com/core/v3/applications/{application_id}/webhooks/filters/{yotpo_filter_id}` Updates a webhook filter. This webhook filter can be used with multiple webhook targets. - [Delete filter](https://docs.yotpo.com/reference/partners-delete-filter.md): `DELETE https://developers.yotpo.com/core/v3/applications/{application_id}/webhooks/filters/{yotpo_filter_id}` Deletes a webhook filter. This webhook filter can be used with multiple webhook targets, so only unused webhook filters can be deleted. - [Store-level webhook subscriptions](https://docs.yotpo.com/reference/store-level-webhooks.md): Each event is characterized by a tenant type that signifies the proprietor of the event data. - [Create store subscription](https://docs.yotpo.com/reference/partners-create-subscription.md): `POST https://developers.yotpo.com/core/v3/applications/{application_id}/stores/{store_id}/webhooks/subscriptions` Create a unique store subscription per account, using each merchant’s specific access token and store id. Combine the target and filter to create a subscription - [Retrieve store subscriptions](https://docs.yotpo.com/reference/partners-retrieve-subscriptions.md): `GET https://developers.yotpo.com/core/v3/applications/{application_id}/stores/{store_id}/webhooks/subscriptions` Retrieves a list of all of the webhook subscriptions per account. - [Retrieve store subscription by ID](https://docs.yotpo.com/reference/partners-retrieve-subscription-by-id.md): `GET https://developers.yotpo.com/core/v3/applications/{application_id}/stores/{store_id}/webhooks/subscriptions/{yotpo_subscription_id}` Retrieves a webhook subscription using its Yotpo ID. - [Update store subscription](https://docs.yotpo.com/reference/partners-update-subscription.md): `PATCH https://developers.yotpo.com/core/v3/applications/{application_id}/stores/{store_id}/webhooks/subscriptions/{yotpo_subscription_id}` Updates a webhook subscription per account. - [Delete store subscription](https://docs.yotpo.com/reference/delete-subscription-1.md): `DELETE https://developers.yotpo.com/core/v3/applications/{application_id}/stores/{store_id}/webhooks/subscriptions/{yotpo_subscription_id}` Deletes a webhook subscription per account. - [App-level webhook subscriptions](https://docs.yotpo.com/reference/app-level-webhooks.md): Each event is characterized by a tenant type that signifies the proprietor of the event data: - [Create app subscription](https://docs.yotpo.com/reference/create-app-subscription.md): `POST https://developers.yotpo.com/core/v3/applications/{application_id}/webhooks/subscriptions` Create an app webhook subscription - [Retrieve app subscriptions](https://docs.yotpo.com/reference/retrieve-app-subscriptions.md): `GET https://developers.yotpo.com/core/v3/applications/{application_id}/webhooks/subscriptions` Retrieve a list of all of your app webhook subscriptions - [Retrieve app subscription by ID](https://docs.yotpo.com/reference/retrieve-app-subscription-by-id.md): `GET https://developers.yotpo.com/core/v3/applications/{application_id}/webhooks/subscriptions/{yotpo_subscription_id}` Retrieve an app webhook subscription using its Yotpo ID - [Update app subscription](https://docs.yotpo.com/reference/update-app-subscription.md): `PATCH https://developers.yotpo.com/core/v3/applications/{application_id}/webhooks/subscriptions/{yotpo_subscription_id}` Update an app webhook subscription. - [Delete app subscription](https://docs.yotpo.com/reference/delete-app-subscription.md): `DELETE https://developers.yotpo.com/core/v3/applications/{application_id}/webhooks/subscriptions/{yotpo_subscription_id}` Deletes a webhook subscription per account. - [App Disconnected](https://docs.yotpo.com/reference/app-disconnected.md): `WEBHOOK integrations.applications.disconnected.v3` Sent when a merchant disconnects your app: they click Disconnect on the integration page in Yotpo, or they uninstall it in your product and you delete the access token with Remove application. ## API reference · Core V1 · General - [Welcome](https://docs.yotpo.com/reference/core-v1-welcome.md): The Yotpo Core API (v1) lets you sync your store activity and related information to Yotpo, including orders and product catalog information. - [Table of contents](https://docs.yotpo.com/reference/core-v1-table-of-contents.md): Here are all of the endpoints available for version 1 of the Core API: - [Guidelines & conventions](https://docs.yotpo.com/reference/guidelines.md): This page contains general information about Yotpo API calls. - [Changelog](https://docs.yotpo.com/reference/core-v1-changelog.md): See the API changelog for the latest changes and updates to Yotpo APIs. - [Finding your app key and API secret](https://docs.yotpo.com/reference/app-key-vs-store-id.md): The app key (Store ID) and API secret are unique codes for your account.