About the Ricos Embeddables API

The Ricos Embeddables API lets you retrieve a site's bookable services, events, products, blog posts, and store categories in a single unified format. Use it to embed this content in rich content, such as blog posts and landing pages, or to link text to it.

With the Ricos Embeddables API, you can:

• List a site's items of a given type, with optional search by title.
• Retrieve a single item by ID, for example to refresh an item you stored earlier.
• Get a link to each item's page, either as a full URL or as a path relative to the site's base URL.
• Work with 1 data structure, whichever Wix app the item comes from.

Before you begin

It's important to note the following points before starting to code:

• The API is read-only. To create or change items, use the source app's API.
• Each List Embeddable Items call returns items of a single type. To collect items of several types, call it once per type.
• Not every item is listed. See Which items are listed.
• When the source app isn't installed on the site, List Embeddable Items returns no items and Get Embeddable Item returns a NOT_FOUND error.
• Paging uses cursors only, with up to 100 items per page. Search matches item titles only. When you request the next page, specify the same query as in the original request.
• Each item includes its full plain-text description (excerpt for blog posts), so responses can be large. Specify a smaller paging.limit when you only need titles and images.
• An item's id is the ID of the source entity in its Wix app, and isn't always a GUID. For PRODUCT and STORE_CATEGORY, the ID depends on the site's Wix Stores catalog version: a product or collection ID on catalog V1 sites, or a product or category ID on catalog V3 sites. The API detects the site's catalog version automatically.

Which items are listed

List Embeddable Items returns these items for each item type:

• BOOKING: Services that have a service page on the site.
• EVENT: Events that haven't ended.
• PRODUCT: Visible products, including out-of-stock products.
• BLOG_POST: Published posts, sorted by first published date, newest first.
• STORE_CATEGORY: On Wix Stores catalog V3 sites, visible categories. On catalog V1 sites, collections, including hidden ones.

For item types other than BLOG_POST, the order of results is unspecified and can change.

Page URL and path

Each item has 2 ways to reach its page on the site:

• pageUrl: A full URL.
  • For BOOKING, EVENT, and PRODUCT, it's a Wix link (https://www.wix.app/...) that redirects to the item's page on the live site and keeps working when the site's domain changes.
  • For BLOG_POST and STORE_CATEGORY, it's the absolute URL of the page on the site.
• path: The page path relative to the site's base URL, for example /post/my-post. To build a full URL, join the site's base URL with path. On free sites, the base URL includes the site-name prefix, for example https://user.wixsite.com/my-site. path is empty when the item has no page on the site.

To store a link that must keep working after the site's domain changes, store path together with the item's id and itemType, and build the full URL when you display the link.

Use cases

• Embed a bookable service in content.
• Create an event listing.
• Build a product showcase.
• Link to a blog post or store category.
• Refresh a stored item.

Terminology

• Embeddable item: A read-only, unified representation of a site's bookable service, event, product, blog post, or store category.
• Item type: The kind of content (BOOKING, EVENT, PRODUCT, BLOG_POST, or STORE_CATEGORY). It determines which details object the item includes.
• Details object: Fields specific to the item type, such as session durations for bookable services, dates and location for events, the last published date for blog posts, and descriptions.
• Page URL (pageUrl): A full URL of the item's page. See Page URL and path.
• Path (path): The item's page path relative to the site's base URL. See Page URL and path.
• Pricing data: Lowest and highest prices, a discounted price for products, and the currency. Returned for bookable services, events, and products.

Related APIs

• Services V2, for BOOKING items.
• Events V3, for EVENT items.
• Catalog V1, Products V3, and Categories, for PRODUCT and STORE_CATEGORY items.
• Posts, for BLOG_POST items.