REST API Reference

This document is written for WooCommerce developers looking to extend or customize WooCommerce Product Addons. It requires an advanced understanding of PHP and WordPress development.

WooCommerce 2.6 added support for REST API endpoints based on the WordPress REST API infrastructure.

Since version 6.9.0, Product Add-Ons includes REST API support, too. This version added new endpoints to work with global add-ons and add-on groups, and extended the WooCommerce core’s products endpoint to interact with product-specific add-ons.

Global Add-Ons

↑ Back to top

Global add-ons can be managed vie 2 endpoints:

  • wc-product-add-ons/v2/global-add-ons
  • wc-product-add-ons/v2/global-add-ons/<group-id>

Add-On Group Properties

Attribute Type Context Description
id integer, readonly read write Global group ID.
name string read write Name of the global group.
priority integer read write Priority of the group.
restrict_to_categories array[int] read write Product categories this group applies to, or an empty array if it applies to all products.
fields array[object] read write Fields containing the add-ons and their options for the group. See below for details on the structure of each add-on object.

Add-On Properties

Attribute Type Context Description
id integer, readonly view edit Unique identifier for the add-on.
name string view edit Name of the product add-on.
title_format string view edit Format of the add-on title. Values: label, heading, hide
description_enable boolean, readonly view edit Status indicating if the add-on description is enabled.
description string view edit Description of the add-on.
placeholder_enable boolean, readonly view edit Status indicating if the add-on placeholder is enabled.
placeholder string view edit Placeholder text for the add-on, applicable for custom_text and custom_textarea add-on types.
type string view edit Type of the add-on. Values: multiple_choice, checkbox, custom_text, custom_textarea, file_upload, custom_price, input_multiplier, heading, datepicker
display string view edit Display options for multiple_choice type add-ons. Values: select, radiobutton, images
position integer view edit Position of the add-on in the product.
required boolean view edit Status indicating if the add-on is required.
restrictions boolean, readonly view edit Status indicating if min/max limits for price or text length are enabled.
restrictions_type string view edit Input restrictions for custom_text type add-ons. Values: any_text, only_letters, only_numbers, only_letters_numbers, email
adjust_price boolean, readonly view edit Status indicating if the add-on adjusts the product price.
price_type string view edit Type of price adjustment for the add-on. Values: flat_fee, quantity_based, percentage_based
price string view edit Price of the add-on, if applicable (numeric string).
min integer view edit Minimum allowed input for custom_text, custom_textarea, custom_price, and input_multiplier add-ons.
max integer view edit Maximum allowed input for custom_text, custom_textarea, custom_price, and input_multiplier add-ons.
options array[object] view edit List of options for multiple_choice and checkbox type add-ons. See below for details on the structure of each add-on options object.

Add-On Options Object Properties

Attribute Type Context Description
label string view edit Label for the add-on option.
price string view edit Price of the add-on option, if applicable (numeric string).
price_type string view edit Type of price adjustment for the add-on option. Values: flat_fee, quantity_based, percentage_based
image integer view edit Image ID for the add-on option for image display type, or 0.

Working with Global Add-On Groups: Examples

↑ Back to top

Create a Global Add-On Group with Add-Ons

Creating a global add-on group with 2 add-ons (one custom text and one multiple choice):

pao-rest-api-v2-create-global-group.sh content:
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_category_ids": [],
          "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": "From the ❤️",
              "min": 0,
              "max": 10
            },
            {
              "name": "Matching pin",
              "type": "multiple_choice",
              "required": false,
              "title_format": "label",
              "price_type": "flat_fee",
              "options": [
                {
                  "label": "Silver",
                  "price": "30",
                  "price_type": "flat_fee"
                },
                {
                  "label": "Gold",
                  "price": "45",
                  "price_type": "flat_fee"
                }
              ]
            }
          ]
        }'
View on Github

Update an Add-On in a Global Group

The following example/request changes:

  • The first add-on:
    • Name is updated to “Handmade Engraving”
    • Price is updated to 120
    • Maximum length is changed to 12 characters
  • The second add-on:
    • One new option is added: a platinum pin

Hint: Leaving any previously defined options out of the request would remove them.

pao-rest-api-v2-update-global-group.sh content:
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_category_ids": [
            22
          ],
          "fields": [
            {
              "id": 1719406272,
              "name": "Handmade Engraving",
              "price": "120",
              "max": 12
            },
            {
              "id": 1719406273,
              "options": [
                {
                  "label": "Silver",
                  "price": "30",
                  "price_type": "flat_fee"
                },
                {
                  "label": "Gold",
                  "price": "45",
                  "price_type": "flat_fee"
                },
                {
                  "label": "Platinum",
                  "price": "50",
                  "price_type": "flat_fee"
                },
              ]
            }
          ]
        }'
View on Github

Add an Add-On to a Global Group

The following request will create a new (third) add-on in the same global group:

pao-rest-api-v2-add-global-group-addon.sh content:
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": [
            {
              "name": "Premium box with custom text",
              "type": "custom_text",
              "price_type": "quantity_based",
              "price": "20"
            }
          ]
        }'
View on Github

Delete an Add-On from a Global Group

This request will keep 2 add-ons with ids 1719406272 and 1719406273 and remove all other add-ons.

pao-rest-api-v2-remove-addon-global-group.sh content:
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
            }
          ]
        }'
View on Github

Product Add-Ons

↑ Back to top

Product Add-Ons version XXX extends the WooCommerce core’s v3/products/ endpoint responses by adding 2 new properties:

  • exclude_global_add_ons — a boolean to specify whether global add-ons apply to this product
  • addons — an array of product-specific add-ons (see the Add-On Properties table for reference on the properties)

The operations on the products endpoint behave in the following way:

  • GET
    • context=view — retrieve product-specific and global add-ons applicable to this product (as you’d see it on the single product page)
    • context=edit — retrieve only product-specific add-ons
  • POST — create a new product with add-ons specified in one request
  • PUT — create, modify, or delete add-ons for an existing product
  • DELETE — delete the whole product. To delete only add-ons, the user needs to use PUT request and supply an empty array of addons.

Working with Product Add-Ons: Examples

↑ Back to top

Create a Product with Add-Ons

Creating a product with 2 add-ons (one custom text and one multiple choice):

pao-rest-api-v2-create-product-with-addons.sh content:
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": "Happiness Ring",
          "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": "From the ❤️",
              "min": 0,
              "max": 10
            },
            {
              "name": "Matching pin",
              "type": "multiple_choice",
              "required": false,
              "title_format": "label",
              "options": [
                {
                  "label": "Silver",
                  "price": "30",
                  "price_type": "flat_fee"
                },
                {
                  "label": "Gold",
                  "price": "45",
                  "price_type": "flat_fee"
                }
              ]
            }
          ]
        }'
View on Github

Update an Add-On for a Product

The following example/request changes:

  • The first add-on:
    • Name is updated to “Handmade Engraving”
    • Price is updated to 120
    • Maximum length is changed to 12 characters
  • The second add-on:
    • One new option is added: a platinum pin

Hint: Leaving any previously defined options out of the request would remove them.

pao-rest-api-v2-update-product-addons.sh content:
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"
                },
                {
                  "label": "Gold",
                  "price": "45",
                  "price_type": "flat_fee"
                },
                {
                  "label": "Platinum",
                  "price": "50",
                  "price_type": "flat_fee"
                }
              ]
            }
          ]
        }'
View on Github

Add an Add-On to a Product

The following request will create a new (third) add-on in the same product:

pao-rest-api-v2-add-product-addon.sh content:
curl -X PUT https://example.com/wp-json/wc/v3/products/123 \
    -u customer_key:customer_secret \
    -H "Content-Type: application/json" \
    -d '{
          "addons": [
            {
              "name": "Premium box with custom text",
              "type": "custom_text",
              "price_type": "quantity_based",
              "price": "20"
            }
          ]
        }'
View on Github

Remove an Add-On from a Product

This request will keep 2 add-ons with ids 1719406272 and 1719406273 and remove all other add-ons.

pao-rest-api-v2-remove-product-addon.sh content:
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
            }
          ]
        }'
View on Github

Questions & Support

↑ Back to top

Have a question before you buy? Please fill out this pre-sales form.
Already purchased and need assistance? Get in touch with us via the Help Desk!