> ## 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.

# Tools

> Complete reference for the 32 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.

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

| Domain                                           | Tools                                                                                                                            |  Count |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | -----: |
| [Customer Management](#customer-management)      | `create_customer` · `get_customer` · `list_customers` · `update_customer` · `delete_customer` · `ensure_customer`                |      6 |
| [Product Management](#product-management)        | `create_product` · `get_product` · `list_products` · `update_product` · `delete_product`                                         |      5 |
| [Plan Management](#plan-management)              | `create_plan` · `get_plan` · `list_plans` · `list_plans_for_product` · `update_plan` · `delete_plan`                             |      6 |
| [Purchase Management](#purchase-management)      | `list_purchases` · `get_purchase` · `get_purchases_by_customer` · `get_purchases_by_product` · `cancel_renewal` · `check_limits` |      6 |
| [Payment & Checkout](#payment--checkout)         | `create_checkout_session` · `create_customer_session`                                                                            |      2 |
| [Revenue](#revenue)                              | `get_product_balance`                                                                                                            |      1 |
| [Usage Tracking](#usage-tracking)                | `record_usage` · `record_bulk_usage`                                                                                             |      2 |
| [Transactions & Refunds](#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                              |

Plan types: `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 |

***

## 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`) |

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                                  |