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:

Catalog Reference Object Structure

The catalogReference object includes the following fields:

eCommerceStores Catalog
catalogItemIdThe productId of the Wix Stores product
appIdThe Wix Stores app ID (always "215238eb-22a5-4c36-9e7b-e7c08025e04e")
optionsAn optional object containing product-specific key-value pairs
Copy
{
  "catalogItemId": "<productId>",
  "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e",
  "options": {
    "variantId": "<variantsInfo.variants.id>",
    "options": {
      "<modifiers.key>": "<modifiers.choicesSettings.choices.key>"
    },
    "customTextFields": {
      "<modifiers.freeTextSettings.key>": "<user input>"
    },
    "subscriptionOptionId": "<subscriptionDetails.subscriptions.id>"
  }
}

Important Notes

  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 is not 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:

Copy
{
  "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

Copy
{
  "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"
  }
}

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.optionId 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:

Copy
{
  "catalogItemId": "dc765ec4-eaf0-4253-8ba7-e752c227d4ca",
  "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e",
  "options": {
    "variantId": "9650a809-5567-44f7-9435-cf77a38cb170"
  }
}
Did this help?