Documentation

Mix and Match: Store API Reference

Overview

WooCommerce Mix and Match Products is compatible with the WooCommerce Store API, which powers the front-end cart, checkout, and product data for modern, JavaScript-driven storefronts (including block-based themes, headless implementations, and custom front-end apps).

This guide provides a reference for how Mix and Match containers are represented in Store API requests and responses, including details about adding Mix and Match products to the cart, retrieving container contents, and updating configurations.

What is the Store API?

↑ Back to top

The Store API is WooCommerce’s public REST API designed specifically for front-end features. It exposes endpoints for building headless or decoupled stores, powering features such as product browsing, cart operations, and checkout flows.

Unlike the classic WooCommerce REST API (used mainly for authenticated integrations and admin‑level data), the Store API is unauthenticated and does not provide access to sensitive store or customer data. Instead, it focuses purely on powering front‑end experiences and is optimized for customer-facing interactions.

These are core WooCommerce endpoints; Mix and Match Products (MNM) works by passing its own parameters through these standard routes to handle its custom (MNM) product type.

How Mix and Match Works with the Store API

↑ Back to top

A Mix and Match product is added to the cart as a single container line item with its contents specified via the mnm_config parameter. The server validates the configuration to ensure the container rules are met.

Each container in the cart has a unique key which is generated automatically by WooCommerce when the container is added to the cart. It’s a unique hash (e.g., mnm_abc123) that identifies that specific configuration and quantity combination. You’ll use this key when updating or removing the container.

Relevant Endpoints

↑ Back to top

Some commonly used Store API endpoints for Mix and Match Products:

Endpoint	Purpose
`POST /wp-json/wc/store/v1/cart/add-item`	Add a Mix and Match container with its configuration to the cart.
`GET /wp-json/wc/store/v1/cart`	Retrieve the cart, including containers and their contents.
`POST /wp-json/wc/store/v1/cart/update-item`	Update the container’s configuration (e.g., change child items).
`DELETE /wp-json/wc/store/v1/cart/remove-item`	Remove a container from the cart using its key.
`GET /store/products`	Retrieve Mix and Match product data (details), show options, pricing, etc.

For information about all of WooCommerce’s Store API endpoints, please see their documentation here.

Request Format: Adding a Mix and Match Product (Simple Child Products)

↑ Back to top

When adding a Mix and Match product, you must send a POST request to /wp-json/wc/store/v1/cart/add-item with the container ID and child item configuration using mnm_config.

Example: Add a Mix and Match product containing only Simple Child Products

POST /wp-json/wc/store/v1/cart/add-item
{
  "id": 99,
  "quantity": 1,
  "mnm_config": [
    {
      "product_id": 15,
      "quantity": 3
    },
    {
      "product_id": 100,
      "quantity": 3
    }
  ]
}

Request Parameters for Adding a Mix and Match Product (Simple Child Products)

↑ Back to top

Below is an explanation of each parameter used when adding a Mix and Match product (containing only Simple Child Products) via the Store API:

id: The product ID of the Mix and Match container product. Obtain this from the Products admin or the /store/products endpoint.
quantity: The number of containers to add. For unique configurations, this is typically 1.
mnm_config: An object defining the child items selected for this container.
- product_id: The product ID of the individual child product.
- quantity: The number of units of that child product inside the container.

Include these correctly in your request to ensure the Mix and Match container is added to the cart as intended.

Response Format: Cart with Mix and Match Container

↑ Back to top

When retrieving the cart, the container appears as a single line item with a mnm_config property listing the configured products.

Example Response

{
  "items": [
    {
      "key": "mnm_abc123",
      "id": 123,
      "name": "6-Pack Snack Box",
      "quantity": 1,
      "totals": {
        "line_subtotal": "20.00",
        "line_total": "20.00"
      },
      "mnm_config": [
        {
          "product_id": 456,
          "name": "Chocolate Bar",
          "quantity": 2
        },
        {
          "product_id": 457,
          "name": "Granola Bite",
          "quantity": 1
        }
      ]
    }
  ]
}

Response Format for Cart with Mix and Match Container

↑ Back to top

Below is an explanation of each property returned when retrieving a cart that contains a Mix and Match container:

key: A unique identifier that is generated automatically by WooCommerce when the container is added to the cart. It’s a unique hash (e.g., mnm_abc123) that identifies that specific configuration and quantity combination. Needed for updating or removing the container.
id: The product ID of the Mix and Match container.
name: The name of the container product.
quantity: How many containers of this configuration are in the cart.
totals: The pricing details for this container line item.
- line_subtotal: The total price before any discounts.
- line_total: The total price after discounts.
mnm_config: An array of child products included in this container.
- product_id: The product ID of the child item.
- name: The name of the child product.
- quantity: The quantity of each child product inside the container.

These details allow your front-end to display the full container configuration and pricing to the customer.

Updating a Mix and Match Container

↑ Back to top

To change the configuration of an existing container in the cart, use the POST /wp-json/wc/store/v1/cart/update-item endpoint with the container’s key and a new mnm_config object.

Example: Update Container

POST /wp-json/wc/store/v1/cart/update-item
{
  "key": "mnm_abc123",
  "quantity": 1,
  "mnm_config": [
    {
      "product_id": 15,
      "quantity": 2
    },
    {
      "product_id": 100,
      "quantity": 4
    }
  ]
}

Request Parameters for Updating a Mix and Match Container

↑ Back to top

Below is an explanation of each parameter used when updating a Mix and Match container via the Store API:

key: The unique cart item key for the container to update. This is retrieved from a previous cart response.
quantity: The updated quantity of this container in the cart. This is optional if you’re only updating the configuration.
mnm_config: An object defining the new child items for the container.
- product_id: The product ID of the child product.
- quantity: The new quantity for each child product inside the container.

Include these correctly in your request to update an existing Mix and Match container and its configuration.

Notes and Best Practices

↑ Back to top

Validation: Mix and Match child quantities are always validated server-side to ensure they match the container’s rules.
Client-side UI: For headless or custom JS stores, ensure your UI lets customers configure child items correctly before adding to the cart.
Cart Key: Each Mix and Match container in the cart has a unique key, which must be included when updating or removing the container.
Compatibility: Most standard Store API functionality works as expected with Mix and Match containers, but test custom front-end workflows thoroughly.

Related Resources

↑ Back to top

Questions & Support

↑ Back to top

Something missing from this documentation? Do you still have questions and need assistance?

Have a question before you buy this extension? Please fill out this pre-sales form – please include the name of this extension in your query.
Already purchased and need some assistance? Get in touch with the developer via the WooCommerce.com Support page and choose this extension name from the “I need help with” dropdown. Please include a clear description of the issue.