> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Introduction

## Article: Introduction

## Article Link: https://dev.wix.com/docs/api-reference/assets/rich-content/embeddable-item-v1/introduction.md

## Article Content:

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

@sdk_package_setup