# Tools · Sales and plans

> MCP tools for selling: listing plans, products and coupons, creating billing options and plans with add-ons as drafts, publishing and unpublishing, changing prices, creating, editing and deleting coupons and downsell offers, deleting products and plans and reordering plans, with confirmation for anything that touches money.

What the community sells: plans with their billing options and add-ons, one-off products, coupons. Everything starts as a draft and only goes on sale when you ask; changing a price, creating or editing a coupon, creating or editing a last-chance offer and deleting ask for your yes, with a summary of the amounts. Changing a plan (`update_plan`) runs on the first call.

## Drafts before approval

You can set everything up **before** the [business information](/pagamentos/informacao-comercial) is approved: products, options, plans, add-ons, coupons and downsell offers start as drafts and can be edited as much as you like. What waits for approval is **publishing and selling**:

- `publish_product` in a community without approval is refused with Memberfy's message: *"To publish and start selling, the community needs approved business information. Meanwhile you can create and configure everything as a draft: fill it in under Settings › Business Information and submit it for review."*
- In the composite tools (`create_course`, `create_event` and `create_plan` with publish), the refusal **undoes nothing**: the course, the event, the ticket, the plan and the options stay as drafts, the response gives the reason in `publish_blocked`, and the suggested next step is to fill in the business information and then publish with `publish_product`.
- A draft's price is in the currency of the business information's country (in any status) or, without it, in reais. If the approved currency is a different one, publishing is refused (*"This product is priced in …, but the approved business information uses …"*): adjust the currency and the price first.

Each tool carries a badge: <span class="tool-kind tool-kind-read">Read-only</span> changes nothing, <span class="tool-kind tool-kind-write">Changes</span> creates or changes something right away, and <span class="tool-kind tool-kind-confirm">Asks to confirm</span> only acts after your yes to a summary. See [Money and confirmation](/mcp/dinheiro-e-confirmacao).

## In short

| Tool | What it does | Minimum role | Type |
|---|---|---|---|
| [`list_plans`](#list-plans) | Plans, options and add-ons | Admin or finance | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`list_products`](#list-products) | Billing options and products, with price and status | Admin or finance | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`list_coupons`](#list-coupons) | Coupons with status and usage | Admin or finance | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`create_product`](#create-product) | Creates a product or billing option, as a draft | Admin | <span class="tool-kind tool-kind-write">Changes</span> |
| [`create_plan`](#create-plan) | Options, plan and add-ons, in one go | Admin | <span class="tool-kind tool-kind-write">Changes</span> |
| [`publish_product`](#publish-product) | Puts a product on sale | Admin | <span class="tool-kind tool-kind-write">Changes</span> |
| [`unpublish_product`](#unpublish-product) | Takes a product off sale | Admin | <span class="tool-kind tool-kind-write">Changes</span> |
| [`update_price`](#update-price) | Changes a price, with confirmation | Admin | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`create_coupon`](#create-coupon) | Creates a coupon, with confirmation | Admin | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`update_plan`](#update-plan) | Changes a plan's name, address, options and add-ons | Admin | <span class="tool-kind tool-kind-write">Changes</span> |
| [`update_product`](#update-product) | Changes title, spaces, stock, installments, trial and direct link | Admin | <span class="tool-kind tool-kind-write">Changes</span> |
| [`update_coupon_status`](#update-coupon-status) | Pauses or reactivates a coupon | Admin | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`update_coupon`](#update-coupon) | Changes a coupon's name, discount, duration, limits, validity and products | Admin | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`delete_coupon`](#delete-coupon) | Deletes a coupon | Admin | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`get_coupon_usage`](#get-coupon-usage) | Who used a coupon | Admin or finance | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`list_downsell_offers`](#list-downsell-offers) | A plan's last-chance offers, with conversion | Admin | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`create_downsell_offer`](#create-downsell-offer) | Creates a last-chance offer | Admin | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`update_downsell_offer`](#update-downsell-offer) | Changes or pauses a last-chance offer | Admin | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`delete_downsell_offer`](#delete-downsell-offer) | Deletes a last-chance offer | Admin | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`delete_product`](#delete-product) | Deletes a product or billing option | Admin | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`delete_plan`](#delete-plan) | Deletes a plan | Admin | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`reorder_plans`](#reorder-plans) | Puts the plans in a new order on the pricing page | Admin | <span class="tool-kind tool-kind-write">Changes</span> |
| [`get_storefront`](#get-storefront) | What a Store space shows | Admin | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`update_storefront`](#update-storefront) | Chooses a Store's products | Admin | <span class="tool-kind tool-kind-write">Changes</span> |

## `list_plans`

<span class="tool-kind tool-kind-read">Read-only</span>

**List plans.** The community's plans, with each one's billing options and add-ons. *Minimum role: admin or finance.*

Parameters: none.

**Returns:** the plans (id, name, address), each plan's options (id, title, price, interval, status) and the add-ons.

**Ask like this:** *"What plans do we have, and how much does each option cost?"*

## `list_products`

<span class="tool-kind tool-kind-read">Read-only</span>

**List billing options and products.** All products: subscription options, one-time products, installment products and add-ons. *Minimum role: admin or finance.*

Parameters: none.

**Returns:** each product with id, title, type, price, interval, status (draft or published) and the spaces it unlocks. The id is what `create_plan` (in `add_on_ids`), `update_price`, `publish_product` and `create_coupon` need.

**Ask like this:** *"Which products are still drafts?"*

## `list_coupons`

<span class="tool-kind tool-kind-read">Read-only</span>

**List coupons.** The coupons, with status and usage. *Minimum role: admin or finance.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `status` | `ACTIVE`, `INACTIVE`, `EXPIRED` | No | Only one status |
| `search` | text | No | Part of the code or name |
| `page`, `limit` | number | No | Pagination |

**Returns:** the coupons, with code, type, value, duration, validity, limit and uses.

**Ask like this:** *"Which coupons are active, and how many times has each been used?"*

## `create_product`

<span class="tool-kind tool-kind-write">Changes</span>

**Create billing option or product.** Creates a product **as a draft**: a subscription option, a one-time product (ticket, course) or an installment product. *Minimum role: admin.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `title` | text, 3 to 255 | Yes | |
| `type` | `SUBSCRIPTION`, `ONE_TIME`, `INSTALLMENT` | Yes | Subscription option, one-time or installment |
| `price` | number, in the community's currency | Yes | For a subscription, the amount per cycle; for annual in installments, the amount for the year |
| `interval` | `MONTHLY`, `YEARLY` | No | Only for `SUBSCRIPTION`: monthly or annual |
| `max_installments` | 1 to 12 | No | Up to how many card installments (one-time, or annual) |
| `commitment_months` | 1 to 36 | No | [Contract length](/monetizacao/duracao-do-contrato); monthly only |
| `trial_days` | 0 to 365 | No | Free trial |
| `description` | plain text, up to 5,000 | No | No formatting: Markdown marks are stripped |
| `space_ids` | list of ids | No | The spaces the purchase unlocks |
| `stock` | number | No | Quantity on sale (tickets). Empty: no limit |
| `direct_link` | yes or no | No | A one-time product sold by direct link, outside the Store |

**Returns:** the new product, as a draft, with its id.

**Ask like this:** *"Create the product One-off mentoring, R$ 450, in up to 3 installments, unlocking the Mentoring space. Leave it as a draft."*

**Notes:** nothing is sold until `publish_product`, and creating doesn't depend on approved business information (see [Drafts before approval](#drafts-before-approval)). For a plan with several options, `create_plan` does it all at once. Each field follows the same rules as in the dashboard: see [Products](/monetizacao/produtos) and [Billing options](/monetizacao/opcoes-de-cobranca).

## `create_plan`

<span class="tool-kind tool-kind-write">Changes</span>

**Create plan with options and add-ons.** Billing options → plan with the options → linked add-ons. *Minimum role: admin.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | text, up to 120 | Yes | The plan name |
| `description` | plain text | No | No formatting: Markdown marks are stripped |
| `slug` | text, up to 60 | No | The plan's address, for the `/pricing/<address>` link |
| `options` | list, 1 to 6 | Yes | The billing options (see below) |
| `add_on_ids` | list of ids | No | Existing monthly products that aren't a plan option, from `list_products` |
| `publish` | yes or no | No | Publishes all options. Default: draft |
| `idempotency_key` | text, up to 100 | No | |

Each **option**:

| Field | Type | Description |
|---|---|---|
| `title` | text, 3 to 255 | Required. E.g. *Mentoring · Monthly* |
| `price` | number, in the community's currency | Required. For annual, the amount for the year |
| `interval` | `MONTHLY`, `YEARLY` | Default: `MONTHLY` |
| `max_installments` | 1 to 12 | For annual, up to how many card installments |
| `commitment_months` | 1 to 36 | Minimum contract, for monthly |
| `trial_days` | 0 to 365 | Free trial |
| `description` | plain text | No formatting: Markdown marks are stripped |
| `space_ids` | list of ids | The spaces the option unlocks |

**Returns:** the plan (id, name, address), the options (id, title, price, interval, status) and the linked add-ons.

**Ask like this:** *"Create the Mentoring plan with a R$ 390 monthly option with a 6-month contract and a R$ 3,900 annual option in up to 12 installments, both unlocking the Mentoring space, and link One-on-one session as an add-on."*

**Notes:** if a step fails, the plan is undone last, because Memberfy won't delete a plan that still has options. See [Plans](/monetizacao/planos), [Add-ons](/monetizacao/adicionais) and [Annual in installments](/monetizacao/anual-parcelado).

## `publish_product`

<span class="tool-kind tool-kind-write">Changes</span>

**Publish product (put on sale).** Puts a draft product on sale. *Minimum role: admin.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `product_id` | id | Yes | From `list_products` or from a create call |

**Returns:** the product, published.

**Ask like this:** *"Go ahead and publish the Excel from Scratch product."*

**Notes:** publishing requires approved [business information](/pagamentos/informacao-comercial), and the product in the approved country's currency. Without that, Memberfy refuses and the product stays a draft, editable. See [Drafts before approval](#drafts-before-approval).

## `unpublish_product`

<span class="tool-kind tool-kind-write">Changes</span>

**Take product off sale.** Takes a product off sale. Anyone who already bought it keeps access. *Minimum role: admin.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `product_id` | id | Yes | |

**Returns:** the product, off sale.

**Ask like this:** *"Take the October meetup ticket off sale."*

## `update_price`

<span class="tool-kind tool-kind-confirm">Asks to confirm</span>

**Change a product's price.** Changes the price of a product or billing option. *Minimum role: admin.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `product_id` | id | Yes | From `list_products` |
| `new_price` | number, in reais | Yes | |

**The summary:** the product, the current price, the new price and the status (draft or published).

**Ask like this:** *"Raise Growth Monthly from R$ 129 to R$ 149."*

**Notes:** existing subscriptions follow Memberfy's rules for price changes, the same as editing in the dashboard. See [Billing options](/monetizacao/opcoes-de-cobranca#changing-an-option-that-already-has-subscribers).

## `create_coupon`

<span class="tool-kind tool-kind-confirm">Asks to confirm</span>

**Create coupon.** Creates a discount coupon, a percentage or a fixed amount, for all products or only some. *Minimum role: admin.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `code` | text, 2 to 50 | Yes | E.g. `PRO20`. Stored in uppercase |
| `name` | text, up to 120 | Yes | The internal name |
| `type` | `PERCENTAGE`, `FIXED` | Yes | Percentage or fixed amount |
| `value` | number | Yes | 20 = 20%, or the amount in reais |
| `duration` | `ONCE`, `FOREVER`, `REPEATING` | No | For subscriptions: first charge only (default), always, or for some months |
| `months` | 1 to 36 | No | With `REPEATING` |
| `max_uses` | number | No | Empty: no limit |
| `start_date` | ISO 8601 date | No | Default: now |
| `end_date` | ISO 8601 date | No | Empty: no end |
| `product_ids` | list of ids | No | Only these products. Empty: all |

**The summary:** the action, the code, the discount (*20%* or *R$ 50.00*), the duration, the usage limit, the validity and the products.

**Ask like this:** *"Create the coupon BLACK30, 30% on the first charge only, for the Growth plans, up to 100 uses, valid until 11/30."*

See [Coupons](/monetizacao/cupons).

## `update_plan`

<span class="tool-kind tool-kind-write">Changes</span>

**Edit plan.** Changes a plan's name, description, address, whether it is active, its billing options and its add-ons. *Minimum role: admin.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `plan` | id or link (`/pricing/…`) | Yes | |
| `name`, `description`, `slug` | text | No | |
| `active` | yes or no | No | |
| `option_ids` | list of ids | No | The plan's **whole** list of options |
| `add_on_ids` | list of ids | No | The **whole** list of add-ons |

**Ask like this:** *"Remove the annual option from the Growth plan and keep only the monthly."*

**Notes:** it changes what is sold right away, without confirmation. Prices change with `update_price`, which asks for your yes.

## `update_product`

<span class="tool-kind tool-kind-write">Changes</span>

**Edit product.** Changes title, descriptions, the spaces it unlocks, stock, installments, free trial or direct link. *Minimum role: admin.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `product` | id or slug | Yes | |
| `title`, `description`, `short_description` | text | No | |
| `space_ids` | list of ids | No | The spaces the purchase unlocks |
| `stock` | number | No | |
| `max_installments` | number | No | |
| `trial_days` | number | No | |
| `direct_link` | yes or no | No | |

**Ask like this:** *"Raise the ticket's stock to 120."*

**Notes:** the price is changed with `update_price`, which asks for confirmation.

## `update_coupon_status`

<span class="tool-kind tool-kind-confirm">Asks to confirm</span>

**Pause or reactivate coupon.** Pauses or reactivates a coupon. *Minimum role: admin.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `coupon` | id or code | Yes | |
| `status` | `ACTIVE`, `INACTIVE` | Yes | Reactivate or pause |

**Ask like this:** *"Pause the BLACK30 coupon."*

## `update_coupon`

<span class="tool-kind tool-kind-confirm">Asks to confirm</span>

**Edit coupon.** Changes an existing coupon. Only what is sent changes; pausing is done with `update_coupon_status`. *Minimum role: admin.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `coupon` | id or code | Yes | |
| `name`, `description` | text | No | |
| `value` | number | No | Percentage (20 = 20%) or amount, depending on the coupon's type |
| `duration` | `ONCE`, `FOREVER`, `REPEATING` | No | Once, forever or for a few months |
| `months` | 1 to 36 | No | With `REPEATING` |
| `max_uses`, `max_uses_per_person` | number | No | Usage limits |
| `start_date`, `end_date` | date | No | The validity |
| `product_ids` | list of ids | No | The products the coupon applies to |

**Returns:** on the first call, the code and what changes, and the confirmation code.

**Ask like this:** *"Raise BLACK30 to 40% and extend it until Sunday."*

See [Coupons](/monetizacao/cupons).

## `delete_coupon`

<span class="tool-kind tool-kind-confirm">Asks to confirm</span>

**Delete coupon.** Discounts already given remain valid. *Minimum role: admin.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `coupon` | id or code | Yes | |

**Returns:** on the first call, the code and how many times it was used, and the confirmation code.

## `get_coupon_usage`

<span class="tool-kind tool-kind-read">Read-only</span>

**View coupon usage.** Who used it, when and how much discount. *Minimum role: admin or finance.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `coupon` | id or code | Yes | |
| `page` | number | No | |

**Ask like this:** *"Who used the BLACK30 coupon?"*

## `list_downsell_offers`

<span class="tool-kind tool-kind-read">Read-only</span>

**A plan's downsell offers.** The discount offers on add-ons after a plan is bought, with how many times they were shown and converted. *Minimum role: admin.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `plan` | id or link | Yes | |

**Ask like this:** *"How well does the last-chance offer for the Coworking Extension convert?"*

## `create_downsell_offer`

<span class="tool-kind tool-kind-confirm">Asks to confirm</span>

**Create downsell offer.** Creates a discount offer on an add-on, shown after the plan is paid. *Minimum role: admin.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `plan` | id or link | Yes | |
| `add_on_id` | id | Yes | The plan's add-on |
| `discount_percent` | number | No | |
| `timing` | `IMMEDIATE`, `DELAYED` | No | Right away (default) or after some time |
| `delay_minutes` | number | No | With `DELAYED` |
| `price_duration` | `FOREVER`, `FIRST_CHARGE`, `CYCLES` | No | Discount forever, only on the first charge, or for a number of cycles |
| `cycles` | number | No | With `CYCLES` |
| `ttl_minutes` | number | No | How long the offer is valid |

**Ask like this:** *"Offer 30% off the Coworking Extension to people who subscribe to Growth without it, for the first 3 charges."*

See [Downsell](/monetizacao/downsell).

## `update_downsell_offer`

<span class="tool-kind tool-kind-confirm">Asks to confirm</span>

**Edit downsell offer.** Changes a plan's last-chance offer, or pauses it. Only what is sent changes. *Minimum role: admin.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `plan` | id or link | Yes | |
| `offer_id` | id | Yes | From `list_downsell_offers` |
| `discount_percent`, `timing`, `delay_minutes`, `price_duration`, `cycles`, `ttl_minutes` | | No | The same as in `create_downsell_offer` |
| `active` | yes or no | No | With no, pauses the offer |

**Ask like this:** *"Pause the Coworking Extension offer until the end of the month."*

## `delete_downsell_offer`

<span class="tool-kind tool-kind-confirm">Asks to confirm</span>

**Delete downsell offer.** *Minimum role: admin.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `plan` | id or link | Yes | |
| `offer_id` | id | Yes | From `list_downsell_offers` |

## `delete_product`

<span class="tool-kind tool-kind-confirm">Asks to confirm</span>

**Delete product.** Deletes a product or a billing option. Whoever bought it keeps access. *Minimum role: admin.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `product` | id or slug | Yes | From `list_products` |

**Returns:** on the first call, the title, the price and the status, and the confirmation code.

**Notes:** to just stop selling, prefer `unpublish_product`. See [Products](/monetizacao/produtos).

## `delete_plan`

<span class="tool-kind tool-kind-confirm">Asks to confirm</span>

**Delete plan.** Existing subscribers aren't canceled. *Minimum role: admin.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `plan` | id or link (`/pricing/…`) | Yes | |

**Returns:** on the first call, the plan's name and its options, and the confirmation code.

## `reorder_plans`

<span class="tool-kind tool-kind-write">Changes</span>

**Reorder plans.** Puts the plans in a new order on the pricing page, from first to last. *Minimum role: admin.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `plan_ids` | list of ids | Yes | From `list_plans`, in the new order |

**Ask like this:** *"On the pricing page, put Growth before Starter."*

## `get_storefront`

<span class="tool-kind tool-kind-read">Read-only</span>

**View store.** What a Store space shows: all products or only the chosen ones. *Minimum role: admin.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `space` | id or link | Yes | The Store space |

## `update_storefront`

<span class="tool-kind tool-kind-write">Changes</span>

**Choose the store's products.** Sets what a Store space sells. *Minimum role: admin.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `space` | id or link | Yes | |
| `mode` | `all`, `selected` | Yes | All published products, or only the chosen ones |
| `product_ids` | list of ids | No | With `selected`, from `list_products` |

**Ask like this:** *"Leave only the one-off courses in the store."*

See [Store](/espacos/loja).

## Related

- [Tools](/mcp/ferramentas)
- [Recipes](/mcp/receitas)
- [Money and confirmation](/mcp/dinheiro-e-confirmacao)