> 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`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # GetCatalogItems # Package: catalogs # Namespace: PlatformCatalogSPI # Method link: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/catalogs/catalog-service-plugin/get-catalog-items.md ## Introduction Retrieves data for specified items in a specified catalog. Wix calls this method whenever a cart or checkout is updated, and when an item is added to an order. The method receives a `catalogReferences` array. Each catalog reference in the array contains: + The ID of the item whose latest information Wix needs to retrieve. + The ID of the app providing the catalog containing the item. + Optional details about preferences or customization of the item. The method also receives preferences for the currency and weight unit to be used in the response. Your external catalog can store and organize item details in any way you prefer. When implementing the Catalog service plugin, learn how to [handle item variants](https://dev.wix.com/docs/rest/business-solutions/e-commerce/catalog-service-plugin/handle-item-variants.md) in a way that meets your needs. The method's response must contain a `catalogItems` array. Each item in the array must contain: + A `catalogReference` object. This must be identical to the `catalogReference` object received in the request. + A `data` object with full details about the item. > **Notes:** > + If an item doesn't exist in the catalog, the response must exclude it from the `catalogItems` array in the response. > + When none of the items requested exist in the catalog, `catalogItems` must contain an empty array. > + Wix calls the method every time a cart or checkout is updated. If the response doesn't include an item that was already in the cart or checkout, Wix removes the item from the cart or checkout. --- ## REST API ### Schema ``` Method: getCatalogItems Description: Retrieves data for specified items in a specified catalog. Wix calls this method whenever a cart or checkout is updated, and when an item is added to an order. The method receives a `catalogReferences` array. Each catalog reference in the array contains: + The GUID of the item whose latest information Wix needs to retrieve. + The GUID of the app providing the catalog containing the item. + Optional details about preferences or customization of the item. The method also receives preferences for the currency and weight unit to be used in the response. Your external catalog can store and organize item details in any way you prefer. When implementing the Catalog service plugin, learn how to [handle item variants](https://dev.wix.com/docs/rest/business-solutions/e-commerce/catalog-service-plugin/handle-item-variants.md) in a way that meets your needs. The method's response must contain a `catalogItems` array. Each item in the array must contain: + A `catalogReference` object. This must be identical to the `catalogReference` object received in the request. + A `data` object with full details about the item. > **Notes:** > + If an item doesn't exist in the catalog, the response must exclude it from the `catalogItems` array in the response. > + When none of the items requested exist in the catalog, `catalogItems` must contain an empty array. > + Wix calls the method every time a cart or checkout is updated. If the response doesn't include an item that was already in the cart or checkout, Wix removes the item from the cart or checkout. URL: https://www.wixapis.com/get-catalog-items Method: POST Method parameters: param name: catalogReferences | type: array | description: Catalog reference details for the items to retrieve, including quantity of each item. - name: catalogReference | type: CatalogReference | description: Catalog and item reference info. Holds GUIDs for the item and the catalog it belongs to, as well as further optional details. This is identical in the request and response. - name: catalogItemId | type: string | description: GUID of the item within the catalog it belongs to. - name: appId | type: string | description: GUID of the app providing the catalog. You can get your app's GUID from its page in the [app dashboard](https://dev.wix.com/dc3/my-apps/). For items from Wix catalogs, the following values always apply: + Wix Stores: `"215238eb-22a5-4c36-9e7b-e7c08025e04e"` + Wix Bookings: `"13d21c63-b5ec-5912-8397-c3a5ddb27a97"` + Wix Restaurants: `"9a5d83fd-8570-482e-81ab-cfa88942ee60"` - name: options | type: object | description: Additional item details in `key:value` pairs. Use this optional field for more specificity with item selection. The values of the `options` field differ depending on which catalog is providing the items. For Wix Stores products, learn more about integrating with [Catalog V3](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/e-commerce-integration.md) or [Catalog V1](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v1/catalog/e-commerce-integration.md), depending on [the version the site uses](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-versioning/introduction.md). - name: quantity | type: integer | description: Item quantity. param name: currency | type: currency | description: Currency to return item prices in, in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, `USD` or `EUR`. By default, Wix sends the currency specified in the site's settings. param name: weightUnit | type: WeightUnit - enum: UNSPECIFIED_WEIGHT_UNIT - Weight unit can't be classified due to an error. KG - Kilograms. LB - Pounds. Return type: GetCatalogItemsResponse - name: catalogItems | type: array | description: Details for each item, including catalog reference details and item data. Any items that don't exist in the catalog are excluded. If none of the requested items exist in the catalog, this array must be empty. - name: catalogReference | type: CatalogReference | description: Catalog and item reference info. Holds GUIDs for the item and the catalog it belongs to, as well as further optional details. This is identical in the request and response. - name: catalogItemId | type: string | description: GUID of the item within the catalog it belongs to. - name: appId | type: string | description: GUID of the app providing the catalog. You can get your app's GUID from its page in the [app dashboard](https://dev.wix.com/dc3/my-apps/). For items from Wix catalogs, the following values always apply: + Wix Stores: `"215238eb-22a5-4c36-9e7b-e7c08025e04e"` + Wix Bookings: `"13d21c63-b5ec-5912-8397-c3a5ddb27a97"` + Wix Restaurants: `"9a5d83fd-8570-482e-81ab-cfa88942ee60"` - name: options | type: object | description: Additional item details in `key:value` pairs. Use this optional field for more specificity with item selection. The values of the `options` field differ depending on which catalog is providing the items. For Wix Stores products, learn more about integrating with [Catalog V3](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/e-commerce-integration.md) or [Catalog V1](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v1/catalog/e-commerce-integration.md), depending on [the version the site uses](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-versioning/introduction.md). - name: data | type: ItemData | description: Item data. Contains full details about the item. - name: productName | type: ProductName | description: __Required.__ Item name. - name: original | type: string | description: __Required.__ Item name in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). Min: 1 character. Max: 200 characters. - name: translated | type: string | description: Item name translated into the buyer's language. Min: 1 character. Max: 400 characters. Default: Same as `original`. - name: url | type: PageUrlV2 | description: URL for the item's page on the site. This is used to link back to the relevant item page from the cart page. If not provided, the site URL is used. - name: relativePath | type: string | description: The relative path for the page within the site. For example, `/product-page/a-product`. - name: url | type: string | description: The page's full URL. For example, `https://mysite.com/product-page/a-product`. - name: itemType | type: ItemType | description: __Required.__ Item type. Either one of the preset types or a custom type. - ONE-OF: - name: preset | type: ItemTypePreset | description: Preset item type. - enum: UNRECOGNISED, PHYSICAL, DIGITAL, GIFT_CARD, SERVICE - name: custom | type: string | description: Custom item type. When none of the preset types are suitable, specifies the custom type. - name: price | type: string | description: __Required.__ Item price with discounts applied. If a catalog-defined discount applies, the discount is reflected in this price. - name: fullPrice | type: string | description: Item price **before** applying any catalog-defined discount. Default: Value of `price` field, if no catalog-defined discount applies. - name: taxGroupId | type: string | description: The tax group GUID associated with this item. Learn more about the [Tax Groups Service Plugin](https://dev.wix.com/docs/rest/business-solutions/e-commerce/service-plugins/tax-groups-integration-service-plugin/introduction.md). - name: descriptionLines | type: array | description: Line item description lines. Used for displaying the item in a cart, checkout or order. For example, if you want `Size: Large` to appear under the item name, create a description line with `"name": {"original": "Size"}` and `"plainText": {"original": "Large"}`. Default: No description line. - ONE-OF: - name: plainText | type: PlainTextValue | description: Description line plain text value. - name: original | type: string | description: Description line plain text value in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). - name: translated | type: string | description: Description line plain text value translated into the buyer's language. Default: Same as `original`. - name: colorInfo | type: Color | description: Description line color value. - name: original | type: string | description: Description line color name in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). - name: translated | type: string | description: Description line color name translated into the buyer's language. Default: Same as `original`. - name: code | type: string | description: HEX or RGB color code for display. - name: name | type: DescriptionLineName | description: Description line name. - name: original | type: string | description: Description line name in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). - name: translated | type: string | description: Description line name translated into the buyer's language. Default: Same as `original`. - name: media | type: Image | description: Line item image details. Supports images from the [Wix Media Manager](https://support.wix.com/en/article/wix-media-accessing-the-media-manager) only. To use an image from another source, first upload it to the Media Manager. You can retrieve the GUID, width and height of an image from the Wix Media Manager. - name: id | type: string | description: __Required.__ WixMedia image GUID. Given a full image URL of `https://static.wixstatic.com/media/5cc69183e7954e2c9760fa2383870992.jpg`, `media.id` is `5cc69183e7954e2c9760fa2383870992.jpg`. - name: height | type: integer | description: __Required.__ Image height. - name: width | type: integer | description: __Required.__ Image width. - name: altText | type: string | description: Image alt text. - name: filename | type: string | description: Image filename. - name: quantityAvailable | type: integer | description: Quantity of the item available for purchase. Only return if the catalog manages inventory. If not returned, a buyer can increase the quantity of this item to add to the cart or checkout without limit. - name: physicalProperties | type: PhysicalProperties | description: Physical properties of the item. Only return for physical items. When applicable, contains information such as SKU and item weight. - name: weight | type: number | description: Line item weight. Measurement unit matches the weight unit specified in `weightUnit` in the request. - name: sku | type: string | description: Stock-keeping unit. Learn more about [SKUs](https://www.wix.com/encyclopedia/definition/stock-keeping-unit-sku). - name: shippable | type: boolean | description: Whether this line item is shippable. - name: subscriptionOptionInfo | type: SubscriptionOptionInfo | description: Subscription option info. - name: subscriptionSettings | type: SubscriptionSettings | description: Subscription option settings. - name: frequency | type: SubscriptionFrequency | description: Frequency of recurring payment. - enum: UNDEFINED, DAY, WEEK, MONTH, YEAR - name: interval | type: integer | description: Interval of recurring payment. Default: `1`. If SubscriptionFrequency is Day the minimum interval is 7 - name: autoRenewal | type: boolean | description: Whether subscription is renewed automatically at the end of each period. - name: billingCycles | type: integer | description: Number of billing cycles before subscription ends. Ignored if `autoRenewal` is `true`. - name: enableCustomerCancellation | type: boolean | description: Whether to allow the customer to cancel the subscription.. - name: freeTrialPeriod | type: FreeTrialPeriod | description: Period until first cycle starts. If applied payNow will be 0 If None => no free trial - name: frequency | type: SubscriptionFrequency | description: Frequency of period. Values: DAY, WEEK, MONTH, YEAR - name: interval | type: integer | description: Number of frequency units in the free trial period. For example, frequency `MONTH` with interval `3` means a 3-month free trial. - name: title | type: Title | description: Subscription option title. - name: original | type: string | description: Subscription option name in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). - name: translated | type: string | description: Subscription option name translated into the buyer's language. Default: Same as `original`. - name: description | type: Description | description: Subscription option description. - name: original | type: string | description: Subscription option description. - name: translated | type: string | description: Translated subscription option description. - name: paymentOption | type: PaymentOptionType | description: Type of selected payment option for current item. Default: `FULL_PAYMENT_ONLINE` - enum: - FULL_PAYMENT_ONLINE: The entire payment for this item happens as part of the checkout. - FULL_PAYMENT_OFFLINE: The entire payment for this item happens after checkout. For example, when using cash, check, or other offline payment methods. - MEMBERSHIP: Payment for this item is done by charging a membership. Any remaining amount not covered by the membership, such as item modifiers, is paid online. - DEPOSIT_ONLINE: Partial payment to be paid upfront during checkout. The initial amount to be paid for each line item is specified in `depositAmount`. - MEMBERSHIP_OFFLINE: Payment for this item can only be done by charging a membership and must be manually redeemed in the dashboard by the site admin. When selected, `price` is `0`. - MEMBERSHIP_ONLINE_WITH_OFFLINE_REMAINDER: Item price is charged to online membership. Any remaining amount not covered by the membership, such as item modifiers, is paid offline. - name: serviceProperties | type: ServiceProperties | description: Service properties. When applicable, this contains information such as time and number of participants. - name: scheduledDate | type: string | description: Date and time the service is to be provided, in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format. For example, the start time of a class. - name: numberOfParticipants | type: integer | description: The number of people participating in the service. For example, the number of people attending a class or the number of people per hotel room. - name: rootCatalogItemId | type: string | description: Additional GUID for the item in the catalog. This field provides an additional identifier for the item if your flow requires another GUID as well as `catalogReference.catalogItemId`. Can be used for membership validation. Default: Same as `catalogReference.catalogItemId`. - name: priceDescription | type: PriceDescription | description: Additional description for the price. Return when additional information about the price is needed. For example, when `price` is `"0"` but additional details about the actual price are needed, such as `"Starts at $67"`. - name: original | type: string | description: __Required.__ Price description in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). - name: translated | type: string | description: Price description translated into the buyer's language. Default: Same as `original`. - name: depositAmount | type: string | description: Partial payment to be paid upfront during the checkout. Return when `paymentOption` is `DEPOSIT_ONLINE`. Default: If `paymentOption` is `DEPOSIT_ONLINE` but `depositAmount` is not provided, the item is treated as if `paymentOption` is `FULL_PAYMENT_ONLINE`. - name: deliveryProfileId | type: string | description: Delivery profile GUID for the product. - name: consentRequiredPaymentPolicy | type: string | description: Item payment policy that requires customer consent to complete purchase. The payment policy will be displayed on the checkout page. - name: priceUndetermined | type: boolean | description: Whether the price is not yet defined, and will be updated after the order is created. Default: `false` - name: fixedQuantity | type: boolean | description: Whether the line item quantity is fixed and cannot be changed. Default: `false` - name: savePaymentMethod | type: boolean | description: Whether to save the payment method on the order. Default: `false` - name: taxableAddress | type: TaxableAddress | description: Address to use for tax calculation purposes. - ONE-OF: - name: addressType | type: TaxableAddressType | description: taxable address type. if this field is selected, the address is automatically resolved, and the tax is calculated accordingly. - enum: BUSINESS, BILLING, SHIPPING - name: policies | type: array | description: Policies to be displayed to the customer on the checkout page. - name: title | type: string | description: Policy title - should be translated - name: content | type: string | description: Policy content - should be translated - name: additionalFees | type: array | description: Additional Fees to be added to this item calculation. - name: code | type: string | description: Additional fee's unique code or GUID. - name: name | type: string | description: Additional fee's name. Max: 50 characters - name: price | type: string | description: Total additional fees. This `price` does not include any taxes that may apply to these additional fees. - name: taxDetails | type: TaxDetails | description: Tax details. > **Note:** Tax is not calculated in the returned `price` even when `taxDetails.taxable` is `true`. - name: taxable | type: boolean | description: Whether additional fee is taxable. - name: taxGroupId | type: string | description: Reserved for internal use. - name: membersOnly | type: boolean | description: Whether the item can only be purchased by site members. Default: `false` - name: modifierGroups | type: array | description: Modifier groups that were added to the item. - name: id | type: string | description: Modifier group GUID. - name: name | type: TranslatableString | description: Modifier group name. - name: original | type: string | description: __Required.__ String in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). Min: 1 character. Max: 200 characters. - name: translated | type: string | description: String translated into the buyer's language. Min: 1 character. Max: 400 characters. Default: Same as `original`. - name: modifiers | type: array | description: List of modifiers in this group. - name: id | type: string | description: Modifier GUID. - name: quantity | type: integer | description: The quantity of this modifier. - name: label | type: TranslatableString | description: Primary display label for the modifier. - name: details | type: TranslatableString | description: Additional details. - name: price | type: string | description: The price of the modifier. ``` ### Examples ### Get Catalog Items - decoded JWT The data payload will include the following object as an encoded JWT. For the purposes of this example, we show the request and response objects decoded. ```curl curl -X POST https://provider.example.com/get-catalog-items \ -H 'user-agent: Wix' \ -H 'accept-encoding: gzip, deflate' \ -H 'content-type: text/plain; charset=utf-8' \ -d '{ "catalogReferences": [ { "catalogReference": { "appId": "3b8658a6-3282-4b5e-ae0e-439113e20aef", "catalogItemId": "205c539b-fd89-4b0c-8d7e-55630f66e5f9" }, "quantity": 1 }, { "catalogReference": { "appId": "3b8658a6-3282-4b5e-ae0e-439113e20aef", "catalogItemId": "f95bd723-ea83-40f2-8cb8-accff2d54866", "options": { "color": "Green", "size": "M" } }, "quantity": 1 } ], "weightUnit": "KG", "currency": "USD" }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.catalogs.PlatformCatalogSPI.getCatalogItems(request, metadata) Description: Retrieves data for specified items in a specified catalog. Wix calls this method whenever a cart or checkout is updated, and when an item is added to an order. The method receives a `catalogReferences` array. Each catalog reference in the array contains: + The GUID of the item whose latest information Wix needs to retrieve. + The GUID of the app providing the catalog containing the item. + Optional details about preferences or customization of the item. The method also receives preferences for the currency and weight unit to be used in the response. Your external catalog can store and organize item details in any way you prefer. When implementing the Catalog service plugin, learn how to [handle item variants](https://dev.wix.com/docs/rest/business-solutions/e-commerce/catalog-service-plugin/handle-item-variants.md) in a way that meets your needs. The method's response must contain a `catalogItems` array. Each item in the array must contain: + A `catalogReference` object. This must be identical to the `catalogReference` object received in the request. + A `data` object with full details about the item. > **Notes:** > + If an item doesn't exist in the catalog, the response must exclude it from the `catalogItems` array in the response. > + When none of the items requested exist in the catalog, `catalogItems` must contain an empty array. > + Wix calls the method every time a cart or checkout is updated. If the response doesn't include an item that was already in the cart or checkout, Wix removes the item from the cart or checkout. Method parameters: param name: metadata | type: Context | description: this message is not directly used by any service, it exists to describe the expected parameters that SHOULD be provided to invoked Velo methods as part of open-platform. e.g. SPIs, event-handlers, etc.. NOTE: this context object MUST be provided as the last argument in each Velo method signature. Example: ```typescript export function wixStores_onOrderCanceled({ event, metadata }: OrderCanceledEvent) { ... } ``` - name: requestId | type: string | description: A unique identifier of the request. You may print this GUID to your logs to help with future debugging and easier correlation with Wix's logs. - name: currency | type: string | description: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code. - name: identity | type: IdentificationData | description: An object that describes the identity that triggered this request. - ONE-OF: - name: anonymousVisitorId | type: string | description: GUID of a site visitor that has not logged in to the site. - name: memberId | type: string | description: GUID of a site visitor that has logged in to the site. - name: wixUserId | type: string | description: GUID of a Wix user (site owner, contributor, etc.). - name: appId | type: string | description: GUID of an app. - name: languages | type: array | description: A string representing a language and region in the format of `"xx-XX"`. First 2 letters represent the language code according to ISO 639-1. This is followed by a dash "-", and then a by 2 capital letters representing the region according to ISO 3166-2. For example, `"en-US"`. - name: instanceId | type: string | description: The service provider app's instance GUID. param name: request | type: GetCatalogItemsRequest - name: catalogReferences | type: array | description: Catalog reference details for the items to retrieve, including quantity of each item. - name: catalogReference | type: CatalogReference | description: Catalog and item reference info. Holds GUIDs for the item and the catalog it belongs to, as well as further optional details. This is identical in the request and response. - name: catalogItemId | type: string | description: GUID of the item within the catalog it belongs to. - name: appId | type: string | description: GUID of the app providing the catalog. You can get your app's GUID from its page in the [app dashboard](https://dev.wix.com/dc3/my-apps/). For items from Wix catalogs, the following values always apply: + Wix Stores: `"215238eb-22a5-4c36-9e7b-e7c08025e04e"` + Wix Bookings: `"13d21c63-b5ec-5912-8397-c3a5ddb27a97"` + Wix Restaurants: `"9a5d83fd-8570-482e-81ab-cfa88942ee60"` - name: options | type: object | description: Additional item details in `key:value` pairs. Use this optional field for more specificity with item selection. The values of the `options` field differ depending on which catalog is providing the items. For Wix Stores products, learn more about integrating with [Catalog V3](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/e-commerce-integration.md) or [Catalog V1](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v1/catalog/e-commerce-integration.md), depending on [the version the site uses](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-versioning/introduction.md). - name: quantity | type: integer | description: Item quantity. - name: weightUnit | type: WeightUnit | description: Weight measurement unit. By default, Wix sends the weight unit specified in the site's settings. - enum: - UNSPECIFIED_WEIGHT_UNIT: Weight unit can't be classified due to an error. - KG: Kilograms. - LB: Pounds. - name: currency | type: string | description: Currency to return item prices in, in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, `USD` or `EUR`. By default, Wix sends the currency specified in the site's settings. Return type: PROMISE - name: catalogItems | type: array | description: Details for each item, including catalog reference details and item data. Any items that don't exist in the catalog are excluded. If none of the requested items exist in the catalog, this array must be empty. - name: catalogReference | type: CatalogReference | description: Catalog and item reference info. Holds GUIDs for the item and the catalog it belongs to, as well as further optional details. This is identical in the request and response. - name: catalogItemId | type: string | description: GUID of the item within the catalog it belongs to. - name: appId | type: string | description: GUID of the app providing the catalog. You can get your app's GUID from its page in the [app dashboard](https://dev.wix.com/dc3/my-apps/). For items from Wix catalogs, the following values always apply: + Wix Stores: `"215238eb-22a5-4c36-9e7b-e7c08025e04e"` + Wix Bookings: `"13d21c63-b5ec-5912-8397-c3a5ddb27a97"` + Wix Restaurants: `"9a5d83fd-8570-482e-81ab-cfa88942ee60"` - name: options | type: object | description: Additional item details in `key:value` pairs. Use this optional field for more specificity with item selection. The values of the `options` field differ depending on which catalog is providing the items. For Wix Stores products, learn more about integrating with [Catalog V3](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/e-commerce-integration.md) or [Catalog V1](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v1/catalog/e-commerce-integration.md), depending on [the version the site uses](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-versioning/introduction.md). - name: data | type: ItemData | description: Item data. Contains full details about the item. - name: productName | type: ProductName | description: __Required.__ Item name. - name: original | type: string | description: __Required.__ Item name in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). Min: 1 character. Max: 200 characters. - name: translated | type: string | description: Item name translated into the buyer's language. Min: 1 character. Max: 400 characters. Default: Same as `original`. - name: url | type: string | description: URL for the item's page on the site. This is used to link back to the relevant item page from the cart page. If not provided, the site URL is used. - name: itemType | type: ItemType | description: __Required.__ Item type. Either one of the preset types or a custom type. - ONE-OF: - name: preset | type: ItemTypePreset | description: Preset item type. - enum: UNRECOGNISED, PHYSICAL, DIGITAL, GIFT_CARD, SERVICE - name: custom | type: string | description: Custom item type. When none of the preset types are suitable, specifies the custom type. - name: price | type: string | description: __Required.__ Item price with discounts applied. If a catalog-defined discount applies, the discount is reflected in this price. - name: fullPrice | type: string | description: Item price **before** applying any catalog-defined discount. Default: Value of `price` field, if no catalog-defined discount applies. - name: taxGroupId | type: string | description: The tax group GUID associated with this item. Learn more about the [Tax Groups Service Plugin](https://dev.wix.com/docs/rest/business-solutions/e-commerce/service-plugins/tax-groups-integration-service-plugin/introduction.md). - name: descriptionLines | type: array | description: Line item description lines. Used for displaying the item in a cart, checkout or order. For example, if you want `Size: Large` to appear under the item name, create a description line with `"name": {"original": "Size"}` and `"plainText": {"original": "Large"}`. Default: No description line. - ONE-OF: - name: plainText | type: PlainTextValue | description: Description line plain text value. - name: original | type: string | description: Description line plain text value in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). - name: translated | type: string | description: Description line plain text value translated into the buyer's language. Default: Same as `original`. - name: colorInfo | type: Color | description: Description line color value. - name: original | type: string | description: Description line color name in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). - name: translated | type: string | description: Description line color name translated into the buyer's language. Default: Same as `original`. - name: code | type: string | description: HEX or RGB color code for display. - name: name | type: DescriptionLineName | description: Description line name. - name: original | type: string | description: Description line name in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). - name: translated | type: string | description: Description line name translated into the buyer's language. Default: Same as `original`. - name: media | type: string | description: Line item image details. Supports images from the [Wix Media Manager](https://support.wix.com/en/article/wix-media-accessing-the-media-manager) only. To use an image from another source, first upload it to the Media Manager. You can retrieve the GUID, width and height of an image from the Wix Media Manager. - name: quantityAvailable | type: integer | description: Quantity of the item available for purchase. Only return if the catalog manages inventory. If not returned, a buyer can increase the quantity of this item to add to the cart or checkout without limit. - name: physicalProperties | type: PhysicalProperties | description: Physical properties of the item. Only return for physical items. When applicable, contains information such as SKU and item weight. - name: weight | type: number | description: Line item weight. Measurement unit matches the weight unit specified in `weightUnit` in the request. - name: sku | type: string | description: Stock-keeping unit. Learn more about [SKUs](https://www.wix.com/encyclopedia/definition/stock-keeping-unit-sku). - name: shippable | type: boolean | description: Whether this line item is shippable. - name: subscriptionOptionInfo | type: SubscriptionOptionInfo | description: Subscription option info. - name: subscriptionSettings | type: SubscriptionSettings | description: Subscription option settings. - name: frequency | type: SubscriptionFrequency | description: Frequency of recurring payment. - enum: UNDEFINED, DAY, WEEK, MONTH, YEAR - name: interval | type: integer | description: Interval of recurring payment. Default: `1`. If SubscriptionFrequency is Day the minimum interval is 7 - name: autoRenewal | type: boolean | description: Whether subscription is renewed automatically at the end of each period. - name: billingCycles | type: integer | description: Number of billing cycles before subscription ends. Ignored if `autoRenewal` is `true`. - name: enableCustomerCancellation | type: boolean | description: Whether to allow the customer to cancel the subscription.. - name: freeTrialPeriod | type: FreeTrialPeriod | description: Period until first cycle starts. If applied payNow will be 0 If None => no free trial - name: frequency | type: SubscriptionFrequency | description: Frequency of period. Values: DAY, WEEK, MONTH, YEAR - name: interval | type: integer | description: Number of frequency units in the free trial period. For example, frequency `MONTH` with interval `3` means a 3-month free trial. - name: title | type: Title | description: Subscription option title. - name: original | type: string | description: Subscription option name in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). - name: translated | type: string | description: Subscription option name translated into the buyer's language. Default: Same as `original`. - name: description | type: Description | description: Subscription option description. - name: original | type: string | description: Subscription option description. - name: translated | type: string | description: Translated subscription option description. - name: paymentOption | type: PaymentOptionType | description: Type of selected payment option for current item. Default: `FULL_PAYMENT_ONLINE` - enum: - FULL_PAYMENT_ONLINE: The entire payment for this item happens as part of the checkout. - FULL_PAYMENT_OFFLINE: The entire payment for this item happens after checkout. For example, when using cash, check, or other offline payment methods. - MEMBERSHIP: Payment for this item is done by charging a membership. Any remaining amount not covered by the membership, such as item modifiers, is paid online. - DEPOSIT_ONLINE: Partial payment to be paid upfront during checkout. The initial amount to be paid for each line item is specified in `depositAmount`. - MEMBERSHIP_OFFLINE: Payment for this item can only be done by charging a membership and must be manually redeemed in the dashboard by the site admin. When selected, `price` is `0`. - MEMBERSHIP_ONLINE_WITH_OFFLINE_REMAINDER: Item price is charged to online membership. Any remaining amount not covered by the membership, such as item modifiers, is paid offline. - name: serviceProperties | type: ServiceProperties | description: Service properties. When applicable, this contains information such as time and number of participants. - name: scheduledDate | type: Date | description: Date and time the service is to be provided, in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format. For example, the start time of a class. - name: numberOfParticipants | type: integer | description: The number of people participating in the service. For example, the number of people attending a class or the number of people per hotel room. - name: rootCatalogItemId | type: string | description: Additional GUID for the item in the catalog. This field provides an additional identifier for the item if your flow requires another GUID as well as `catalogReference.catalogItemId`. Can be used for membership validation. Default: Same as `catalogReference.catalogItemId`. - name: priceDescription | type: PriceDescription | description: Additional description for the price. Return when additional information about the price is needed. For example, when `price` is `"0"` but additional details about the actual price are needed, such as `"Starts at $67"`. - name: original | type: string | description: __Required.__ Price description in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). - name: translated | type: string | description: Price description translated into the buyer's language. Default: Same as `original`. - name: depositAmount | type: string | description: Partial payment to be paid upfront during the checkout. Return when `paymentOption` is `DEPOSIT_ONLINE`. Default: If `paymentOption` is `DEPOSIT_ONLINE` but `depositAmount` is not provided, the item is treated as if `paymentOption` is `FULL_PAYMENT_ONLINE`. - name: deliveryProfileId | type: string | description: Delivery profile GUID for the product. - name: consentRequiredPaymentPolicy | type: string | description: Item payment policy that requires customer consent to complete purchase. The payment policy will be displayed on the checkout page. - name: priceUndetermined | type: boolean | description: Whether the price is not yet defined, and will be updated after the order is created. Default: `false` - name: fixedQuantity | type: boolean | description: Whether the line item quantity is fixed and cannot be changed. Default: `false` - name: savePaymentMethod | type: boolean | description: Whether to save the payment method on the order. Default: `false` - name: taxableAddress | type: TaxableAddress | description: Address to use for tax calculation purposes. - ONE-OF: - name: addressType | type: TaxableAddressType | description: taxable address type. if this field is selected, the address is automatically resolved, and the tax is calculated accordingly. - enum: BUSINESS, BILLING, SHIPPING - name: policies | type: array | description: Policies to be displayed to the customer on the checkout page. - name: title | type: string | description: Policy title - should be translated - name: content | type: string | description: Policy content - should be translated - name: additionalFees | type: array | description: Additional Fees to be added to this item calculation. - name: code | type: string | description: Additional fee's unique code or GUID. - name: name | type: string | description: Additional fee's name. Max: 50 characters - name: price | type: string | description: Total additional fees. This `price` does not include any taxes that may apply to these additional fees. - name: taxDetails | type: TaxDetails | description: Tax details. > **Note:** Tax is not calculated in the returned `price` even when `taxDetails.taxable` is `true`. - name: taxable | type: boolean | description: Whether additional fee is taxable. - name: taxGroupId | type: string | description: Reserved for internal use. - name: membersOnly | type: boolean | description: Whether the item can only be purchased by site members. Default: `false` - name: modifierGroups | type: array | description: Modifier groups that were added to the item. - name: _id | type: string | description: Modifier group GUID. - name: name | type: TranslatableString | description: Modifier group name. - name: original | type: string | description: __Required.__ String in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). Min: 1 character. Max: 200 characters. - name: translated | type: string | description: String translated into the buyer's language. Min: 1 character. Max: 400 characters. Default: Same as `original`. - name: modifiers | type: array | description: List of modifiers in this group. - name: _id | type: string | description: Modifier GUID. - name: quantity | type: integer | description: The quantity of this modifier. - name: label | type: TranslatableString | description: Primary display label for the modifier. - name: details | type: TranslatableString | description: Additional details. - name: price | type: string | description: The price of the modifier. ``` ### Examples ### Example of a `catalogItems` return value ```javascript import { catalog } from '@wix/ecom/service-plugins'; catalog.provideHandlers({ getCatalogItems: async ( payload ) => { const {request, metadata} = payload; // Use the `request` and `metadata` received from Wix and // apply custom logic. return { // Return your response exactly as documented to integrate with Wix. // Return value example: catalogItems: [ { catalogReference: { appId: "3b8658a6-3282-4b5e-ae0e-439113e20aef", catalogItemId: "205c539b-fd89-4b0c-8d7e-55630f66e5f9" }, data: { productName: { original: "Simple Black Sun Hat" }, url: { relativePath: "/product-page/sun-hat", url: "https://www..com/" }, itemType: { preset: "PHYSICAL" }, price: "20.00", physicalProperties: { sku: "227220141836", shippable: true }, media: { id: "e3bc27_6edeb786f2aa44b19d9abcb4d1f6bfd6~mv2.png", height: 720, width: 720 } } }, { catalogReference: { appId: "3b8658a6-3282-4b5e-ae0e-439113e20aef", catalogItemId: "f95bd723-ea83-40f2-8cb8-accff2d54866", options: { color: "Green", size: "M" } }, data: { productName: { original: "Cotton T-shirt" }, url: { relativePath: "/product-page/t-shirt", url: "https://www..com/" }, itemType: { preset: "PHYSICAL" }, price: { amount: "80.00" }, descriptionLines: [ { name: { original: "Size", translated: "Size" }, plainText: { original: "Medium", translated: "Medium" } }, { name: { original: "Color", translated: "Color" }, plainText: { original: "Green", translated: "Green" } } ], physicalProperties: { sku: "889809004958", shippable: true }, media: { id: "3258d9_77f175cc4d234714825fbf316803ca9a~mv2.png", height: 720, width: 720 } } } ] } } }); ``` ### getCatalogItems (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { catalog } from '@wix/ecom/service-plugins'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { catalog }, // Include the auth strategy and host as relevant }); async function getCatalogItems(request,metadata) { const response = await myWixClient.catalog.getCatalogItems(request,metadata); }; ``` ---