# 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](fallback::https://dev.wix.com/docs/api-reference/assets/rich-content/embeddable-item-v1/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](fallback::#which-items-are-listed).
+ When the source app isn't installed on the site, List Embeddable Items returns no items and [Get Embeddable Item](fallback::https://dev.wix.com/docs/api-reference/assets/rich-content/embeddable-item-v1/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](fallback::https://dev.wix.com/docs/api-reference/assets/rich-content/embeddable-item-v1/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](fallback::https://dev.wix.com/docs/api-reference/assets/rich-content/embeddable-item-v1/sample-flows#embed-a-bookable-service-in-content).
+ [Create an event listing](fallback::https://dev.wix.com/docs/api-reference/assets/rich-content/embeddable-item-v1/sample-flows#create-an-event-listing).
+ [Build a product showcase](fallback::https://dev.wix.com/docs/api-reference/assets/rich-content/embeddable-item-v1/sample-flows#build-a-product-showcase).
+ [Link to a blog post or store category](fallback::https://dev.wix.com/docs/api-reference/assets/rich-content/embeddable-item-v1/sample-flows#link-to-a-blog-post-or-store-category).
+ [Refresh a stored item](fallback::https://dev.wix.com/docs/api-reference/assets/rich-content/embeddable-item-v1/sample-flows#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](fallback::#page-url-and-path).
+ **Path (`path`)**: The item's page path relative to the site's base URL. See [Page URL and path](fallback::#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](fallback::https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2), for `BOOKING` items.
+ [Events V3](fallback::https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3), for `EVENT` items.
+ [Catalog V1](fallback::https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v1/catalog/introduction), [Products V3](fallback::https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/introduction), and [Categories](fallback::https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories), for `PRODUCT` and `STORE_CATEGORY` items.
+ [Posts](fallback::https://dev.wix.com/docs/api-reference/business-solutions/blog/posts-stats), for `BLOG_POST` items.

@sdk_package_setup

# 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](fallback::https://dev.wix.com/docs/api-reference/assets/rich-content/embeddable-item-v1/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](fallback::https://dev.wix.com/docs/api-reference/assets/rich-content/embeddable-item-v1/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](fallback::https://dev.wix.com/docs/api-reference/assets/rich-content/embeddable-item-v1/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](fallback::https://dev.wix.com/docs/api-reference/assets/rich-content/embeddable-item-v1/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](fallback::https://dev.wix.com/docs/api-reference/assets/rich-content/embeddable-item-v1/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.

Mintlify Sandbox

Coding Examples

Overview

Sled Tests

Go Headless

Studio Two

Dashboard Extensions

Backend Extensions

Site Extensions

Extend Websites with SDK

Wix APIs and References

Build Apps

Frontend Modules

Wix Design System (WDS)

Client (Deprecated)

API Preview

Wix CLI

Contexts

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

value

Int32Value

StringValue

nanos

seconds

Timestamp

excerpt

Date and time the blog post was last published.

lastPublishedDate

BlogPostDetails

Details of a bookable service from Wix Bookings.

description

durations

BookingDetails

An embeddable item is a read-only, unified representation of a site's content, such as a bookable service, event, product, blog post, or store category, that you can embed in rich content or link to. Each item has common fields, such as `title`, `image`, `pageUrl`, and `path`, and a details object specific to its `itemType`.

Item ID. This is the ID of the source entity in its Wix app. Depending on `itemType`, it's a Wix Bookings service ID, a Wix Events event ID, a Wix Stores product ID, a Wix Blog post ID, or a Wix Stores category ID.

Not always a GUID.

For `PRODUCT` and `STORE_CATEGORY`, the ID depends on the site's Wix Stores catalog version.

Item image: the main service image for `BOOKING`, the main event image for `EVENT`, the main media image for `PRODUCT`, the cover image for `BLOG_POST`, and the category image for `STORE_CATEGORY`.

Not returned when the item has no image.

Item type. Determines which details object is returned.

itemType

URL of the item's page.

For `BOOKING`, `EVENT`, and `PRODUCT`, this is 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`, this is the absolute URL of the page on the site, built from the site's base URL and `path`.

Empty when the item has no page on the site.

pageUrl

Path of the item's page, relative to the site's base URL. For example, `/post/my-post`. On free sites the base URL includes the site-name prefix, for example `https://user.wixsite.com/my-site`.

To build a full URL, join the site's base URL with this path. Store `path` instead of an absolute URL when a link must keep working after the site's domain changes.

Empty when the item has no page on the site, for example a store category without a slug.

path

Item pricing. For a single price, `minValue` and `maxValue` are equal. For a free bookable service, no prices are returned.

Returned only for `BOOKING`, `EVENT`, and `PRODUCT` items.

Item title. For example, a service name, product name, or blog post title.

title

EmbeddableItem

Bookable service from Wix Bookings (not an individual booking). Services without a service page on the site aren't listed.

Event from Wix Events. Ended events aren't listed.

Product from Wix Stores. Visible products are listed, including out-of-stock products. [List Embeddable Items](https://dev.wix.com/docs/api-reference/assets/rich-content/embeddable-item-v1/list-embeddable-items) can return a product that has no product page on the site, with empty `pageUrl` and `path`. [Get Embeddable Item](https://dev.wix.com/docs/api-reference/assets/rich-content/embeddable-item-v1/get-embeddable-item) returns a `NOT_FOUND` error for such a product.

ItemType

Blog post details. Returned only when `itemType` is `BLOG_POST`.

Bookable service details. Returned only when `itemType` is `BOOKING`.

Event details. Returned only when `itemType` is `EVENT`.

Product details. Returned only when `itemType` is `PRODUCT`.

Store category details. Returned only when `itemType` is `STORE_CATEGORY`.

itemTypeDetails

endDate

Event date and time, formatted for display by Wix Events.

formattedDateAndTime

location

startDate

Event time zone ID in @IANA TZ database format. For example, `America/New_York`.

timeZoneId

EventDetails

ID of the item to retrieve, as returned in the item's `id`. Not always a GUID.

embeddableItemId

GetEmbeddableItemRequest

Response containing the retrieved embeddable item.

GetEmbeddableItemResponse

Text to search for in item titles. How the text is matched depends on `itemType`.

When you specify `paging.cursor`, specify the same `query` as in the original request.

query

ListEmbeddableItemsRequest

Response containing a list of embeddable items.

items

ListEmbeddableItemsResponse

Item pricing. The returned fields depend on the item's pricing model.

Three-letter currency code in @ISO-4217 alphabetic format.

currency

Lowest price after discounts. For example, `15.99`. When the product has no discount, the value can equal `minValue`.

Returned only for `PRODUCT` items.

discountedValue

maxValue

minValue

ID of a Wix Pricing Plans plan that can be used to pay for the service.

Returned only for `BOOKING` items whose service accepts pricing plans.

pricingPlanId

PricingData

ProductDetails

Details of a product category from Wix Stores.

StoreCategoryDetails

Cursor pointing to the page of results to retrieve. Specify `pagingMetadata.cursors.next` or `pagingMetadata.cursors.prev` from the previous response.

cursor

Maximum number of items to return.

Default: `100` for `EVENT`, `PRODUCT` and `STORE_CATEGORY`. For `BOOKING` and `BLOG_POST`, the source app's default applies.

limit

CursorPaging

Cursor for the next page of results. Not returned when there are no more results.

Cursors

height

width

Image

Number of items returned in this response.

count

Cursors for retrieving the next and previous pages.

PagingMetadataV2

Retrieves an embeddable item by ID and item type.

Supports all item types. Specify the item's `id` and `itemType` as returned by [List Embeddable Items](https://dev.wix.com/docs/api-reference/assets/rich-content/embeddable-item-v1/list-embeddable-items). The item is returned in the same format as in [List Embeddable Items](https://dev.wix.com/docs/api-reference/assets/rich-content/embeddable-item-v1/list-embeddable-items).

Use this method to refresh an item you stored earlier, for example to check that a linked blog post still exists.

`itemType` is `UNKNOWN_ITEM_TYPE` or an unrecognized value. Specify a supported item type.

The [identity](https://dev.wix.com/docs/api-reference/articles/authentication/about-identities) used to call the method can't access the site's Wix Stores catalog. Applies to `PRODUCT` and `STORE_CATEGORY` items.

The site's Wix Stores catalog version is neither V1 nor V3. Applies to `STORE_CATEGORY` items.

Wix Events is temporarily unavailable. Applies to `EVENT` items. Retry the request later.

Couldn't find the item. The item doesn't exist, has no page on the site, or its source app isn't installed on the site.

Get a product

GetEmbeddableItem

Retrieves a blog post by the ID stored with a link, to check that it still exists and to get its current `path`.

Refresh a stored blog post link

Manage Rich Content embeddable items

Retrieves a list of embeddable items of a single item type, with optional title search and cursor paging.

Each call returns items of 1 `itemType`. To collect items of several types, call this method once per type.

The following items are returned:
+ `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.
+ `STORE_CATEGORY`: Store categories.

When the source app isn't installed on the site, the response contains no items.

Blog posts are sorted by first published date, newest first. For other item types, the order is unspecified and can change.

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.

To retrieve the next page, specify `pagingMetadata.cursors.next` from the previous response in `paging.cursor`, together with the same `query`.

`paging.cursor` is malformed. Specify a cursor from a previous response's `pagingMetadata.cursors`.

Lists products whose name matches the search text, 2 items per page.

Search products by name

ListEmbeddableItems

Lists published blog posts whose title contains the search text, newest first. Store `path` to build a link that keeps working when the site's domain changes.