Ricos Embeddables API: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

Embed a bookable service in content

A site owner writing a blog post wants to show a card for one of their Wix Bookings services, so readers can see the price and session lengths and go straight to the booking page.

To embed a bookable service in content:

1. Call List Embeddable Items with itemType set to BOOKING. To narrow the results as the user types, specify the text in query.
2. Let the user pick a service from the returned title and image values.
3. Store the service's id and itemType.
4. Render the card with the service's title, image, pricingData, and the session lengths in bookingDetails.durations.
5. Link the card to pageUrl. For bookable services, this is a Wix link that keeps working when the site's domain changes.

Create an event listing

An event organizer wants to promote an upcoming Wix Events event in a newsletter-style post, with its date, location, and ticket prices.

To create an event listing:

1. Call List Embeddable Items with itemType set to EVENT. Ended events aren't returned.
2. Let the user pick an event, and store its id and itemType.
3. Show the date with eventDetails.formattedDateAndTime, or format your own from eventDetails.startDate, eventDetails.endDate, and eventDetails.timeZoneId.
4. Show the venue from eventDetails.location and a short summary from eventDetails.description.
5. Show ticket prices from pricingData. When pricingData.minValue and pricingData.maxValue differ, show a price range.
6. Link to the event page with pageUrl.

Build a product showcase

A store owner wants to feature a few Wix Stores products in a landing page, with current prices and sale prices.

To build a product showcase:

1. Call List Embeddable Items with itemType set to PRODUCT. Optionally, specify query to search by product name.
2. Let the user pick products, and store each product's id and itemType.
3. Show each product's title and image.
4. Show the price from pricingData. When pricingData.discountedValue is lower than pricingData.minValue, show it as the sale price. Format prices with pricingData.currency.
5. Link each product to its pageUrl. If pageUrl is empty, the product has no product page on the site, so show it without a link.

Link to a blog post or store category

A writer wants to link a piece of text to one of the site's blog posts or store categories. The link must keep working if the site's domain changes.

To link to a blog post or store category:

1. Call List Embeddable Items with itemType set to BLOG_POST or STORE_CATEGORY. Optionally, specify query to search by title. Blog posts are returned newest first.
2. Let the user pick an item from the returned title, image, and, for blog posts, blogPostDetails.lastPublishedDate.
3. Store the item's path, for example /post/my-post, together with its id and itemType.
4. When rendering the link, join the site's base URL with the stored path. On free sites, the base URL includes the site-name prefix, for example https://user.wixsite.com/my-site.

Refresh a stored item

Content that embeds or links to an item can go stale: a product's price changes, a blog post's slug changes, or an item is deleted. Refreshing the stored item keeps the content accurate.

To refresh a stored item:

1. Call Get Embeddable Item with the stored id and itemType.
2. If the call returns a NOT_FOUND error, mark the embed or link as broken. The item was deleted, it has no page on the site, or its source app was removed.
3. Otherwise, replace the stored title, image, pricingData, path, and details with the returned values.