> ## 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.

# POST /api/v1/services/:serviceId/plans — Add a Plan

> POST /api/v1/services/:serviceId/plans — creates a payment plan for a service. Set pricing type, billing interval, and amount in USDC.

Use this endpoint to create a payment plan and attach it to a service. A plan defines how your service charges subscribers — whether that is a fixed recurring fee, a usage-based charge, or a one-time payment — along with the amount in USDC and the billing cadence. Once created, a plan can be referenced in checkout sessions to start collecting payments.

```
POST https://api.retempo.xyz/api/v1/services/:serviceId/plans
```

## Path Parameters

<ParamField path="serviceId" type="string" required>
  The unique identifier of the service you want to attach this plan to. The service must exist; passing an invalid ID returns a `404`.
</ParamField>

## Request Body

<ParamField body="name" type="string" required>
  The display name for the plan. This name appears on invoices and in the checkout flow presented to the payer.
</ParamField>

<ParamField body="pricingType" type="string" required>
  The pricing model for the plan. Accepted values are:

  * `FIXED_RECURRING` — charges the subscriber the same `amount` on every billing cycle (e.g. monthly SaaS).
  * `USAGE_BASED` — charges based on reported usage events. The `amount` field represents the per-unit price.
  * `ONE_TIME` — charges the subscriber once at checkout with no renewal.
</ParamField>

<ParamField body="amount" type="string | number" required>
  The charge amount in USDC. You can pass this as a decimal string (e.g. `"49.00"`) or a number (e.g. `49`). The value is stored with six decimal places of precision (e.g. `"49.000000"`). Must be a non-negative value.
</ParamField>

<ParamField body="description" type="string">
  A human-readable description of what the plan includes. This appears in checkout sessions and on invoices.
</ParamField>

<ParamField body="billingInterval" type="string" default="NONE">
  How often the subscriber is billed. Accepted values are `MONTH`, `WEEK`, `DAY`, and `NONE`. Defaults to `NONE` if omitted.

  * `MONTH` — billed once per calendar month.
  * `WEEK` — billed once per week.
  * `DAY` — billed daily.
  * `NONE` — no automatic recurring billing (use with `ONE_TIME` or `USAGE_BASED` plans).
</ParamField>

<ParamField body="currency" type="string" default="USDC">
  The settlement currency for the plan. Defaults to `USDC` if omitted. Currently only `USDC` is supported.
</ParamField>

<Note>
  For `FIXED_RECURRING` plans, set `billingInterval` to `MONTH`, `WEEK`, or `DAY` to enable automatic recurring settlement. Leaving it as `NONE` on a recurring plan will prevent automatic renewals.
</Note>

## Response

A successful request returns HTTP `201 Created` with the new plan object.

```json theme={null}
{
  "plan": {
    "id": "clz1plan567",
    "serviceId": "clz1abc2def3ghi4",
    "name": "Pro Monthly",
    "description": "Full access, billed monthly",
    "pricingType": "FIXED_RECURRING",
    "billingInterval": "MONTH",
    "amount": "49.000000",
    "currency": "USDC",
    "createdAt": "2025-06-01T10:05:00.000Z",
    "updatedAt": "2025-06-01T10:05:00.000Z"
  }
}
```

<ResponseField name="plan" type="object">
  The newly created payment plan object.

  <Expandable title="plan fields">
    <ResponseField name="plan.id" type="string">
      The unique identifier for the plan. Use this when creating checkout sessions.
    </ResponseField>

    <ResponseField name="plan.serviceId" type="string">
      The ID of the service this plan is attached to.
    </ResponseField>

    <ResponseField name="plan.name" type="string">
      The display name of the plan.
    </ResponseField>

    <ResponseField name="plan.description" type="string">
      The description provided in the request, if any.
    </ResponseField>

    <ResponseField name="plan.pricingType" type="string">
      The pricing model: `FIXED_RECURRING`, `USAGE_BASED`, or `ONE_TIME`.
    </ResponseField>

    <ResponseField name="plan.billingInterval" type="string">
      The billing cadence: `MONTH`, `WEEK`, `DAY`, or `NONE`.
    </ResponseField>

    <ResponseField name="plan.amount" type="string">
      The USDC charge amount stored with six decimal places of precision.
    </ResponseField>

    <ResponseField name="plan.currency" type="string">
      The settlement currency. Currently always `USDC`.
    </ResponseField>

    <ResponseField name="plan.createdAt" type="string">
      ISO 8601 timestamp recording when the plan was created.
    </ResponseField>

    <ResponseField name="plan.updatedAt" type="string">
      ISO 8601 timestamp recording when the plan was last modified.
    </ResponseField>
  </Expandable>
</ResponseField>

### Error Responses

| Status            | Message                                                               | Condition                                        |
| ----------------- | --------------------------------------------------------------------- | ------------------------------------------------ |
| `400 Bad Request` | `name is required.`                                                   | `name` was omitted.                              |
| `400 Bad Request` | `amount is required.`                                                 | `amount` was omitted.                            |
| `400 Bad Request` | `pricingType must be one of: FIXED_RECURRING, USAGE_BASED, ONE_TIME.` | An invalid `pricingType` value was provided.     |
| `400 Bad Request` | `billingInterval must be one of: MONTH, WEEK, DAY, NONE.`             | An invalid `billingInterval` value was provided. |
| `404 Not Found`   | `Referenced database record was not found.`                           | No service exists for the provided `serviceId`.  |

## Examples

**Create a fixed recurring monthly plan:**

```bash theme={null}
curl -X POST https://api.retempo.xyz/api/v1/services/clz1abc2def3ghi4/plans \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Monthly",
    "description": "Full access, billed monthly",
    "pricingType": "FIXED_RECURRING",
    "billingInterval": "MONTH",
    "amount": "49.00"
  }'
```

**Create a usage-based plan with a per-unit price:**

```bash theme={null}
curl -X POST https://api.retempo.xyz/api/v1/services/clz1abc2def3ghi4/plans \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pay-Per-Call",
    "description": "Charged per API call",
    "pricingType": "USAGE_BASED",
    "amount": "0.001"
  }'
```

<Tip>
  For usage-based plans, pair the plan with the `/api/v1/usage-events` endpoint to report consumption and drive accurate invoice generation at the end of each billing period.
</Tip>