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

# Set Up Payment Plans for Your Retempo Service

> Create fixed recurring, usage-based, and one-time payment plans in Retempo. Plans define how subscribers are billed for your service.

Payment plans define the pricing and billing cadence for your service. Every checkout session and invoice in Retempo is tied to a specific plan, so the plan you choose determines how often subscribers are charged, in what amount, and through what mechanism. You can attach multiple plans to a single service — for example, a monthly tier, a weekly trial, and a one-time setup fee can all live under the same service.

<Note>
  All amounts are denominated in USDC.
</Note>

## Pricing types

Retempo supports three pricing types that cover the most common billing models for AI agents, API providers, and SaaS products.

<CardGroup cols={3}>
  <Card title="FIXED_RECURRING" icon="rotate">
    Charges the same amount on every billing interval. Use this for subscription tiers where the price doesn't change month-to-month — a flat \$49/month Pro plan, for example.
  </Card>

  <Card title="USAGE_BASED" icon="chart-bar">
    Bills subscribers based on recorded usage events. The amount on the plan acts as a per-unit rate or cap. Retempo aggregates usage events attached to the invoice before settlement.
  </Card>

  <Card title="ONE_TIME" icon="bolt">
    A single charge with no recurring component. The `billingInterval` is automatically set to `NONE`. Use this for setup fees, one-off API credits, or lifetime access purchases.
  </Card>
</CardGroup>

## Billing intervals

The `billingInterval` field controls how frequently a recurring plan renews. For `ONE_TIME` plans, always use `NONE`.

| Interval | Description                                                                    |
| -------- | ------------------------------------------------------------------------------ |
| `MONTH`  | Plan renews every calendar month.                                              |
| `WEEK`   | Plan renews every seven days. Useful for short trials or weekly agent credits. |
| `DAY`    | Plan renews daily. Suitable for high-frequency API billing.                    |
| `NONE`   | No automatic renewal. Used for one-time charges or manual invoice workflows.   |

## Creating a plan

To create a payment plan, send a `POST` request to `/api/v1/services/:serviceId/plans`. You must supply a `name`, a `pricingType`, and an `amount`. The `billingInterval` defaults to `NONE` if omitted, and `currency` defaults to `USDC`.

Below are three examples covering each pricing type.

### Monthly fixed plan

```curl theme={null}
curl --request POST \
  --url https://api.retempo.xyz/api/v1/services/svc_01hx9kz3v8mq2t4yw6npd7e/plans \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Pro Monthly",
    "description": "Full API access, billed monthly.",
    "pricingType": "FIXED_RECURRING",
    "billingInterval": "MONTH",
    "amount": "49.000000",
    "currency": "USDC"
  }'
```

```json theme={null}
{
  "plan": {
    "id": "plan_01hx9m1bp4nq3s8zt7vce6r",
    "serviceId": "svc_01hx9kz3v8mq2t4yw6npd7e",
    "name": "Pro Monthly",
    "description": "Full API access, billed monthly.",
    "pricingType": "FIXED_RECURRING",
    "billingInterval": "MONTH",
    "amount": "49.000000",
    "currency": "USDC",
    "createdAt": "2025-01-14T10:45:00.000Z"
  }
}
```

### Weekly usage-based plan

```curl theme={null}
curl --request POST \
  --url https://api.retempo.xyz/api/v1/services/svc_01hx9kz3v8mq2t4yw6npd7e/plans \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Metered Weekly",
    "description": "Pay per API call, settled every week.",
    "pricingType": "USAGE_BASED",
    "billingInterval": "WEEK",
    "amount": "0.002000",
    "currency": "USDC"
  }'
```

```json theme={null}
{
  "plan": {
    "id": "plan_01hx9m4cq7pr5u2aw8ynf3t",
    "serviceId": "svc_01hx9kz3v8mq2t4yw6npd7e",
    "name": "Metered Weekly",
    "description": "Pay per API call, settled every week.",
    "pricingType": "USAGE_BASED",
    "billingInterval": "WEEK",
    "amount": "0.002000",
    "currency": "USDC",
    "createdAt": "2025-01-14T11:00:00.000Z"
  }
}
```

### One-time setup fee

```curl theme={null}
curl --request POST \
  --url https://api.retempo.xyz/api/v1/services/svc_01hx9kz3v8mq2t4yw6npd7e/plans \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Onboarding Fee",
    "description": "One-time account activation charge.",
    "pricingType": "ONE_TIME",
    "billingInterval": "NONE",
    "amount": "99.000000",
    "currency": "USDC"
  }'
```

```json theme={null}
{
  "plan": {
    "id": "plan_01hx9m6dz2ks9r1bx5vtg8m",
    "serviceId": "svc_01hx9kz3v8mq2t4yw6npd7e",
    "name": "Onboarding Fee",
    "description": "One-time account activation charge.",
    "pricingType": "ONE_TIME",
    "billingInterval": "NONE",
    "amount": "99.000000",
    "currency": "USDC",
    "createdAt": "2025-01-14T11:05:00.000Z"
  }
}
```

## Listing plans

To see all payment plans attached to a service, send a `GET` request to the plans endpoint for that service:

```curl theme={null}
curl --request GET \
  --url https://api.retempo.xyz/api/v1/services/svc_01hx9kz3v8mq2t4yw6npd7e/plans \
  --header 'Content-Type: application/json'
```

```json theme={null}
{
  "plans": [
    {
      "id": "plan_01hx9m1bp4nq3s8zt7vce6r",
      "serviceId": "svc_01hx9kz3v8mq2t4yw6npd7e",
      "name": "Pro Monthly",
      "pricingType": "FIXED_RECURRING",
      "billingInterval": "MONTH",
      "amount": "49.000000",
      "currency": "USDC",
      "createdAt": "2025-01-14T10:45:00.000Z"
    },
    {
      "id": "plan_01hx9m4cq7pr5u2aw8ynf3t",
      "serviceId": "svc_01hx9kz3v8mq2t4yw6npd7e",
      "name": "Metered Weekly",
      "pricingType": "USAGE_BASED",
      "billingInterval": "WEEK",
      "amount": "0.002000",
      "currency": "USDC",
      "createdAt": "2025-01-14T11:00:00.000Z"
    },
    {
      "id": "plan_01hx9m6dz2ks9r1bx5vtg8m",
      "serviceId": "svc_01hx9kz3v8mq2t4yw6npd7e",
      "name": "Onboarding Fee",
      "pricingType": "ONE_TIME",
      "billingInterval": "NONE",
      "amount": "99.000000",
      "currency": "USDC",
      "createdAt": "2025-01-14T11:05:00.000Z"
    }
  ]
}
```