Tools

Complete reference for the 33 tools exposed by the SolvaPay MCP Server, organised across 8 domains.

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.

Every tool result except get_environment’s starts with an Environment: sandbox or Environment: live line (live is production), followed by the result as JSON. It names the environment the call ran against: your account’s current environment.

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 · clone_product · delete_product	6
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
Environment	get_environment	1
	Total	33

---

​

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
clone_product	Copy a product, including its plans, into a new product
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

​

clone_product

Parameter	Type	Required	Description
reference	string	Yes	Reference of the product to clone
name	string	No	Name for the new product

​

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, discount, 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

---

​

Environment

Tool	Description
get_environment	Get the environment (sandbox or live) this connection works on

​

get_environment

Takes no parameters. Returns { "environment": "sandbox" } or { "environment": "live" }.

With OAuth, this is the environment your account is in, and it changes when you switch in SolvaPay Console. With an API key, it’s the key’s environment, which must match the account’s.