> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage examples

> Use MCP for queries, investigations and safe changes, with prompts and complete calls.

You can talk in natural language; the client assembles the MCP calls. The examples below show the JSON only to make each decision verifiable.

## The safest pattern

<Steps>
  <Step title="Read the context">
    Call `get_chargefy_account_info` and confirm organization, environment and
    access.
  </Step>

  <Step title="Discover the operation">
    Use `chargefy_api_search` instead of guessing the `operation_id`.
  </Step>

  <Step title="Read the contract">
    Check `chargefy_api_details`, especially before a write.
  </Step>

  <Step title="Verify the current state">
    Read the resource or find the right ID before changing anything.
  </Step>

  <Step title="Write with confirmation and idempotency">
    Show the operation, `data`, ID and environment; then use a fresh
    `intent_id`.
  </Step>
</Steps>

<Info>
  Human confirmation is a client policy or an instruction of yours. The server
  validates scope, capability, schema and idempotency, but it does not open a
  confirmation screen on every write. Writing is split into
  `chargefy_api_create` (additive) and `chargefy_api_update` (announced as
  destructive), so clients that respect the annotation ask for confirmation
  before each update.
</Info>

## Recommended opening prompt

> Use the Chargefy connection. First show the organization, the environments and the access level. Work in test. Do reads only until I authorize a change. Before any write, show the tool, the operation, the IDs, the `data` and the `intent_id`.

That prompt avoids three common mistakes: an implicit environment, a guessed operation and a change without review.

## Querying data

### List customers

Ask:

> List the 10 most recent customers in the test environment. Do not change data.

After confirming the context, the read call can be:

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "limit": 10,
    "livemode": false,
    "operation": "customers.list"
  },
  "name": "chargefy_api_read"
}
```

If the connection only holds test, `livemode` can be omitted.

### Filter by email

Filters belong to the operation. Check `chargefy_api_details` before using them:

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "filters": {
      "email": "name@email.com"
    },
    "limit": 10,
    "operation": "customers.list"
  },
  "name": "chargefy_api_read"
}
```

Unknown keys are rejected; they are not silently ignored.

### Retrieve by ID

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "id": "inv_nzaq15x9dEszxCj3",
    "operation": "invoices.get"
  },
  "name": "chargefy_api_read"
}
```

The result is the full public object. An ID from another organization or environment is not returned.

## Finding a resource without knowing the ID

Use the text search for customers, catalog, discounts, links and invoices:

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "query": "essential",
    "resources": [
      "products",
      "prices"
    ]
  },
  "name": "search_chargefy_resources"
}
```

The search returns summaries. Once you have the right IDs, load the full objects:

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "ids": [
      "prod_HtXRoNzqYjmy2pQk",
      "price_SdZX69Sm47CoNX6m"
    ]
  },
  "name": "fetch_chargefy_resources"
}
```

<Tip>
  `fetch_chargefy_resources` is useful for investigating relationships: gather
  up to 25 IDs found in objects or events and load them all in one call.
</Tip>

## Discovering before executing

When the goal does not yet point at a clear operation, search:

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "query": "payment link",
    "risk": "R1"
  },
  "name": "chargefy_api_search"
}
```

Then read the contract of the one you picked:

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "operation": "payment_links.create"
  },
  "name": "chargefy_api_details"
}
```

Use the returned `input_schema` to build `data`. The reference at `documentation_url` explains product rules that do not fit in a schema.

## Creating data

### Create a customer

Ask:

> In test, prepare a customer with the email `name@email.com`. Show the call and wait for my confirmation.

After the confirmation:

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "data": {
      "email": "name@email.com",
      "metadata": {},
      "name": "Customer"
    },
    "intent_id": "9f4c1e0a-5b7d-4c2e-9a01-3d8f6b2c7e51",
    "livemode": false,
    "operation": "customers.create"
  },
  "name": "chargefy_api_create"
}
```

If it times out after sending, repeat exactly that call with the same `intent_id`.

### Create a link with an existing price

After confirming the price with `prices.get`, read the details of `payment_links.create` and execute:

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "data": {
      "label": "Essential plan",
      "line_items": [
        {
          "price_id": "price_xC9prXwEQpkJghuD"
        }
      ]
    },
    "intent_id": "b6a2f8d1-77c3-4e19-a5d0-2c4e9f81b3a7",
    "livemode": false,
    "operation": "payment_links.create"
  },
  "name": "chargefy_api_create"
}
```

The response includes the `payment_link` object and its public URL. For an ad-hoc price, an inline product or recurrence, follow the variants in [Create a payment link](/api-reference/payment-links/create).

## Updating without replacing

Updates merge: absent fields stay as they are.

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "id": "cus_9UjeV34PYKN9Cuqb",
    "data": {
      "name": "Updated customer"
    },
    "intent_id": "e57d20c4-9b1a-4f36-8e02-6a3c1d94f7b8",
    "operation": "customers.update"
  },
  "name": "chargefy_api_update"
}
```

<Warning>
  Do not reuse the `intent_id` from the creation. Each logical change gets a
  fresh token; the token only repeats when retrying that same change.
</Warning>

To clear a field, confirm in the `input_schema` whether it accepts `null` or an empty string. Omitting a field does not remove it.

## Planning a larger flow

For a goal spanning several resources, start with the planner:

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "context": "The customer already exists and I want to work in test only.",
    "goal": "Create a monthly product and generate a payment link"
  },
  "name": "chargefy_implementation_planner"
}
```

The planner points at prerequisites, the order of operations and the documentation. Then:

1. confirm the plan;
2. discover and detail each operation;
3. read existing objects;
4. use a different `intent_id` for each create or update;
5. validate the result of each step before moving on.

The planner never executes a change on its own.

## Investigating payments without moving money

MCP can query payment intents, charges, transactions, invoices, subscriptions, refunds and disputes.

A useful prompt:

> In the live environment and read only, retrieve the payment intent `pi_Q3zX5Sqaeiq5n6WT`. Load the related resources identified in the result and build a timeline with statuses, amounts and timestamps. Do not confirm, capture, cancel or refund anything.

Financial lifecycle operations do not exist on the MCP surface, so investigation stays separate from action.

## Paginating

Lists use a cursor:

<Steps>
  <Step title="Make the first read">
    Choose a `limit` between 1 and 100. The default is 10.
  </Step>

  <Step title="Read has_more">
    If it is `true`, copy the `id` of the last object in `data`.
  </Step>

  <Step title="Fetch the next page">
    Repeat the operation, environment and filters with `starting_after`.
  </Step>
</Steps>

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "limit": 25,
    "operation": "customers.list",
    "starting_after": "cus_9UjeV34PYKN9Cuqb"
  },
  "name": "chargefy_api_read"
}
```

Use `ending_before` to go back. Never send both cursors together.

## Retrying

| Situation                     | What to repeat                                              |
| ----------------------------- | ----------------------------------------------------------- |
| `rate_limited`                | Wait `retry_after_ms`; keep the arguments and scope         |
| Timeout on a read             | Repeat the same call                                        |
| Timeout on a write            | Repeat the operation, ID, `data` and same `intent_id`       |
| `invalid_arguments`           | Fix it per `param` and `chargefy_api_details`               |
| Error with `retryable: false` | Do not repeat without changing permission, context or input |

Changing the `intent_id` after a timeout can turn the retry into a second change.

## Fixing common errors

| Code                          | Cause                                        | Next step                                                          |
| ----------------------------- | -------------------------------------------- | ------------------------------------------------------------------ |
| `no_scope`                    | Ambiguous environment or no active scope     | Check the account and pass `livemode`; reconnect if needed         |
| `environment_disabled`        | Environment turned off for the organization  | Ask an administrator to enable it                                  |
| `operation_not_found`         | Nonexistent `operation_id` or the wrong tool | Use `chargefy_api_search`                                          |
| `operation_not_granted`       | Method outside the connection's grant        | Authorize again                                                    |
| `write_not_allowed`           | Read-only scope                              | Use a write scope                                                  |
| `missing_capability`          | User without the resource's capability       | Review the user's role                                             |
| `invalid_arguments`           | Invalid schema, filter, ID or `intent_id`    | Compare with `chargefy_api_details`                                |
| `idempotency_key_reused`      | Same `intent_id` with different parameters   | Recover the original intent or generate a token for the new action |
| `idempotency_key_in_progress` | The same write is still processing           | Wait and repeat with the same `intent_id`                          |
| `rate_limited`                | Bucket exhausted                             | Wait `retry_after_ms`                                              |

Keep the `request_id` whenever it appears. It correlates the failure with Chargefy's request log and can be sent through `send_chargefy_mcp_feedback`.

## Ready-made prompts

<AccordionGroup>
  <Accordion title="Audit without changing">
    "Use Chargefy for reading only. Confirm the test environment, list open
    invoices and summarize amount, due date and status. Do not call
    `chargefy_api_create` or `chargefy_api_update`."
  </Accordion>

  <Accordion title="Create with human review">
    "In test, prepare a customer with the email `name@email.com`. Check the
    schema, show `data` and `intent_id`, and only execute after my
    confirmation."
  </Accordion>

  <Accordion title="Investigate a failure">
    "Retrieve the request `req_j8ii31CD75absd7t` and whichever related objects
    are available. Build a timeline and preserve the `request_id`. Do not change
    any resource."
  </Accordion>

  <Accordion title="Build a catalog and a link">
    "Plan selling a monthly R\$ 99.90 plan in test. After my approval, create the
    product, the price and the link. Use a fresh `intent_id` on each write and
    validate every response."
  </Accordion>
</AccordionGroup>

## Keep going

<CardGroup cols={2}>
  <Card title="Tools and operations" icon="screwdriver-wrench" href="/en/mcp/tools">
    Check arguments, limits and the full operation matrix.
  </Card>

  <Card title="Limits and security" icon="shield-halved" href="/en/mcp/limits">
    Understand rate limits, auditing and actions that require the REST API.
  </Card>
</CardGroup>