> 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). On the **ChatGPT** connector, payment-facilitation tools are also withheld: anything that makes or retries a charge, refunds a payment, changes a saved card, or changes billing terms is not exposed, because OpenAI's platform policy does not allow assistants to facilitate payments. These tools are available on Claude and other MCP clients, and over the HTTP v2 API. See [Limitations](/connectors/spiffy/limitations.md). > 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. | | `check_affiliate_slugs` | Read | Check whether affiliate slugs are available. | | `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. | | `download_affiliate_payout_csv` | Read | Download a single payout's commissions as CSV. | | `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. | | `check_affiliate_link_slugs` | Read | Check whether link slugs are available within a program. | | `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. | ## Analytics Requires the `analytics` scope. | Tool | Type | Description | | ---------------------------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query_analytics` | Read | Run a metrics query over orders, subscriptions, or billing data for a time window. Supports grouping by attribution dimension, product, or checkout, and optional comparison to a prior period. | | `get_analytics_capabilities` | Read | Return the full analytics catalog: available metrics, dimensions, groupBy options, and supported comparison modes. Call this to discover what query\_analytics accepts. | ## Reports Requires the `reports` scope. | Tool | Type | Description | | ------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------- | | `list_report_types` | Read | List the six available report types with their filters, datasets, columns, and date presets. | | `list_reports` | Read | List saved reports for the account. | | `get_report` | Read | Get a single saved report. | | `create_report` | Write | Create a saved report with a type, filter set, date range, and optional schedule. | | `update_report` | Write | Update a saved report's name, filters, schedule, or active status. | | `delete_report` | Destructive | Soft-delete a saved report. | | `create_report_run` | Write | Trigger an async run of a saved report. Returns 202 with the run in pending status; poll get\_report\_run until complete. | | `list_report_runs` | Read | List runs for a saved report. | | `get_report_run` | Read | Get a single run with its status and, when complete, its stats block. | | `list_report_run_results` | Read | Get a page of run results in compact tabular form (positional row arrays matched to columns). | | `create_report_export` | Write | Create a short-lived signed download URL for the run's full dataset as CSV. | ## Integrations | Tool | Type | Description | | -------------------------------- | ---- | --------------------------------------------------- | | `list_integration_entity_fields` | Read | List the fields available on an integration entity. | ## Activity log | Tool | Type | Description | | ------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `list_events` | Read | List audit events — the account activity log (subscription changes, payments, card updates, notes). Filter by type, name, customer, order, subscription, and date. |