> For the complete documentation index, see [llms.txt](https://developers.spiffy.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.spiffy.co/connectors/spiffy/tools.md).

# Tools reference

The connector exposes Spiffy's v2 API as MCP tools, one tool per API operation. Tools are named mechanically:

* `list_*`: list or search a collection (read-only)
* `get_*`: fetch a single record (read-only)
* `create_*`: create a record or perform an action (write)
* `update_*`: modify a record (write)
* `delete_*`: remove a record (destructive)

Every tool carries MCP annotations. Read tools are marked `readOnlyHint`. Write and destructive tools are not, so a well-behaved client asks you to confirm before running them. All tools act only on the authenticated merchant's own data (`openWorldHint: false`).

The Type column below uses those annotations:

* Read: `readOnlyHint: true`, no data changes.
* Write: creates or modifies data.
* Destructive: deletes or cancels data; `destructiveHint: true`.

Tool availability depends on the [scopes you granted](/connectors/spiffy/setup.md#accounts-and-scopes).

> The list below documents the tools at time of writing. Because tools are generated 1:1 from the v2 API, new endpoints appear as new tools automatically. The authoritative, always-current list is whatever the connector advertises via MCP `tools/list` after you connect.

## Utility tools

These have no v2 API analog. They help the assistant reason correctly about time and find answers in Spiffy's docs.

| Tool               | Type | Description                                                                                                                             |
| ------------------ | ---- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `get_utc_time`     | Read | Returns the current UTC time plus your account's configured time zone. The assistant calls this to anchor relative dates ("last week"). |
| `convert_to_utc`   | Read | Converts a local time to UTC ISO 8601, honoring DST. Use when a request mentions a local time.                                          |
| `search_help_docs` | Read | Natural-language search over Spiffy University (help articles, release notes, tutorials).                                               |
| `get_help_article` | Read | Fetches the full markdown of a specific help article found via search.                                                                  |

> **Dates are UTC.** The v2 API treats timestamps as UTC and silently drops time zone offsets. The connector tells the assistant to convert local times with the two tools above; you can also state times in UTC directly.

## Accounts

| Tool            | Type | Description                                          |
| --------------- | ---- | ---------------------------------------------------- |
| `list_accounts` | Read | List the Spiffy accounts this connection can access. |
| `get_account`   | Read | Get details for a single account.                    |

## Customers

| Tool                     | Type        | Description                                  |
| ------------------------ | ----------- | -------------------------------------------- |
| `list_customers`         | Read        | Search and list customers.                   |
| `get_customer`           | Read        | Get a single customer.                       |
| `update_customer`        | Write       | Update a customer's details.                 |
| `preview_customer_merge` | Read        | Preview the result of merging two customers. |
| `merge_customers`        | Write       | Merge two customer records into one.         |
| `list_customer_cards`    | Read        | List a customer's saved payment cards.       |
| `create_customer_card`   | Write       | Add a saved card to a customer.              |
| `delete_customer_card`   | Destructive | Remove a saved card from a customer.         |
| `create_customer_note`   | Write       | Add a note to a customer.                    |

## Orders

| Tool                             | Type        | Description                                        |
| -------------------------------- | ----------- | -------------------------------------------------- |
| `list_orders`                    | Read        | Search and list orders.                            |
| `get_order`                      | Read        | Get a single order.                                |
| `update_order`                   | Write       | Update an order.                                   |
| `update_order_items_canceled`    | Write       | Cancel specific items on an order.                 |
| `refund_order`                   | Destructive | Refund an order.                                   |
| `create_order_note`              | Write       | Add a note to an order.                            |
| `get_order_affiliate_program`    | Read        | Get the affiliate program attribution on an order. |
| `update_order_affiliate_program` | Write       | Change an order's affiliate attribution.           |
| `delete_order_affiliate`         | Destructive | Remove affiliate attribution from an order.        |

## Subscriptions

| Tool                                  | Type        | Description                                  |
| ------------------------------------- | ----------- | -------------------------------------------- |
| `list_subscriptions`                  | Read        | Search and list subscriptions.               |
| `get_subscription`                    | Read        | Get a single subscription.                   |
| `cancel_subscription`                 | Destructive | Cancel a subscription.                       |
| `update_subscription_uncancel`        | Write       | Reverse a pending cancellation.              |
| `update_subscription_hardresume`      | Write       | Force-resume a paused/past-due subscription. |
| `update_subscription_earlyrenewal`    | Write       | Trigger an early renewal.                    |
| `update_subscription_nextbillingdate` | Write       | Change the next billing date.                |
| `update_subscription_price`           | Write       | Change the subscription price.               |
| `update_subscription_discount`        | Write       | Apply or change a subscription discount.     |
| `delete_subscription_discount`        | Destructive | Remove a subscription discount.              |
| `create_subscription_payment`         | Write       | Take a payment on a subscription.            |
| `create_subscription_card`            | Write       | Add a card to a subscription.                |
| `update_subscription_card`            | Write       | Change the card on a subscription.           |
| `create_subscription_note`            | Write       | Add a note to a subscription.                |

## Payment plans

| Tool                                 | Type        | Description                        |
| ------------------------------------ | ----------- | ---------------------------------- |
| `list_paymentplans`                  | Read        | Search and list payment plans.     |
| `get_paymentplan`                    | Read        | Get a single payment plan.         |
| `update_paymentplan_terms`           | Write       | Change a payment plan's terms.     |
| `update_paymentplan_nextbillingdate` | Write       | Change the next billing date.      |
| `update_paymentplan_cancel`          | Destructive | Cancel a payment plan.             |
| `create_paymentplan_pay`             | Write       | Take a payment on a payment plan.  |
| `create_paymentplan_card`            | Write       | Add a card to a payment plan.      |
| `update_paymentplan_card`            | Write       | Change the card on a payment plan. |
| `create_paymentplan_note`            | Write       | Add a note to a payment plan.      |

## Payments

| Tool                   | Type        | Description               |
| ---------------------- | ----------- | ------------------------- |
| `list_payments`        | Read        | Search and list payments. |
| `get_payment`          | Read        | Get a single payment.     |
| `create_payment_retry` | Write       | Retry a failed payment.   |
| `refund_payment`       | Destructive | Refund a payment.         |

## Products

| Tool                            | Type        | Description                               |
| ------------------------------- | ----------- | ----------------------------------------- |
| `list_products`                 | Read        | Search and list products.                 |
| `get_product`                   | Read        | Get a single product.                     |
| `list_product_counts`           | Read        | Get aggregate product counts.             |
| `create_product`                | Write       | Create a product.                         |
| `update_product`                | Write       | Update a product.                         |
| `delete_product`                | Destructive | Delete a product.                         |
| `list_product_actions`          | Read        | List a product's post-purchase actions.   |
| `update_product_actions`        | Write       | Update a product's post-purchase actions. |
| `create_product_option`         | Write       | Add an option to a product.               |
| `update_product_option`         | Write       | Update a product option.                  |
| `delete_product_option`         | Destructive | Delete a product option.                  |
| `sort_product_options`          | Write       | Reorder a product's options.              |
| `list_product_option_actions`   | Read        | List a product option's actions.          |
| `update_product_option_actions` | Write       | Update a product option's actions.        |
| `create_product_price`          | Write       | Add a price to a product.                 |
| `create_product_option_price`   | Write       | Add a price to a product option.          |
| `update_product_option_price`   | Write       | Update a product option price.            |
| `delete_product_option_price`   | Destructive | Delete a product option price.            |
| `move_product_option_price`     | Write       | Move a price between options.             |

## Promos

| Tool                   | Type        | Description                  |
| ---------------------- | ----------- | ---------------------------- |
| `list_promos`          | Read        | Search and list promo codes. |
| `get_promo`            | Read        | Get a single promo.          |
| `create_promo`         | Write       | Create a promo code.         |
| `update_promo`         | Write       | Update a promo code.         |
| `delete_promo`         | Destructive | Delete a promo code.         |
| `list_promo_actions`   | Read        | List a promo's actions.      |
| `update_promo_actions` | Write       | Update a promo's actions.    |

## Affiliates

| Tool                             | Type        | Description                                                                                                               |
| -------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------- |
| `list_affiliates`                | Read        | Search and list affiliates.                                                                                               |
| `get_affiliate`                  | Read        | Get a single affiliate.                                                                                                   |
| `create_affiliate`               | Write       | Create an affiliate.                                                                                                      |
| `update_affiliate`               | Write       | Update an affiliate.                                                                                                      |
| `update_affiliate_checkslugs`    | Write       | Check whether affiliate slugs are available. (Annotated as a write because it is a `PUT` route; it does not modify data.) |
| `list_affiliate_payouts`         | Read        | List affiliate payouts.                                                                                                   |
| `get_affiliate_payout`           | Read        | Get a single affiliate payout.                                                                                            |
| `list_affiliate_payout_current`  | Read        | List the current (open) payout period.                                                                                    |
| `list_affiliate_payout_download` | Read        | Get a downloadable payout export.                                                                                         |
| `create_affiliate_payout`        | Write       | Create an affiliate payout.                                                                                               |
| `update_affiliate_payout`        | Write       | Update an affiliate payout.                                                                                               |
| `delete_affiliate_payout`        | Destructive | Delete an affiliate payout.                                                                                               |

## Affiliate programs

| Tool                                             | Type        | Description                                                                                                          |
| ------------------------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------- |
| `list_affiliate_programs`                        | Read        | List affiliate programs.                                                                                             |
| `get_affiliate_program`                          | Read        | Get a single affiliate program.                                                                                      |
| `create_affiliate_program`                       | Write       | Create an affiliate program.                                                                                         |
| `update_affiliate_program`                       | Write       | Update an affiliate program.                                                                                         |
| `delete_affiliate_program`                       | Destructive | Delete an affiliate program.                                                                                         |
| `list_affiliate_program_affiliates`              | Read        | List affiliates in a program.                                                                                        |
| `create_affiliate_program_affiliate`             | Write       | Add an affiliate to a program.                                                                                       |
| `delete_affiliate_program_affiliate`             | Destructive | Remove an affiliate from a program.                                                                                  |
| `create_affiliate_program_affiliate_adjustments` | Write       | Add commission adjustments for an affiliate.                                                                         |
| `list_affiliate_program_links`                   | Read        | List a program's tracking links.                                                                                     |
| `create_affiliate_program_link`                  | Write       | Create a tracking link.                                                                                              |
| `update_affiliate_program_link`                  | Write       | Update a tracking link.                                                                                              |
| `update_affiliate_program_link_checkslugs`       | Write       | Check whether link slugs are available. (Annotated as a write because it is a `PUT` route; it does not modify data.) |
| `delete_affiliate_program_link`                  | Destructive | Delete a tracking link.                                                                                              |
| `list_affiliate_program_options`                 | Read        | List a program's product options.                                                                                    |
| `create_affiliate_program_option`                | Write       | Add an option to a program.                                                                                          |
| `update_affiliate_program_option`                | Write       | Update a program option.                                                                                             |
| `delete_affiliate_program_option`                | Destructive | Remove an option from a program.                                                                                     |
| `list_affiliate_program_prices`                  | Read        | List a program's prices.                                                                                             |
| `create_affiliate_program_price`                 | Write       | Add a price to a program.                                                                                            |
| `update_affiliate_program_price`                 | Write       | Update a program price.                                                                                              |
| `delete_affiliate_program_price`                 | Destructive | Remove a price from a program.                                                                                       |
| `list_affiliate_program_checkout_items`          | Read        | List a program's checkout items.                                                                                     |
| `create_affiliate_program_checkout`              | Write       | Add a checkout to a program.                                                                                         |
| `update_affiliate_program_checkout`              | Write       | Update a program checkout.                                                                                           |
| `delete_affiliate_program_checkout`              | Destructive | Remove a checkout from a program.                                                                                    |

## Webhooks

| Tool                             | Type        | Description                           |
| -------------------------------- | ----------- | ------------------------------------- |
| `list_webhookendpoints`          | Read        | List webhook endpoints.               |
| `get_webhookendpoints`           | Read        | Get a single webhook endpoint.        |
| `create_webhookendpoints`        | Write       | Create a webhook endpoint.            |
| `update_webhookendpoints`        | Write       | Update a webhook endpoint.            |
| `delete_webhookendpoints`        | Destructive | Delete a webhook endpoint.            |
| `rotate_webhook_endpoint_secret` | Write       | Rotate an endpoint's signing secret.  |
| `test_webhook_endpoint`          | Write       | Send a test event to an endpoint.     |
| `list_webhookendpoints_events`   | Read        | List events delivered to an endpoint. |
| `get_webhookendpoints_event`     | Read        | Get a single delivered event.         |
| `retry_webhook_event`            | Write       | Retry delivery of a webhook event.    |
| `list_webhookevents`             | Read        | List webhook events.                  |
| `list_webhookeventtypes`         | Read        | List available webhook event types.   |

## Integrations

| Tool                             | Type | Description                                         |
| -------------------------------- | ---- | --------------------------------------------------- |
| `list_integration_entity_fields` | Read | List the fields available on an integration entity. |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.spiffy.co/connectors/spiffy/tools.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.