---
title: "List subscriptions"
method: GET
path: "/gateway/subscriptions"
tags: ["Subscriptions"]
---

# List subscriptions

`GET /gateway/subscriptions`

## Request

- Base URL: `https://api.agentaos.ai/api/v1`
- URL: `https://api.agentaos.ai/api/v1/gateway/subscriptions`
- Auth: API key in header `x-api-key`

Paginated. A subscription is created automatically when a buyer pays a payment link with `type: "subscription"` at checkout: there is no `POST` create endpoint by design. Every field on this resource is camelCase on the wire.

## Query parameters

- `limit` integer
- `offset` integer

## Response `200`

A page of subscriptions.

- SubscriptionListResponse
  - `items` Subscription[], required
    - `id` string, uuid, required: Use this as the :id path parameter to cancel.
    - `customerEmail` string, nullable, required
    - `customerName` string, nullable, required
    - `planName` string, nullable, required: The payment link's name, falling back to its description.
    - `billingInterval` 'month' | 'year' | 'null', nullable, required
    - `status` 'incomplete' | 'incomplete_expired' | 'trialing' | 'active' | 'past_due' | 'canceled' | 'unpaid' | 'paused', required: Mirrored directly from the card processor.
    - `unitAmountMinor` integer, required: Per-cycle price, integer minor units (1999 = EUR 19.99).
    - `currency` string, required
    - `currentPeriodEnd` string, date-time, nullable, required: null before the first cycle books.
    - `stripeSubscriptionId` string, nullable, required
    - `pendingPlanChange` object, nullable, required: Null unless a downgrade is scheduled; then the plan, quoted amount and date the subscription switches to. `planName`, `unitAmountMinor` and `linkId` stay what the buyer paid for until `effectiveAt`.
      - `linkId` string, uuid, required
      - `planName` string, nullable, required
      - `unitAmountMinor` integer, required: Per-cycle amount from `effectiveAt` on, integer minor units.
      - `effectiveAt` string, date-time, required
  - `total` integer, required
  - `hasMore` boolean, required

## Other responses

- `401`: Missing or invalid `x-api-key`.

---

[API](https://skmtc.dev/agentaos/apis/agentaos-gateway-api.md) · [All operations](https://skmtc.dev/agentaos/apis/agentaos-gateway-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentaos/apis/agentaos-gateway-api/revisions/3a8ad3c6b965?raw)