REST API Reference

Use the Product Add-Ons REST API to manage global groups and product-specific add-ons. This reference lists the available fields and links to task examples.

Use a test store and WooCommerce REST API credentials with appropriate permissions. Replace example IDs with values from your store. Global group and product updates can remove omitted add-ons; include all fields you want to keep.

Global Add-Ons

↑ Back to top

Global add-ons can be managed via 2 endpoints:

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

Add-On Group Properties

• id (integer, readonly; read only): 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): Send an array of category IDs, or an empty array for all products. Responses contain category objects with IDs and names.
• fields (array[object]; read write): Fields containing the add-ons and their options for the group. See the Add-On Properties section.

Add-On Properties

• id (integer, readonly; read only): 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
• default (string; view edit): Default value or pre-selected option indexes for custom_price, input_multiplier, multiple_choice and checkbox add-ons.
• 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 (string; view edit): Minimum allowed input for custom_text, custom_textarea, custom_price, and input_multiplier add-ons.
• max (string; 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 the Add-On Options Object Properties section.

Add-On Options Object Properties

• 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.
• visibility (boolean; view edit): Visibility of the add-on option.

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):

See the global group examples for the complete request and verification steps.

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.

See the global group examples for the complete request and verification steps.

Add an Add-On to a Global Group

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

See the global group examples for the complete request and verification steps.

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.

See the global group examples for the complete request and verification steps.

Product Add-Ons

↑ Back to top

Product Add-Ons 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):

See the product-specific examples for the complete request and verification steps.

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.

See the product-specific examples for the complete request and verification steps.

Add an Add-On to a Product

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

See the product-specific examples for the complete request and verification steps.

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.

See the product-specific examples for the complete request and verification steps.

Store API integration

↑ Back to top

Product Add-Ons integrates with WooCommerce’s Store API. Use the task guide for a working cart example:

Add a product with add-ons to the cart

↑ Back to top

Here’s an example of a request that adds a product with one add-on of each type to the cart:

See the Store API cart example for the complete request and verification steps.