REST API
Please note this article is meant for the premium version of the plugin (version 3.2.3 or newer).
Advanced Product Fields has a REST API to read, create, update and delete field groups and their fields. You can use it to manage your product options from another system, like an ERP, a PIM or your own scripts, without opening the WordPress admin.
All routes live under:
https://your-shop.com/wp-json/wc-product-fields/v1Code language: JavaScript (javascript)
Authentication
The API uses the standard WordPress and WooCommerce authentication. You can use any of these:
- WooCommerce REST API keys (WooCommerce > Settings > Advanced > REST API). Use the consumer key and secret the same way as for the WooCommerce API. Give the key “Read/Write” permissions if you want to make changes.
- Application Passwords (Users > Profile > Application Passwords), sent with HTTP Basic authentication.
- Cookie authentication with a nonce, for requests made from the WordPress admin itself.
The user behind the request needs the same capability as for editing field groups in the admin. By default this is manage_options (administrators). You can change it with the wapf/setting/capability filter.
An example request with WooCommerce API keys:
curl https://your-shop.com/wp-json/wc-product-fields/v1/groups \
-u ck_xxxxxxxx:cs_xxxxxxxxCode language: JavaScript (javascript)
Key concepts
Field groups and a product’s own fields
There are two places where fields can live:
- Field groups (WooCommerce > Product Fields). A field group has display rules that decide on which products it shows. Use the
/groupsroutes. - A product’s own fields, added on the product edit screen. They always show on that product, so they have no display rules. Use the
/products/{product_id}/grouproutes. Variations can’t have their own fields: use the parent product.
IDs are created by us
Fields and choices get their ID from the plugin. When you add a new field or choice, leave the id out. The response contains the generated ID. When you send an id, it always refers to an existing field or choice. An unknown ID returns an error.
Because of this, a condition can only refer to a field or choice that already exists. To create a field that depends on another new field, first create the fields, then add the condition with the IDs from the response.
PUT and PATCH
- PUT replaces the whole resource. Fields you leave out are removed, and settings you leave out go back to their default.
- PATCH (or POST on an existing resource) only changes what you send. Fields are merged by their
id, and fields you don’t send are kept. Within a field,pricingandrepeatare merged too, so you can send only{"pricing": {"amount": 5}}.
Lists are always replaced as a whole when you send them: choices, conditions, display_rules and variables. To change one choice, send the field’s full choices list, with the id of every choice you want to keep.
All or nothing
Every request is checked completely before anything is saved. If one field, choice or rule is invalid, the request returns an error and nothing is changed.
Endpoints
Field groups
| Method | Route | Description |
|---|---|---|
| GET | /groups | List field groups. Parameters: status (any, publish, draft, trash), search (searches the name), page, per_page (max. 100). The headers X-WP-Total and X-WP-TotalPages contain the totals. |
| POST | /groups | Create a field group. name is required. |
| GET | /groups/{id} | Get one field group. |
| PUT | /groups/{id} | Replace a field group. |
| PATCH | /groups/{id} | Update a field group. |
| DELETE | /groups/{id} | Move a field group to the trash. Add ?force=true to delete it permanently. Returns the deleted group. |
A product’s own fields
| Method | Route | Description |
|---|---|---|
| GET | /products/{product_id}/group | Get the product’s own fields. Returns a 404 when the product has none. |
| PUT | /products/{product_id}/group | Create or replace them. |
| PATCH | /products/{product_id}/group | Create or update them. |
| DELETE | /products/{product_id}/group | Remove them. Returns the removed group. |
When a product ends up with no fields and no variables, its group is removed, the same as on the product edit screen. The response is then a 204 No Content.
Fields
These routes work on one field at a time. They exist for field groups and for a product’s own fields. Replace {base} with /groups/{id} or /products/{product_id}/group.
| Method | Route | Description |
|---|---|---|
| GET | {base}/fields | List the fields. |
| POST | {base}/fields | Add a field. The body is the field, without an id. Add ?position=0 to insert it at that position (0 is first), otherwise it’s added at the end. On a product without fields, this creates its group. |
| GET | {base}/fields/{field_id} | Get one field. |
| PUT | {base}/fields/{field_id} | Replace a field. It keeps its position. type is required. |
| PATCH | {base}/fields/{field_id} | Update a field. |
| DELETE | {base}/fields/{field_id} | Delete a field. Returns the deleted field. Fails with a 409 when the conditions of other fields or variables use this field. |
The field group object
{
"id": 123,
"name": "Engraving options",
"status": "publish",
"date_created": "2026-10-22T08:00:00",
"date_modified": "2026-10-22T09:30:00",
"display_rules": [
[ { "condition": "product_cats", "value": [ 15 ] } ]
],
"layout": {
"labels_position": "above",
"instructions_position": "field",
"mark_required": true
},
"variables": [],
"fields": [
{
"id": "a1b2c3d",
"type": "radio",
"label": "Color",
"required": true,
"pricing": { "type": "none", "amount": 0 },
"conditions": [],
"repeat": { "enabled": false },
"choices": [
{ "id": "x7k2p", "label": "Red", "selected": false, "disabled": false, "pricing": { "type": "fixed", "amount": 5 } },
{ "id": "m3q9z", "label": "Blue", "selected": false, "disabled": false, "pricing": { "type": "none", "amount": 0 } }
]
}
]
}Code language: JavaScript (javascript)
A product’s own group looks the same, but has product_id instead of id, name, status and the dates, and has no display_rules.
Layout
| Key | Values |
|---|---|
labels_position | above or below |
instructions_position | label, field or tooltip |
mark_required | true or false |
enable_gallery_images, swap_type, gallery_images | The “change product image” settings. |
Display rules
Display rules decide on which products a field group shows. They’re a list of rule groups. The group shows when one rule group matches, and a rule group matches when all its rules match:
"display_rules": [
[ { "condition": "products", "value": [ 12, 34 ] }, { "condition": "!role", "value": "wholesale" } ],
[ { "condition": "product_cats", "value": [ 15 ] } ]
]Code language: JavaScript (javascript)
| Condition | Meaning | Value |
|---|---|---|
auth / !auth | The customer is (not) logged in | None |
role / !role | The customer has (not) this role | A role, like "customer" |
products / !products | The product is (not) one of these | Product IDs |
product_var / !product_var | The selected variation is (not) one of these | Variation IDs |
product_cats / !product_cats | The product is (not) in one of these categories | Category IDs |
p_tags / !p_tags | The product has (not) one of these tags | Tag IDs |
product_type / !product_type | The product is (not) of this type | Types, like "simple" or "variable" |
patts / !patts | The selected variation has (not) this attribute value | "attribute|term", like "color|red", or "color|*" for any value |
lang / !lang | The current language is (not) this one (WPML or Polylang) | A language code |
IDs aren’t checked against your shop, so requests stay fast. An ID that doesn’t exist simply never matches.
The field object
| Key | Description |
|---|---|
id | Generated by the plugin. Leave it out for a new field. |
type | The field type, see below. Required for a new field. |
subtype | Only for products fields, see below. |
label, description | The label and the instructions. |
required | true or false. |
width | The field width in %. |
css_class | Extra CSS classes. |
label_position | For swatches: default, out, hide or tooltip. |
hide_cart, hide_checkout, hide_order | Hide the field’s value on the cart, checkout or order. |
pricing | The price of the field itself (for fields without choices). See “Pricing”. |
choices | For fields with options. See “Choices”. |
conditions | When the field shows. See “Conditions”. |
repeat | The repeater settings. See “Repeater”. |
content | The text of a p (paragraph) field. |
image_id | The attachment ID of an img field. |
Type-specific settings use the same names as in the plugin, for example placeholder, default, minlength, maxlength, minimum, maximum, step, min_choices, max_choices, items_per_row, items_per_row_tablet and items_per_row_mobile. Tip: create a field in the admin and GET it to see all its settings.
Field types
text, textarea, number, email, url, select, checkboxes, radio, true-false, image-swatch, multi-image-swatch, image-swatch-qty, card, vcard, color-swatch, multi-color-swatch, text-swatch, multi-text-swatch, file, p (paragraph), img (image), section and sectionend.
date is available when the date picker is enabled in the plugin settings. The Extended version also has calc and products. A products field needs a subtype: checkbox, radio, dropdown, image, card, vcard, card-qty or vcard-qty.
Field types added by other plugins (through the wapf/field_types filter) work too.
Pricing
Fields and choices both use the same pricing object:
"pricing": { "type": "fixed", "amount": 5 }Code language: JavaScript (javascript)
| Type | Meaning |
|---|---|
none | No price change |
fixed | Fixed flat fee |
fixed_per_qty | Flat fee × quantity |
percent | Fixed percentage of the product price |
percent_per_qty | Percentage × quantity |
formula | A formula. The amount is the formula, like "[qty] * 2" |
per_character, per_character_per_qty | Amount × number of characters (× quantity). Text fields only. |
per_value, per_value_per_qty | Amount × the entered number (× quantity). Number fields only. |
For a products field, choices use only none, fixed or custom: fixed charges the product’s own price, none adds the product for free and custom charges the amount you set (0 is free).
Choices
{
"id": "x7k2p",
"label": "Red",
"description": "A bright red finish",
"selected": false,
"disabled": false,
"pricing": { "type": "fixed", "amount": 5 },
"image_id": 456,
"color": "#ff0000"
}Code language: JavaScript (javascript)
idis generated by the plugin. Leave it out for a new choice, send it to keep an existing one.labelis required. Onlyproductsfields can leave it out: then the label is the product’s name.selectedmeans selected by default.image_idis an attachment ID, for image swatches. Sendnullto remove the image.coloris for color swatches.productsfields need aproduct_idfor every choice, also for the choices you keep.
Conditions
Conditions decide when a field shows, based on the values of other fields in the same group. They work like display rules: the field shows when one rule group matches, and a rule group matches when all its rules match.
"conditions": [
[ { "field": "a1b2c3d", "operator": "==", "value": "x7k2p" } ]
]Code language: JavaScript (javascript)
field is the ID of another field in the same group. For fields with choices, value is the ID of a choice.
| Operator | Meaning |
|---|---|
== / != | The value is (not) equal to. For fields with choices: the selection contains (not) this choice. |
contains / !contains | The value contains (not) this text |
empty / !empty | The field is (not) empty. No value needed. |
check / !check | The checkbox is (not) checked |
gt / lt | The number is greater / lower than |
gtd / ltd | The date is later / earlier than |
Not every operator applies to every field type. Use the ones the admin offers for that type.
Repeater
"repeat": {
"enabled": true,
"type": "button",
"add_label": "Add another",
"remove_label": "Remove",
"max": 5
}Code language: JavaScript (javascript)
type is field, button or qty.
Variables
Variables can be used in formulas as [var_name]. All keys are required:
"variables": [
{
"name": "discount",
"default": "0",
"rules": [
{ "type": "qty", "field": "qty", "condition": "gt", "value": "10", "variable": "5" }
]
}
]Code language: JavaScript (javascript)
The variable takes the variable value of the first rule that matches, otherwise its default. A rule checks a field’s value ("type": "field") or the quantity ("type": "qty").
Examples
Change the price of a choice
Send the field’s full list of choices, with the IDs of the choices you keep:
PATCH /wp-json/wc-product-fields/v1/groups/123/fields/a1b2c3d
{
"choices": [
{ "id": "x7k2p", "label": "Red", "pricing": { "type": "fixed", "amount": 7.5 } },
{ "id": "m3q9z", "label": "Blue", "pricing": { "type": "none", "amount": 0 } }
]
}Code language: JavaScript (javascript)
Add a field to a product
POST /wp-json/wc-product-fields/v1/products/456/group/fields
{
"type": "text",
"label": "Engraving text",
"maxlength": 20,
"pricing": { "type": "per_character", "amount": 0.5 }
}Code language: JavaScript (javascript)
Show a field only when a choice is selected
First create both fields, then add the condition with the IDs from the response:
PATCH /wp-json/wc-product-fields/v1/groups/123/fields/e5f6a7b
{
"conditions": [
[ { "field": "a1b2c3d", "operator": "==", "value": "x7k2p" } ]
]
}Code language: JavaScript (javascript)
Errors
Errors use the standard WordPress format:
{
"code": "wcpf_unknown_field",
"message": "Field at index 0: unknown field id \"zzz\". Leave the id out for a new field.",
"data": { "status": 400 }
}Code language: JavaScript (javascript)
| Code | Status | Meaning |
|---|---|---|
wcpf_group_not_found | 404 | The field group doesn’t exist. |
wcpf_product_not_found | 404 | The product doesn’t exist. |
wcpf_product_group_not_found | 404 | The product has no fields of its own. |
wcpf_field_not_found | 404 | The field isn’t in this group. |
wcpf_invalid_product | 400 | The product can’t have fields, for example a variation. |
wcpf_missing_name | 400 | A new field group needs a name. |
wcpf_invalid_group | 400 | The field group data is invalid. |
wcpf_invalid_field | 400 | A field is invalid. The message says which one and why. |
wcpf_unknown_field | 400 | A field ID that doesn’t exist in this group. |
wcpf_unknown_choice | 400 | A choice ID that doesn’t exist in this field. |
wcpf_invalid_rule | 400 | A display rule is invalid. |
wcpf_invalid_variable | 400 | A variable is missing keys. |
wcpf_field_in_use | 409 | The field can’t be deleted: other fields or variables use it. data.fields and data.variables list them. |
wcpf_already_trashed | 410 | The field group is already in the trash. Use ?force=true. |
wcpf_cannot_save, wcpf_cannot_delete | 400 / 500 | Saving or deleting failed. |
WordPress itself can also return errors, like rest_forbidden (401/403) when the user isn’t allowed, or rest_invalid_param (400) when a parameter has the wrong type.
Good to know
- When you delete a field, formulas that use it (
[field.id]) aren’t checked. Update those formulas yourself. - Sections are pairs: a
sectionfield needs asectionendfield after it. - Changes are saved the same way as in the admin, so they show on your shop right away.