Use the Product Add-Ons management REST API

Use this reference for authenticated catalog tools that manage POM groups, reusable choices, product-specific definitions, publication revisions, assignments, or integrity information.

Authentication and site scope

• Use an administrator or shop manager account. Remote HTTPS clients can use a WordPress Application Password; logged-in clients use the normal REST nonce.
• Use the URL of the intended multisite site. Records, capabilities, caches, and compatibility IDs are site-scoped.
• Read a record immediately before changing it so the client has its current strong ETag or numeric revision.

The management namespace is:

/wp-json/pom-tweaks/v1/product-add-ons

Routes

type is group, choice, or product. Prefix every route above with the namespace shown earlier.

List records

Group and choice collections accept bounded page, per_page, search, status, orderby, and order parameters. per_page cannot exceed 100. Responses include X-WP-Total and X-WP-TotalPages.

Group records contain the internal name, status, priority, field definition, assignment scope, publication state, revision, and read-only usage. The scope supports:

• all_products, category_ids, include_children, and product_ids;
• include_rules and exclude_rules for product IDs, product types, or terms in a registered product taxonomy;
• include_relation and exclude_relation, each using any or all.

Reusable-choice records contain name, status, config, publication state, revision, and read-only usage. Product configuration contains local_definition, excluded_group_ids, exclude_global, and canonical-language inheritance state.

Create a group

Create an enabled configuration draft that is assigned to one category:

POST /wp-json/pom-tweaks/v1/product-add-ons/groups
Content-Type: application/json

{
  "name": "Gift options",
  "public_name": "Gift options",
  "status": "publish",
  "priority": 20,
  "definition": {
    "fields": []
  },
  "scope": {
    "all_products": false,
    "category_ids": [42],
    "include_children": true,
    "product_ids": [],
    "include_relation": "any",
    "exclude_relation": "any",
    "include_rules": [],
    "exclude_rules": []
  }
}

status describes whether the configuration inside the draft is enabled (publish) or disabled (draft); it does not bypass the separate publication step. The server normalizes the schema and returns the saved record with its ETag. A malformed field, unknown product or term, excessive rule set, or unsupported type rejects the complete write.

Update without overwriting another editor

Read the record and retain its response header:

GET /wp-json/pom-tweaks/v1/product-add-ons/groups/123
ETag: "pom-pao-group-123-r7"

Send the intended update with that precondition:

PATCH /wp-json/pom-tweaks/v1/product-add-ons/groups/123
If-Match: "pom-pao-group-123-r7"
Content-Type: application/json

{
  "name": "Gift and presentation options",
  "priority": 15
}

Every PUT, PATCH, or DELETE must include either the exact If-Match value or the current numeric revision. If both are present, they must agree. A stale precondition returns HTTP 409; a missing precondition returns HTTP 428. Read and reconcile the current record instead of retrying blindly.

The same rule applies to choices and product configuration. A temporary pom_tweaks_product_addons_allow_unversioned_writes filter exists for a controlled migration of one known client, but unversioned writes cannot detect stale edits and should not remain enabled.

Manage product-specific configuration

Read the current source and exclusions:

GET /wp-json/pom-tweaks/v1/product-add-ons/products/123/configuration

Update local_definition, excluded_group_ids, and exclude_global together when the product needs an explicit configuration. Send local_definition: null to remove only the product-specific fields.

For a translated product, send this by itself to remove its complete local override and resume inheritance from the default-language product:

{
  "inherit_canonical": true
}

To create an explicit translated override, send inherit_canonical: false with the complete intended local definition and exclusion values. Responses identify canonical_product_id, configuration_source_product_id, and inherits_canonical.

Explain assignment

Use the explanation route before publishing a broad or complex group:

GET /wp-json/pom-tweaks/v1/product-add-ons/groups/123/explain?product_id=456

The response reports whether the published group applies and explains each inclusion and exclusion. Product-level exclusions win first, group exclusion rules win over inclusion rules, and a variation inherits the variable parent's product type and taxonomy terms.

Publish or restore a revision

Read publication status:

GET /wp-json/pom-tweaks/v1/product-add-ons/publications/group/123

Publish the current draft with its record revision:

{
  "operation": "publish",
  "reason": "Reviewed gift option changes",
  "revision": 7
}

Restore an earlier publication as a new revision with operation: "rollback" and source_revision_id. History is preserved; existing carts and orders keep their stored snapshots.

Delete safely

DELETE /groups/{id} and DELETE /choices/{id} move the record to Trash by default. Add force=true only for intentional permanent deletion. POM returns HTTP 409 with reference_count and a usage summary while any assignment, product exclusion, or field reference remains. There is no bypass that leaves orphaned configuration.

The authenticated /integrity route reports bounded, site-scoped entity counts, ownership, usage maps, orphan counts, and up to 100 samples. It is read-only and never repairs records automatically.

Limits and extension points

The API uses the same field, option, assignment, payload, and text limits as the administration. Important administration defaults include 100 fields per definition, 500 options per field, 2,000 options per definition, 24 include and 24 exclusion rules, 200 values per rule, and 500 advanced-rule values in total.

pom_tweaks_product_addons_assignment_taxonomies can expose an already registered taxonomy attached to products. The filter does not register the taxonomy or grant capabilities. Use pom_tweaks_product_addons_operational_limits only for measured requirements and keep its returned values inside the protected ceilings.

Verify a client

1. List groups with two pages and confirm the totals and stable ordering.
2. Create a draft group, update it with If-Match, and confirm the stale value returns 409 without changing the record.
3. Explain one included product and one excluded product.
4. Publish the draft and confirm the public product route and storefront use it.
5. Trash a linked reusable choice, restore it, and confirm its field relationship remains.
6. Attempt permanent deletion while it is linked and confirm the 409 usage response.
7. Read /integrity as a manager and confirm an anonymous request is rejected.
8. On multisite, repeat a read against another site URL and confirm records do not cross sites.

Troubleshooting

• HTTP 401 or 403: authenticate a user with WooCommerce management permission and use the correct site URL.
• HTTP 409: the record changed or remains referenced; inspect the response before acting.
• HTTP 428: read the record and send its ETag or revision.
• rest_invalid_param: submit the documented public structure instead of private WordPress metadata.
• Missing assignment result: confirm the group is published; the explanation route evaluates published assignment behavior.

Related: Publish and restore configurations, Official Product Add-Ons compatibility, and Health and compatibility checks.