Create an add-on on a plan with POST /sites/SITE_ID/plans/PLAN_CODE/add_ons; supply code, name, currencies with unit_amount, and set add_on_type=fixed or add_on_type=usage
For usage-based add-ons, set add_on_type=usage and usage_type=price; report usage with POST /sites/SITE_ID/subscriptions/SUBSCRIPTION_ID/add_ons/ADD_ON_CODE/usage supplying amount and recorded_timestamp
Enroll a subscriber with the add-on by including subscription_add_ons array in the POST /sites/SITE_ID/subscriptions body, each entry with add_on_code and quantity
Update add-on quantity mid-cycle with PUT /sites/SITE_ID/subscriptions/SUBSCRIPTION_ID providing subscription_add_ons with the updated quantity; set timeframe=now for immediate proration or timeframe=renewal for next cycle
Verify add-on charges appear on the preview invoice with POST /sites/SITE_ID/subscriptions/SUBSCRIPTION_ID/change_preview before committing the update
Known gotchas
Usage add-ons aggregate usage between the subscription's current_period_started_at and current_period_ends_at; usage reported outside this window is either dropped or applied to the wrong invoice period
Changing add-on quantity with timeframe=now generates a prorated invoice immediately; ensure the account has a valid billing info to avoid an uncollectable invoice
The add-on code is plan-scoped — the same code can exist on different plans but they are independent objects; referencing the wrong plan's add-on code returns a 404
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp