Documentation Index
Fetch the complete documentation index at: https://docs.solvapay.com/llms.txt
Use this file to discover all available pages before exploring further.
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 |
| Wallet & Revenue | get_product_balance | 1 |
| Usage Tracking | record_usage · record_bulk_usage | 2 |
| Transactions & Refunds | list_transactions · get_transaction · get_transaction_stats · create_refund | 4 |
| Total | 32 |
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 |
recurring, usage-based, one-time, hybrid. Billing cycles: weekly, monthly, quarterly, yearly, custom. Billing models (usage-based only): pre-paid, post-paid.
create_plan
| Parameter | Type | Required | Description |
|---|
productRef | string | Yes | Reference of the product to add the plan to |
type | string | No | recurring (default), usage-based, one-time, or hybrid |
billingCycle | string | Conditional | Required for recurring, hybrid, and post-paid usage-based plans |
price | number | No | Price in minor currency units (e.g. cents) for recurring / one-time |
currency | string | No | ISO 4217 currency code |
setupFee | number | No | One-time setup fee in minor units |
trialDays | number | No | Free trial length in days |
freeUnits | number | No | Free units included per cycle |
limit | number | No | Usage limit for usage-based / hybrid |
billingModel | string | No | pre-paid or post-paid (usage-based only) |
creditsPerUnit | number | No | Credits consumed per usage unit |
basePrice | number | No | Base price for hybrid plans |
rolloverUnusedUnits | boolean | No | Carry unused units to next cycle |
features | object | No | Arbitrary feature flags |
limits | object | No | Named numeric limits |
metadata | object | No | Arbitrary metadata |
default | boolean | No | Mark as the product’s default plan |
status | string | No | active, inactive, or archived |
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 |
type | string | No | — | Filter by plan type |
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 |
billingCycle | string | No | Updated billing cycle |
price | number | No | Updated price (minor units) |
currency | string | No | Updated currency |
setupFee | number | No | Updated setup fee |
trialDays | number | No | Updated trial length |
freeUnits | number | No | Updated free units |
limit | number | No | Updated usage limit |
creditsPerUnit | number | No | Updated credits per unit |
basePrice | number | No | Updated base price (hybrid) |
rolloverUnusedUnits | boolean | No | Updated rollover toggle |
features | object | No | Updated feature flags |
limits | object | No | Updated named limits |
metadata | object | No | Updated metadata |
default | boolean | No | Mark / unmark as default |
status | string | No | Updated status |
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 |
Wallet & Revenue
| Tool | Description |
|---|
get_product_balance | Get revenue for a specific product |
get_product_balance
| Parameter | Type | Required | Description |
|---|
productRef | string | Yes | Product 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) |
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 |
