Smart Add-Ons REST API | Developer Docs

Base URL & namespace

Base URL: https://your-store.com/wp-json/saue/v1
Namespace: saue/v1

Authentication

Endpoints fall into four access levels:

Public — accessible without authentication. Used by the storefront (price preview, event tracking, addon group retrieval, cart validation).
manage_woocommerce — requires a WordPress user with the manage_woocommerce capability. Send credentials via WordPress REST API authentication (cookie nonce or Application Password).
Nonce — the file upload endpoints require a valid X-WP-Nonce header for the wp_rest action. This is a CSRF check, not a capability check: any visitor with a current page nonce can upload. The storefront bundle sends it automatically via @wordpress/api-fetch.
edit_shop_orders — the order attachment download accepts either edit_shop_orders or manage_woocommerce.

Public endpoints are throttled per IP address and return 429 once the limit is exceeded: 60 requests/minute for /price-preview and /analytics/events, 30 requests/minute for /validate-addons. /addons/product/{product_id} is not throttled.

Example using Application Password:

curl -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx" 
  https://your-store.com/wp-json/saue/v1/addons

Addon Group endpoints

Endpoint	Method	Auth	Description
`/addons`	GET	manage_woocommerce	List every addon group, ordered by priority, with fields and assignments included
`/addons`	POST	manage_woocommerce	Create a new addon group from a JSON body of group, fields, and assignments
`/addons/{id}`	GET	manage_woocommerce	Get a single addon group by ID
`/addons/{id}`	PUT, PATCH	manage_woocommerce	Update an addon group. When fields is sent it replaces the set — any existing field missing from it is deleted. Omitting assignments resets the group to global scope.
`/addons/{id}`	DELETE	manage_woocommerce	Delete an addon group (permanent)
`/addons/{id}/duplicate`	POST	manage_woocommerce	Copy the group and its fields into a new group named "… (copy)"
`/addons/{id}/export`	GET	manage_woocommerce	Return the group as a portable JSON payload (schema version, group, fields)
`/addons/import`	POST	manage_woocommerce	Create a group from an exported JSON payload sent as the request body

Template endpoints

A template is an addon group stored with status "template". Templates carry no product or category assignments and never render on the storefront.

Endpoint	Method	Auth	Description
`/addons/templates`	GET	manage_woocommerce	List every group saved as a template, ordered by name
`/addons/{id}/template`	POST	manage_woocommerce	Convert an existing group into a template, clearing its assignments
`/addons/templates/{id}/create`	POST	manage_woocommerce	Create a new draft group from a template. Optional body keys: name, scope, assignments.

Storefront endpoints (public)

Endpoint	Method	Auth	Description
`/addons/product/{product_id}`	GET	Public	Get all resolved addon groups for a product ID
`/price-preview`	POST	Public	Recalculate the total for a set of selections. All client-supplied price fields are discarded server-side.
`/validate-addons`	POST	Public	Validate field selections before add-to-cart. Returns 422 with an error list when invalid.
`/analytics/events`	POST	Public	Record up to 20 storefront events per request. Accepted event types: addon_view, addon_select, addon_deselect.

Analytics endpoints

Endpoint	Method	Auth	Description
`/analytics/summary`	GET	manage_woocommerce	Aggregate totals for the last ?days days (1–365, default 30): views, selections, conversions, revenue, and the top 5 selected fields

File upload endpoints

Endpoint	Method	Auth	Description
`/upload`	POST	Nonce (X-WP-Nonce)	Upload a file for a file field as multipart/form-data (file, field_id, product_id, session_id). Returns a token, filename, and size.
`/upload/{token}`	DELETE	Nonce (X-WP-Nonce)	Discard a not-yet-claimed upload. Requires the matching field_id and session_id; returns 403 once the file is attached to an order.
`/orders/{order_id}/items/{item_id}/uploads/{field_id}/download`	GET	edit_shop_orders	Stream an uploaded file attached to an order item. Accepts edit_shop_orders or manage_woocommerce.

A/B Test endpoints

Endpoint	Method	Auth	Description
`/ab-tests`	GET	manage_woocommerce	List all A/B tests with their groups, traffic split, status, and winner
`/ab-tests`	POST	manage_woocommerce	Create a new A/B test (name, group A, group B, traffic split, status)
`/ab-tests/{id}`	PUT, PATCH	manage_woocommerce	Update a test — name, status, traffic split, or winner_group_id. Setting a winner is how a test is concluded: the losing group stops rendering on the storefront.
`/ab-tests/{id}`	DELETE	manage_woocommerce	Delete an A/B test (permanent)

AI suggestions endpoint

Endpoint	Method	Auth	Description
`/ai/suggest`	POST	manage_woocommerce	Send product context to the hosted AI service and return its upsell suggestions. Requires a Pro plan or higher; returns 403 otherwise.

Appearance endpoints

Endpoint	Method	Auth	Description
`/appearance`	GET	manage_woocommerce	Get the stored appearance settings together with the CSS generated from them
`/appearance`	PUT, PATCH	manage_woocommerce	Replace the appearance settings from a JSON body. Returns the sanitized settings and regenerated CSS.

License endpoints

Endpoint	Method	Auth	Description
`/license/status`	GET	manage_woocommerce	Get current license status (plan, expiry, features)
`/license/activate`	POST	manage_woocommerce	Activate a license key on this site
`/license/deactivate`	POST	manage_woocommerce	Deactivate the current license (frees an activation slot)

Admin metadata endpoints

These back the pickers and field palette in the plugin admin screens. They are documented for completeness — the response shapes serve the admin UI and may change between releases, so treat them as unstable for external integrations.

Endpoint	Method	Auth	Description
`/lookup/products`	GET	manage_woocommerce	Search published products by ?search, capped at 20 results. Returns id and label pairs.
`/lookup/categories`	GET	manage_woocommerce	Search product categories by ?search, capped at 20 results. Returns id and label pairs.
`/field-types`	GET	manage_woocommerce	List every registered field type and its admin schema, including types added via the saue_register_field_types action

Example: Price preview

addons is an object keyed by field ID, not an array. Pass variation_id as well when the selection belongs to a variable product — pricing is then resolved against the variation.

POST /wp-json/saue/v1/price-preview
Content-Type: application/json

{
  "product_id": 123,
  "quantity": 2,
  "addons": {
    "10": "yes",
    "11": "Happy Birthday!"
  }
}

Response. Money values are strings with two decimals, and base_price is already multiplied by quantity:

{
  "base_price": "99.98",
  "addons_total": "3.00",
  "total": "102.98",
  "breakdown": [
    { "label": "Add gift wrapping: yes", "price": "3.00", "price_formatted": "$3.00" }
  ],
  "quantity_pricing_errors": []
}

Example: Get addon groups for a product

GET /wp-json/saue/v1/addons/product/123

Returns the resolved and ordered list of addon groups assigned to product 123, including all field definitions, options, pricing rules, and conditional logic.

Next: Troubleshooting →

← Hooks & Filters

REST API Reference