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

# GET /api/v1/services/:serviceId/plans — List Payment Plans

> GET /api/v1/services/:serviceId/plans — returns all payment plans for a service ordered by creation date. Use plan IDs to create checkout sessions.

Use this endpoint to retrieve all payment plans attached to a given service. The response is an array of plan objects ordered by `createdAt` descending, so the most recently created plan appears first. Use the plan IDs returned here when you create checkout sessions or need to audit your pricing configuration.

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

## Path Parameters

<ParamField path="serviceId" type="string" required>
  The unique identifier of the service whose plans you want to list. You can find this ID in the [list services](/api/services/list) or [get service](/api/services/get) response. Passing an ID that does not exist returns a `404`.
</ParamField>

## Response

A successful request returns HTTP `200 OK` with a `plans` array. If the service exists but has no plans, the array is empty.

```json theme={null}
{
  "plans": [
    {
      "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="plans" type="array">
  An array of payment plan objects for the specified service, ordered by `createdAt` descending.

  <Expandable title="plan object fields">
    <ResponseField name="id" type="string">
      The unique identifier for the plan. Pass this to the checkout session endpoint to let subscribers enroll.
    </ResponseField>

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

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

    <ResponseField name="description" type="string">
      The plan description, if one was provided at creation.
    </ResponseField>

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

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

    <ResponseField name="amount" type="string">
      The USDC charge amount stored with six decimal places of precision (e.g. `"49.000000"`).
    </ResponseField>

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

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

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

### Error Responses

| Status          | Message                                     | Condition                                       |
| --------------- | ------------------------------------------- | ----------------------------------------------- |
| `404 Not Found` | `Referenced database record was not found.` | No service exists for the provided `serviceId`. |

## Example

Replace `clz1abc2def3ghi4` with your actual service ID:

```bash theme={null}
curl https://api.retempo.xyz/api/v1/services/clz1abc2def3ghi4/plans
```

**Example response:**

```json theme={null}
{
  "plans": [
    {
      "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"
    }
  ]
}
```

**Example 404 response:**

```json theme={null}
{
  "error": "Referenced database record was not found."
}
```

<Note>
  To add a new plan to a service, use the [Create Plan](/api/plans/create) endpoint. To inspect a service and all its plans in one call, use [Get Service](/api/services/get).
</Note>