Tools - SolvaPay Documentation

The SolvaPay MCP Server gives AI agents — and any MCP-compatible client — full programmatic access to your SolvaPay account. Every tool follows a consistent request/response pattern and accepts JSON parameters as described below.

Parameters marked Required must always be provided. Optional parameters can be omitted and will either use a sensible default or be ignored.

Domain	Tools	Count
Customer Management	`create_customer` · `get_customer` · `list_customers` · `update_customer` · `delete_customer` · `ensure_customer`	6
Product Management	`create_product` · `get_product` · `list_products` · `update_product` · `delete_product`	5
Plan Management	`create_plan` · `get_plan` · `list_plans` · `list_plans_for_product` · `update_plan` · `delete_plan`	6
Purchase Management	`list_purchases` · `get_purchase` · `get_purchases_by_customer` · `get_purchases_by_product` · `cancel_renewal` · `check_limits`	6
Payment & Checkout	`create_checkout_session` · `create_customer_session`	2
Usage Tracking	`record_usage` · `record_bulk_usage`	2
Transactions & Refunds	`list_transactions` · `get_transaction` · `get_transaction_stats` · `create_refund`	4
	Total	31

Customer Management

Tool	Description
`create_customer`	Create a new customer
`get_customer`	Retrieve a customer by reference
`list_customers`	List customers with search and pagination
`update_customer`	Update a customer’s details
`delete_customer`	Delete a customer
`ensure_customer`	Create or retrieve a customer by email (idempotent)

create_customer

Parameter	Type	Required	Description
`email`	string	Yes	Customer email address
`name`	string	No	Customer display name
`telephone`	string	No	Customer telephone number
`metadata`	object	No	Arbitrary key-value metadata

get_customer

Parameter	Type	Required	Description
`reference`	string	Yes	Customer reference (e.g. `cus_A1B2C3D4`)

list_customers

Parameter	Type	Required	Default	Description
`limit`	number	No	20	Maximum results to return
`offset`	number	No	0	Pagination offset
`search`	string	No	—	Search by name or email

update_customer

Parameter	Type	Required	Description
`reference`	string	Yes	Customer reference
`name`	string	No	Updated name
`email`	string	No	Updated email
`telephone`	string	No	Updated telephone
`metadata`	object	No	Updated metadata

delete_customer

Parameter	Type	Required	Description
`reference`	string	Yes	Customer reference

ensure_customer

Creates a customer if one doesn’t exist for the given email. Returns the existing customer if found.

Parameter	Type	Required	Description
`email`	string	Yes	Customer email (used as unique key)
`name`	string	No	Customer name (used only on creation)
`externalRef`	string	No	Your system’s ID for this customer

Product Management

Tool	Description
`create_product`	Create a new product
`get_product`	Retrieve a product by reference
`list_products`	List products with search and filters
`update_product`	Update a product’s details
`delete_product`	Delete a product

create_product

Parameter	Type	Required	Description
`name`	string	Yes	Product name
`description`	string	No	Product description

get_product

Parameter	Type	Required	Description
`reference`	string	Yes	Product reference (e.g. `prd_P9Q0R1S2`)

list_products

Parameter	Type	Required	Default	Description
`limit`	number	No	20	Maximum results
`offset`	number	No	0	Pagination offset
`search`	string	No	—	Search by name
`status`	string	No	—	Filter by status

update_product

Parameter	Type	Required	Description
`reference`	string	Yes	Product reference
`name`	string	No	Updated name
`description`	string	No	Updated description

delete_product

Parameter	Type	Required	Description
`reference`	string	Yes	Product reference

Plan Management

Tool	Description
`create_plan`	Create a new plan inside a product
`get_plan`	Retrieve a specific plan within a product
`list_plans`	List all plans across all products
`list_plans_for_product`	List plans belonging to a specific product
`update_plan`	Update an existing plan
`delete_plan`	Delete a plan

A plan is an ordered options[] list. Recurring / usage-based / hybrid / one-time is a derived label — do not send type, creditsPerUnit, basePrice, setupFee, or freeUnits. See Plans.

create_plan

Parameter	Type	Required	Description
`productRef`	string	Yes	Reference of the product to add the plan to
`name`	string	Yes	Plan name
`options`	array	Yes	Composable pricing options (`charge`, `billingCycle`, `tier`, `limit`, `entitlement`, `trial`, `prepaid`, `discount`, `rollover`, `autoAssigned`, `hidden`)
`description`	string	No	Plan description
`currency`	string	No	ISO 4217 display currency (defaults from options)
`features`	object	No	Arbitrary feature flags
`metadata`	object	No	Arbitrary metadata
`status`	string	No	`active`, `inactive`, or `archived`
`maxActiveUsers`	number	No	Optional concurrent-user cap
`accessExpiryDays`	number	No	Optional access lifetime
`taxBehavior`	string	No	`auto`, `inclusive`, or `exclusive`

Example options for a $19/month plan:

[
  { "kind": "billingCycle", "interval": "month" },
  { "kind": "charge", "per": "flat", "amountMinor": 1900, "currency": "USD" }
]

get_plan

Parameter	Type	Required	Description
`productRef`	string	Yes	Reference of the product
`planRef`	string	Yes	Reference of the plan

list_plans

Parameter	Type	Required	Default	Description
`limit`	number	No	20	Maximum results
`offset`	number	No	0	Pagination offset
`status`	string	No	—	Filter by status
`requiresPayment`	boolean	No	—	Filter by whether any charge amount is positive
`search`	string	No	—	Search by name

list_plans_for_product

Parameter	Type	Required	Description
`productRef`	string	Yes	Reference of the product

update_plan

Parameter	Type	Required	Description
`productRef`	string	Yes	Reference of the product
`planRef`	string	Yes	Reference of the plan to update
`name`	string	No	Updated name
`description`	string	No	Updated description
`currency`	string	No	Updated display currency
`options`	array	No	Replacement `options[]` (send the full list)
`features`	object	No	Updated feature flags
`metadata`	object	No	Updated metadata
`status`	string	No	Updated status
`maxActiveUsers`	number	No	Updated concurrent-user cap
`accessExpiryDays`	number	No	Updated access lifetime
`taxBehavior`	string	No	`auto`, `inclusive`, or `exclusive`

delete_plan

Parameter	Type	Required	Description
`productRef`	string	Yes	Reference of the product
`planRef`	string	Yes	Reference of the plan to delete

Purchase Management

Tool	Description
`list_purchases`	List all purchases
`get_purchase`	Retrieve a purchase by reference
`get_purchases_by_customer`	Purchases for a customer
`get_purchases_by_product`	Purchases for a product
`cancel_renewal`	Cancel renewal of a purchase
`check_limits`	Check usage limits for a customer/product pair

list_purchases

Parameter	Type	Required	Description
`status`	string	No	Filter by status

get_purchase

Parameter	Type	Required	Description
`reference`	string	Yes	Purchase reference

get_purchases_by_customer

Parameter	Type	Required	Description
`customerRef`	string	Yes	Customer reference
`status`	string	No	Filter by status

get_purchases_by_product

Parameter	Type	Required	Description
`productRef`	string	Yes	Product reference
`status`	string	No	Filter by status

cancel_renewal

Parameter	Type	Required	Description
`purchaseRef`	string	Yes	Purchase reference
`reason`	string	No	Cancellation reason

check_limits

Returns usage-limit status for a customer/product pair. If limits are exceeded, the response includes a checkout URL for the customer to upgrade.

Parameter	Type	Required	Description
`customerRef`	string	Yes	Customer reference
`productRef`	string	Yes	Product reference

Payment & Checkout

Tool	Description
`create_checkout_session`	Generate a checkout URL
`create_customer_session`	Generate a customer billing-portal URL

create_checkout_session

Parameter	Type	Required	Description
`customerRef`	string	Yes	Customer reference
`productRef`	string	Yes	Product reference
`planRef`	string	No	Plan reference (uses the product’s default plan if omitted)
`returnUrl`	string	No	Redirect URL after checkout completes

create_customer_session

Generates a URL where the customer can manage their billing, payment methods, and purchases.

Parameter	Type	Required	Description
`customerRef`	string	Yes	Customer reference

Usage Tracking

Tool	Description
`record_usage`	Record a single usage event
`record_bulk_usage`	Record multiple usage events in one call

record_usage

Parameter	Type	Required	Description
`customerRef`	string	Yes	Customer reference
`productRef`	string	Yes	Product reference
`outcome`	string	Yes	Outcome identifier (e.g. `success`, `failure`)
`action`	string	No	Action name
`requestId`	string	No	Idempotency / correlation ID
`actionDuration`	number	No	Duration in milliseconds

record_bulk_usage

Parameter	Type	Required	Description
`events`	array	Yes	Array of usage-event objects (same schema as `record_usage`)

Each object in events accepts the same fields as record_usage.

Transactions & Refunds

Tool	Description
`list_transactions`	List transactions with filters
`get_transaction`	Retrieve a transaction by reference
`get_transaction_stats`	Get transaction count and statistics
`create_refund`	Refund a transaction (full or partial)

list_transactions

Parameter	Type	Required	Default	Description
`limit`	number	No	20	Maximum results
`offset`	number	No	0	Pagination offset
`status`	string	No	—	Filter by status
`fromDate`	string	No	—	Start date (ISO 8601)
`toDate`	string	No	—	End date (ISO 8601)

get_transaction

Parameter	Type	Required	Description
`transactionRef`	string	Yes	Transaction reference

get_transaction_stats

Parameter	Type	Required	Description
`fromDate`	string	No	Start date (ISO 8601)
`toDate`	string	No	End date (ISO 8601)

create_refund

Parameter	Type	Required	Description
`sourceTransactionRef`	string	Yes	Transaction reference to refund
`amount`	number	No	Partial refund amount (omit for a full refund)
`reason`	string	No	Refund reason

​Customer Management

​create_customer

​get_customer

​list_customers

​update_customer

​delete_customer

​ensure_customer

​Product Management

​create_product

​get_product

​list_products

​update_product

​delete_product

​Plan Management

​create_plan

​get_plan

​list_plans

​list_plans_for_product

​update_plan

​delete_plan

​Purchase Management

​list_purchases

​get_purchase

​get_purchases_by_customer

​get_purchases_by_product

​cancel_renewal

​check_limits

​Payment & Checkout

​create_checkout_session

​create_customer_session

​Usage Tracking

​record_usage

​record_bulk_usage

​Transactions & Refunds

​list_transactions

​get_transaction

​get_transaction_stats

​create_refund

Customer Management

create_customer

get_customer

list_customers

update_customer

delete_customer

ensure_customer

Product Management

create_product

get_product

list_products

update_product

delete_product

Plan Management

create_plan

get_plan

list_plans

list_plans_for_product

update_plan

delete_plan

Purchase Management

list_purchases

get_purchase

get_purchases_by_customer

get_purchases_by_product

cancel_renewal

check_limits

Payment & Checkout

create_checkout_session

create_customer_session

Usage Tracking

record_usage

record_bulk_usage

Transactions & Refunds

list_transactions

get_transaction

get_transaction_stats

create_refund