Manage global Product Add-Ons groups with the REST API

Use these examples to create and maintain global add-on groups 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.

For category restrictions, send an array of product category IDs in restrict_to_categories; use an empty array for all categories. Responses include category objects with IDs and names.

These requests are a sequence. Record the group 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 the group with two add-ons. The response contains the IDs needed for subsequent requests.

curl -X POST \
  https://example.com/wp-json/wc-product-add-ons/v2/global-add-ons \
  -u customer_key:customer_secret \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Personalization Options",
  "priority": 5,
  "restrict_to_categories": [],
  "fields": [
    {
      "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": "1",
      "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-product-add-ons/v2/global-add-ons/123 \
  -u customer_key:customer_secret \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Personalization Options for rings",
  "restrict_to_categories": [
    22
  ],
  "fields": [
    {
      "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-product-add-ons/v2/global-add-ons/123 \
  -u customer_key:customer_secret \
  -H "Content-Type: application/json" \
  -d '{
  "fields": [
    {
      "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 group.

curl -X PUT \
  https://example.com/wp-json/wc-product-add-ons/v2/global-add-ons/123 \
  -u customer_key:customer_secret \
  -H "Content-Type: application/json" \
  -d '{
  "fields": [
    {
      "id": 1719406272
    },
    {
      "id": 1719406273
    }
  ]
}'

Verify and troubleshoot

↑ Back to top

Read the group 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.