> 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 ## Resource: eCommerce Integration ## Article: eCommerce Integration ## Article Link: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/e-commerce-integration.md ## Article Content: # eCommerce Integration with Wix Stores Catalog V3 When integrating products from your Wix Stores catalog into an eCommerce cart, checkout, or order, you must use the `catalogReference` object structure. This guide explains how to properly format and use the `catalogReference` object in various eCommerce API functions. Pass the `catalogReference` object as part of the `lineItems` array in the following eCommerce API functions: - [Add To Cart](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/add-to-cart.md) - [Create Checkout](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/checkout/checkout/create-checkout.md) and [Add To Checkout](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/checkout/checkout/add-to-checkout.md) - [Create Order](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/create-order.md) ## Catalog reference object structure The `catalogReference` object includes the following fields: ::::tabs :::REST_TAB | eCommerce | Stores Catalog | |-----------------|-------------------------------------------------------------------------| | `catalogItemId` | The `product.id` of the Wix Stores product | | `appId` | The Wix Stores app ID (always `"215238eb-22a5-4c36-9e7b-e7c08025e04e"`) | | `options` | An optional object containing product-specific key-value pairs | ::: :::SDK_TAB | eCommerce | Stores Catalog | |-----------------|-------------------------------------------------------------------------| | `catalogItemId` | The `product._id` of the Wix Stores product | | `appId` | The Wix Stores app ID (always `"215238eb-22a5-4c36-9e7b-e7c08025e04e"`) | | `options` | An optional object containing product-specific key-value pairs | ::: :::: ::::tabs :::REST_TAB ```json { "catalogItemId": "", "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e", "options": { "variantId": "", "options": { "": "" }, "customTextFields": { "": "" }, "subscriptionOptionId": "" } } ``` ::: :::SDK_TAB ```json { "catalogItemId": "", "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e", "options": { "variantId": "", "options": { "": "" }, "customTextFields": { "": "" }, "subscriptionOptionId": "" } } ``` ::: ::::
__Important:__ 1. Use modifiers in either `options` or `customTextFields` based on the `modifierRenderType`: - For `TEXT_CHOICES`, use the modifier and choice key in `options`. - For `FREE_TEXT`, use the `freeTextSettings.key` in `customTextFields`. 2. You may omit `customTextFields` and `options` in `catalogReference` if the related modifier isn't mandatory. 3. You can omit `subscriptionOptionId` if the product doesn't have `subscriptionDetails` defined or when `subscriptionDetails.allowOneTimePurchases` is `true`. 4. Always include the `variantId`.
## Example Consider a product with the following structure: ::::tabs :::REST_TAB ```json { "product": { "id": "dc765ec4-eaf0-4253-8ba7-e752c227d4ca", "name": "Coffee", "options": [ { "id": "093b7310-b96e-4ed5-927d-84f7de0f62be", "name": "Size", "optionRenderType": "TEXT_CHOICES", "choicesSettings": { "choices": [ { "choiceId": "bd2402d9-4ff2-42d0-b902-db235c132b0d", "name": "S" }, { "choiceId": "a75b02ff-6477-445a-a815-0e2a64edd076", "name": "L" } ] } }, { "id": "480901ba-9144-475b-a461-bd8f7cb6528d", "name": "Box color", "optionRenderType": "SWATCH_CHOICES", "choicesSettings": { "choices": [ { "choiceId": "85f6eae5-967a-4752-ab5d-71a8b8c84bf7", "name": "Red" }, { "choiceId": "11138ea7-a367-4053-b84f-d6065f2ac046", "name": "Blue" } ] } } ], "modifiers": [ { "name": "Engraving", "modifierRenderType": "FREE_TEXT", "mandatory": false, "freeTextSettings": { "title": "Would you like to engrave something on the box?", "key": "Would you like to engrave something on the box?" } }, { "name": "Remove price tag", "modifierRenderType": "TEXT_CHOICES", "mandatory": false, "choicesSettings": { "choices": [ { "key": "yes", "name": "Yes" }, { "key": "no", "name": "No" } ] }, "key": "Remove price tag" } ], "variantsInfo": { "variants": [ { "id": "9650a809-5567-44f7-9435-cf77a38cb170", "optionChoiceIds": [ { "optionId": "093b7310-b96e-4ed5-927d-84f7de0f62be", "choiceId": "bd2402d9-4ff2-42d0-b902-db235c132b0d" }, { "optionId": "480901ba-9144-475b-a461-bd8f7cb6528d", "choiceId": "85f6eae5-967a-4752-ab5d-71a8b8c84bf7" } ] }, { "id": "02f13ad1-40f1-4108-ae2e-9f48e17dfea7", "optionChoiceIds": [ { "optionId": "093b7310-b96e-4ed5-927d-84f7de0f62be", "choiceId": "a75b02ff-6477-445a-a815-0e2a64edd076" }, { "optionId": "480901ba-9144-475b-a461-bd8f7cb6528d", "choiceId": "11138ea7-a367-4053-b84f-d6065f2ac046" } ] } ] }, "subscriptionDetails": { "subscriptions": [ { "id": "3c750e1e-54fd-4fe0-8844-97427522c939", "title": "Monthly Subscription", "visible": true, "frequency": "MONTH", "interval": 1, "autoRenewal": true } ], "allowOneTimePurchases": true } } } ``` ::: :::SDK_TAB ```json { "product": { "_id": "dc765ec4-eaf0-4253-8ba7-e752c227d4ca", "name": "Coffee", "options": [ { "_id": "093b7310-b96e-4ed5-927d-84f7de0f62be", "name": "Size", "optionRenderType": "TEXT_CHOICES", "choicesSettings": { "choices": [ { "choiceId": "bd2402d9-4ff2-42d0-b902-db235c132b0d", "name": "S" }, { "choiceId": "a75b02ff-6477-445a-a815-0e2a64edd076", "name": "L" } ] } }, { "_id": "480901ba-9144-475b-a461-bd8f7cb6528d", "name": "Box color", "optionRenderType": "SWATCH_CHOICES", "choicesSettings": { "choices": [ { "choiceId": "85f6eae5-967a-4752-ab5d-71a8b8c84bf7", "name": "Red" }, { "choiceId": "11138ea7-a367-4053-b84f-d6065f2ac046", "name": "Blue" } ] } } ], "modifiers": [ { "name": "Engraving", "modifierRenderType": "FREE_TEXT", "mandatory": false, "freeTextSettings": { "title": "Would you like to engrave something on the box?", "key": "Would you like to engrave something on the box?" } }, { "name": "Remove price tag", "modifierRenderType": "TEXT_CHOICES", "mandatory": false, "choicesSettings": { "choices": [ { "key": "yes", "name": "Yes" }, { "key": "no", "name": "No" } ] }, "key": "Remove price tag" } ], "variantsInfo": { "variants": [ { "_id": "9650a809-5567-44f7-9435-cf77a38cb170", "optionChoiceIds": [ { "optionId": "093b7310-b96e-4ed5-927d-84f7de0f62be", "choiceId": "bd2402d9-4ff2-42d0-b902-db235c132b0d" }, { "optionId": "480901ba-9144-475b-a461-bd8f7cb6528d", "choiceId": "85f6eae5-967a-4752-ab5d-71a8b8c84bf7" } ] }, { "_id": "02f13ad1-40f1-4108-ae2e-9f48e17dfea7", "optionChoiceIds": [ { "optionId": "093b7310-b96e-4ed5-927d-84f7de0f62be", "choiceId": "a75b02ff-6477-445a-a815-0e2a64edd076" }, { "optionId": "480901ba-9144-475b-a461-bd8f7cb6528d", "choiceId": "11138ea7-a367-4053-b84f-d6065f2ac046" } ] } ] }, "subscriptionDetails": { "subscriptions": [ { "id": "3c750e1e-54fd-4fe0-8844-97427522c939", "title": "Monthly Subscription", "visible": true, "frequency": "MONTH", "interval": 1, "autoRenewal": true } ], "allowOneTimePurchases": true } } } ``` ::: :::: > **Note:** Many product fields in the above example have been omitted for conciseness. ### Scenario A buyer wants to purchase "Coffee" with the following options: - Size: S - Box color: Red - Remove price tag: Yes - Engraving: "For my best friend! :)" - Delivery: Monthly subscription ### Resulting `catalogReference` object ::::tabs :::REST_TAB ```json { "catalogItemId": "dc765ec4-eaf0-4253-8ba7-e752c227d4ca", "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e", "options": { "variantId": "9650a809-5567-44f7-9435-cf77a38cb170", "options": { "Remove price tag": "Yes" }, "customTextFields": { "Would you like to engrave something on the box?": "For my best friend! :)" }, "subscriptionOptionId": "3c750e1e-54fd-4fe0-8844-97427522c939" } } ``` ::: :::SDK_TAB ```json { "catalogItemId": "dc765ec4-eaf0-4253-8ba7-e752c227d4ca", "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e", "options": { "variantId": "9650a809-5567-44f7-9435-cf77a38cb170", "options": { "Remove price tag": "Yes" }, "customTextFields": { "Would you like to engrave something on the box?": "For my best friend! :)" }, "subscriptionOptionId": "3c750e1e-54fd-4fe0-8844-97427522c939" } } ``` ::: :::: ::::tabs :::REST_TAB To find the correct `variantId`, match the `options.id` and `options.choicesSettings.choices.choiceId` of the buyer's selected options with `variantsInfo.variants.optionChoiceIds.optionId` and `variantsInfo.variants.optionChoiceIds.choiceId` in the variants. ::: :::SDK_TAB To find the correct `variantId`, match the `options._id` and `options.choicesSettings.choices.choiceId` of the buyer's selected options with `variantsInfo.variants.optionChoiceIds.optionId` and `variantsInfo.variants.optionChoiceIds.choiceId` in the variants. ::: :::: ### Minimal valid `catalogReference` object Since both modifiers have `"mandatory": false` and `subscriptionDetails.allowOneTimePurchases` is `true`, the following minimal `catalogReference` is also valid: ::::tabs :::REST_TAB ```json { "catalogItemId": "dc765ec4-eaf0-4253-8ba7-e752c227d4ca", "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e", "options": { "variantId": "9650a809-5567-44f7-9435-cf77a38cb170" } } ``` ::: :::SDK_TAB ```json { "catalogItemId": "dc765ec4-eaf0-4253-8ba7-e752c227d4ca", "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e", "options": { "variantId": "9650a809-5567-44f7-9435-cf77a38cb170" } } ``` ::: ::::