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 /groups routes.
  • 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}/group routes. 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, pricing and repeat are 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

MethodRouteDescription
GET/groupsList 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/groupsCreate 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

MethodRouteDescription
GET/products/{product_id}/groupGet the product’s own fields. Returns a 404 when the product has none.
PUT/products/{product_id}/groupCreate or replace them.
PATCH/products/{product_id}/groupCreate or update them.
DELETE/products/{product_id}/groupRemove 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.

MethodRouteDescription
GET{base}/fieldsList the fields.
POST{base}/fieldsAdd 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

KeyValues
labels_positionabove or below
instructions_positionlabel, field or tooltip
mark_requiredtrue or false
enable_gallery_images, swap_type, gallery_imagesThe “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)
ConditionMeaningValue
auth / !authThe customer is (not) logged inNone
role / !roleThe customer has (not) this roleA role, like "customer"
products / !productsThe product is (not) one of theseProduct IDs
product_var / !product_varThe selected variation is (not) one of theseVariation IDs
product_cats / !product_catsThe product is (not) in one of these categoriesCategory IDs
p_tags / !p_tagsThe product has (not) one of these tagsTag IDs
product_type / !product_typeThe product is (not) of this typeTypes, like "simple" or "variable"
patts / !pattsThe selected variation has (not) this attribute value"attribute|term", like "color|red", or "color|*" for any value
lang / !langThe 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

KeyDescription
idGenerated by the plugin. Leave it out for a new field.
typeThe field type, see below. Required for a new field.
subtypeOnly for products fields, see below.
label, descriptionThe label and the instructions.
requiredtrue or false.
widthThe field width in %.
css_classExtra CSS classes.
label_positionFor swatches: default, out, hide or tooltip.
hide_cart, hide_checkout, hide_orderHide the field’s value on the cart, checkout or order.
pricingThe price of the field itself (for fields without choices). See “Pricing”.
choicesFor fields with options. See “Choices”.
conditionsWhen the field shows. See “Conditions”.
repeatThe repeater settings. See “Repeater”.
contentThe text of a p (paragraph) field.
image_idThe 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)
TypeMeaning
noneNo price change
fixedFixed flat fee
fixed_per_qtyFlat fee × quantity
percentFixed percentage of the product price
percent_per_qtyPercentage × quantity
formulaA formula. The amount is the formula, like "[qty] * 2"
per_character, per_character_per_qtyAmount × number of characters (× quantity). Text fields only.
per_value, per_value_per_qtyAmount × 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)
  • id is generated by the plugin. Leave it out for a new choice, send it to keep an existing one.
  • label is required. Only products fields can leave it out: then the label is the product’s name.
  • selected means selected by default.
  • image_id is an attachment ID, for image swatches. Send null to remove the image.
  • color is for color swatches.
  • products fields need a product_id for 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.

OperatorMeaning
== / !=The value is (not) equal to. For fields with choices: the selection contains (not) this choice.
contains / !containsThe value contains (not) this text
empty / !emptyThe field is (not) empty. No value needed.
check / !checkThe checkbox is (not) checked
gt / ltThe number is greater / lower than
gtd / ltdThe 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)
CodeStatusMeaning
wcpf_group_not_found404The field group doesn’t exist.
wcpf_product_not_found404The product doesn’t exist.
wcpf_product_group_not_found404The product has no fields of its own.
wcpf_field_not_found404The field isn’t in this group.
wcpf_invalid_product400The product can’t have fields, for example a variation.
wcpf_missing_name400A new field group needs a name.
wcpf_invalid_group400The field group data is invalid.
wcpf_invalid_field400A field is invalid. The message says which one and why.
wcpf_unknown_field400A field ID that doesn’t exist in this group.
wcpf_unknown_choice400A choice ID that doesn’t exist in this field.
wcpf_invalid_rule400A display rule is invalid.
wcpf_invalid_variable400A variable is missing keys.
wcpf_field_in_use409The field can’t be deleted: other fields or variables use it. data.fields and data.variables list them.
wcpf_already_trashed410The field group is already in the trash. Use ?force=true.
wcpf_cannot_save, wcpf_cannot_delete400 / 500Saving 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 section field needs a sectionend field after it.
  • Changes are saved the same way as in the admin, so they show on your shop right away.

Was this article helpful?