Manage product-specific add-ons with the REST API

Use these examples to create and maintain a product and its add-ons using the WooCommerce REST API.

For endpoint and field definitions, see the Product Add-Ons REST API reference.

Before you start

↑ Back to top

Use a test store with WooCommerce and Product Add-Ons active. Create WooCommerce REST API credentials with read and write access, and use HTTPS. Replace the example URL and credentials; never put real keys in source control. Replace example IDs with IDs returned by your store.

These requests are a sequence. Record the product ID and the add-on IDs returned by the create request; replace the example IDs in later requests. A PUT that includes the add-on array replaces its membership: include every add-on you want to retain. Leaving an option out of an updated options array removes it.

Create

↑ Back to top

Create a draft product with two add-ons. The response contains the IDs needed for subsequent requests.

curl -X POST \
  https://example.com/wp-json/wc/v3/products \
  -u customer_key:customer_secret \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Happiness Ring",
  "status": "draft",
  "type": "simple",
  "regular_price": "21.99",
  "description": "Beautiful ring that will make you happy.",
  "exclude_global_add_ons": true,
  "addons": [
    {
      "name": "Engraving",
      "title_format": "label",
      "description": "Add a handmade engraving to your ring",
      "type": "custom_text",
      "display": "select",
      "restrictions_type": "any_text",
      "price_type": "flat_fee",
      "price": "100",
      "placeholder": "For you",
      "min": 0,
      "max": 10
    },
    {
      "name": "Matching pin",
      "type": "multiple_choice",
      "required": false,
      "title_format": "label",
      "default": "0",
      "options": [
        {
          "label": "Silver",
          "price": "30",
          "price_type": "flat_fee",
          "visibility": true
        },
        {
          "label": "Gold",
          "price": "45",
          "price_type": "flat_fee",
          "visibility": true
        }
      ]
    }
  ]
}'

Update

↑ Back to top

Update the first add-on and replace the second add-on’s options. Keep the existing options you need.

curl -X PUT \
  https://example.com/wp-json/wc/v3/products/123 \
  -u customer_key:customer_secret \
  -H "Content-Type: application/json" \
  -d '{
  "addons": [
    {
      "id": 1719406272,
      "name": "Handmade Engraving",
      "price": "120",
      "max": 12
    },
    {
      "id": 1719406273,
      "options": [
        {
          "label": "Silver",
          "price": "30",
          "price_type": "flat_fee",
          "visibility": true
        },
        {
          "label": "Gold",
          "price": "45",
          "price_type": "flat_fee",
          "visibility": true
        },
        {
          "label": "Platinum",
          "price": "50",
          "price_type": "flat_fee",
          "visibility": true
        }
      ]
    }
  ]
}'

Add an add-on

↑ Back to top

Keep the existing add-ons by ID and add a new field.

curl -X PUT \
  https://example.com/wp-json/wc/v3/products/123 \
  -u customer_key:customer_secret \
  -H "Content-Type: application/json" \
  -d '{
  "addons": [
    {
      "id": 1719406272
    },
    {
      "id": 1719406273
    },
    {
      "name": "Premium box with custom text",
      "type": "custom_text",
      "price_type": "quantity_based",
      "price": "20"
    }
  ]
}'

Remove an add-on

↑ Back to top

List the add-ons to keep. Omitted add-ons are removed from this product.

curl -X PUT \
  https://example.com/wp-json/wc/v3/products/123 \
  -u customer_key:customer_secret \
  -H "Content-Type: application/json" \
  -d '{
  "addons": [
    {
      "id": 1719406272
    },
    {
      "id": 1719406273
    }
  ]
}'

Verify and troubleshoot

↑ Back to top

Read the product back using GET and confirm the add-on IDs, field values, and options match the intended result. If the request fails, check the endpoint, HTTPS credentials, permissions, and IDs. If an add-on disappears, compare the full array sent in the update with the fields you intended to keep.