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

# Billing control

> Set whether an instance is on trial or billable

**`PATCH /api/instance/billing/:instance`**

Sets the billing mode of an instance. Use it to skip the trial and bill right away. The switch is one-way: once billable, an instance does not go back to trial. Authenticate with your account **TokenAccount**, the same one you use to create and manage instances.

## Billing modes

| `billingMode` | What it does                                                                                                           |
| ------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `trial`       | Default mode of a new instance. The instance gets your contract's trial days starting from the first connection.       |
| `billable`    | Bills the instance right away, with no free days. Useful for a customer who already trialed before and is coming back. |

<Warning>
  Switching to `billable` is final. A billable instance cannot go back to `trial`, the API returns 400.
</Warning>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://ryzeapi.cloud/api/instance/billing/my-instance" \
    -H "token: $Token_Account" \
    -H "Content-Type: application/json" \
    -d '{"billingMode": "billable"}'
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/instance/billing/my-instance", {
    method: "PATCH",
    headers: {
      "token": process.env.Token_Account,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ billingMode: "billable" })
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.patch(
      "https://ryzeapi.cloud/api/instance/billing/my-instance",
      headers={
          "token": os.environ["Token_Account"],
          "Content-Type": "application/json"
      },
      json={"billingMode": "billable"}
  )
  ```
</CodeGroup>

## Success response

```json 200 OK theme={null}
{
  "billingMode": "billable"
}
```

The response confirms the mode now in effect on the instance.

## Path parameters

<ParamField path="instance" type="string" required>
  Instance name.
</ParamField>

## Headers

<ParamField header="token" type="string" required>
  Your TokenAccount, the same one you use to create and manage instances.
</ParamField>

## Body

<ParamField body="billingMode" type="string" required>
  One of `trial` or `billable`. Once `billable`, the instance cannot go back to `trial`.
</ParamField>

## What happens on each change

<AccordionGroup>
  <Accordion title="To billable" icon="circle-dollar-to-slot">
    The instance starts being billed from now on. If it is already connected, the committed amount for the cycle starts counting at this moment and runs until renewal, even if you delete the instance before that.
  </Accordion>

  <Accordion title="To trial" icon="hourglass-start">
    Only valid while the instance has not become billable yet. An instance that is already `billable` does not go back to trial, the API returns 400. The trial itself follows your contract rules and the number's history.
  </Accordion>
</AccordionGroup>

## Errors

| HTTP | `error`                                         | When                                                          |
| :--: | ----------------------------------------------- | ------------------------------------------------------------- |
|  400 | `billingMode obrigatorio`                       | The body did not include the `billingMode` field.             |
|  400 | `billingMode invalido (trial\|billable)`        | Value outside the two accepted ones.                          |
|  400 | `instancia billable nao pode voltar para trial` | The instance is already billable and cannot go back to trial. |
|  401 | `Invalid token`                                 | Missing or invalid token.                                     |
|  403 | `Instance does not belong to your account`      | The instance is not yours.                                    |
|  404 | `instance not found`                            | Name does not exist.                                          |

## Next

<CardGroup cols={2}>
  <Card title="How billing works" icon="calculator" href="/en/enterprise/how-billing-works">
    Understand the credit, the trial and per-day metering.
  </Card>

  <Card title="Enterprise webhooks" icon="webhook" href="/en/enterprise/webhooks">
    React to each state change via events.
  </Card>
</CardGroup>