Skip to navigation

write_product_catalog

Create and manage the catalog, coupons and promotion codes

Live server: test server (test.mcp.solvimon.com) only.

Defines the catalog structure and charge type, and manages coupons and promotion codes. Hierarchy: product category (optional) → product → product items and features.

Actions: create, update, delete, activate, deactivate, archive, deprecate. Lifecycle actions apply to products, product items, coupons and promotion codes; deactivate to coupons and promotion codes only.

Resource types: product_categories, products, product_items, features, coupons, promotion_codes

Product item model_type options: RECURRING, PER_SEAT, USAGE_BASED (needs a meter_value_calculation_id), ONE_OFF, CREDITS (needs a credit_type_id). Features are non-billable entitlements such as rate limits or feature flags (NUMBER, AMOUNT, ENUM, SWITCH).

Create a usage-based product item
{
"action": "create",
"resource_type": "product_items",
"body": {
"name": "API calls",
"reference": "api-calls",
"product_id": "prod_Xw3nQr7KmY2vBs8TfLc41",
"model_type": "USAGE_BASED",
"meter_value_calculation_id": "mvc_Jh5tRw9PnX3kMq7VbYd28"
}
}

Coupons and promotion codes.

  • A coupon is always created DRAFT. The result has a summary to confirm before activate.
  • If a coupon with the same discount, duration and scope already exists, the create is refused and the existing one is named so you can reuse it. Pass allow_duplicate_terms: true to create it anyway.
  • A coupon’s terms can’t be edited. Create a replacement and deactivate the old one. Deactivating stops new redemptions; existing holders keep the discount.
  • A promotion code needs an ACTIVE coupon and can only narrow it.
Create a coupon
{"action": "create", "resource_type": "coupons", "body": {"name": "Launch 20", "reference": "launch-20", "discount": {"type": "PERCENTAGE", "percentage": "20"}, "duration": {"type": "PERIOD", "period": {"type": "MONTH", "value": 3}}, "maximum_redemptions": 50}}

model_type is immutable after creation. Creating a product requires category_id, product_type (e.g. DEFAULT) and billing_entity_id alongside name and reference. Guidance (agent_context) or a description in the body is proposed first and saved only with text_confirmed: true, see write_agent_context.

Example prompts

  • “Add a usage-based item ‘API requests’ to our AI API product, billed from the API requests meter.”
  • “Create a coupon: 20% off for the first 3 months, at most 50 redemptions.”
  • “Create promotion code LAUNCH20 for that coupon, limited to 100 uses.”
  • “Add an SSO feature as an on/off switch to the Platform product.”
  • “Deprecate the old Quoting product so no new subscriptions use it.”

Example output

Prompt: “Add a usage-based item ‘API requests’ to the draft AI API product, billed from the API requests meter.”

Tool call:

{
"action": "create",
"resource_type": "product_items",
"body": {
"name": "Docs example API requests",
"reference": "docs-example-api-requests-item",
"product_id": "prod_LwDpzo0vA1bLn9Ce7Q11",
"model_type": "USAGE_BASED",
"meter_value_calculation_id": "mvca_SwDpzo0vA1bBwlCZ7s1j"
}
}

Response (trimmed):

{
"product": {
"id": "prod_LwDpzo0vA1bLn9Ce7Q11",
"name": "Docs example AI API",
"product_type": "DEFAULT",
"status": "DRAFT"
},
"category": {"name": "Monetization Platform"},
"items": [
{
"id": "proi_pwDpzo0vA1bMHRCO7F1N",
"name": "Docs example API requests",
"model_type": "USAGE_BASED",
"status": "DRAFT",
"meter": {"name": "Docs example API requests", "calculation_type": "SUM"}
}
],
"links": {"desk": "https://test.desk.solvimon.com/.../prod_LwDpzo0vA1bLn9Ce7Q11"}
}

Claude’s answer: I added the usage-based item to the product. It sums usage from the API requests meter and is still DRAFT, like the product. Next step is to price it in a pricing plan version with write_pricing_plan, then activate the product.