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

# Subscription

> The Subscription object represents a recurring billing relationship with a customer.

A Subscription object represents an ongoing billing relationship where a customer is charged on a recurring basis. Subscriptions are created when a customer purchases a subscription [Product](/core-resources/product) and manage the lifecycle of recurring [Payments](/core-resources/payment).

Subscriptions track billing intervals, status changes, and link to all associated [Payments](/core-resources/payment) and [Orders](/core-resources/order). You can use the API to manage subscriptions including updating, pausing, and cancelling them.

## Endpoints

| Method  | Endpoint                                                      | Description                       |
| ------- | ------------------------------------------------------------- | --------------------------------- |
| `GET`   | `/v0/subscriptions/list`                                      | List and filter subscriptions     |
| `POST`  | `/v0/subscriptions/create`                                    | Create a new subscription         |
| `GET`   | `/v0/subscriptions/{subscriptionIdOrNumber}`                  | Retrieve a subscription           |
| `PATCH` | `/v0/subscriptions/{subscriptionIdOrNumber}/update`           | Update a subscription             |
| `POST`  | `/v0/subscriptions/{subscriptionIdOrNumber}/charge`           | Charge a subscription immediately |
| `PATCH` | `/v0/subscriptions/{subscriptionIdOrNumber}/cancel`           | Cancel a subscription             |
| `PATCH` | `/v0/subscriptions/{subscriptionIdOrNumber}/pause-collection` | Pause subscription billing        |

## The Subscription object

<ResponseField name="object" type="string">
  Object type identifier. Always `"subscription"` for Subscription objects.
</ResponseField>

<ResponseField name="id" type="string" required>
  Subscription identifier, based on the initial order number.
</ResponseField>

<ResponseField name="status" type="string" required>
  Current subscription status. Possible values: `active`, `past_due`, `canceled`, `unpaid`, `incomplete`, `incomplete_expired`, `trialing`, `paused`
</ResponseField>

<ResponseField name="createdAt" type="integer | null">
  Unix timestamp (milliseconds) when the subscription was created.
</ResponseField>

<ResponseField name="currentIntervalStart" type="integer | null">
  Unix timestamp (milliseconds) when the current billing interval started.
</ResponseField>

<ResponseField name="currentIntervalEnd" type="integer | null">
  Unix timestamp (milliseconds) when the current billing interval ends.
</ResponseField>

<ResponseField name="cancelAtIntervalEnd" type="boolean">
  Whether the subscription will cancel at the end of the current interval. Defaults to `false`.
</ResponseField>

<ResponseField name="canceledAt" type="integer | null">
  Unix timestamp (milliseconds) when the subscription was cancelled, if applicable.
</ResponseField>

<ResponseField name="userId" type="string | null">
  UUID of the subscribed [User](/core-resources/user).
</ResponseField>

<ResponseField name="user" type="User | null">
  Expanded [User object](/core-resources/user) with basic subscriber information.

  <Expandable title="user properties">
    <ResponseField name="object" type="string">
      Always `"user"`.
    </ResponseField>

    <ResponseField name="id" type="string" required>
      Unique identifier (UUID) for this user.
    </ResponseField>

    <ResponseField name="username" type="string | null">
      Username of the user.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="orderId" type="string" required>
  UUID of the initial [Order](/core-resources/order) that created this subscription.
</ResponseField>

<ResponseField name="orderNumber" type="string" required>
  Human-readable number of the initial order.
</ResponseField>

<ResponseField name="order" type="Order" required>
  Expanded [Order object](/core-resources/order) for the initial subscription order.

  <Expandable title="order properties">
    <ResponseField name="object" type="string">
      Always `"order"`.
    </ResponseField>

    <ResponseField name="id" type="string" required>
      Unique identifier (UUID) for this order.
    </ResponseField>

    <ResponseField name="number" type="string" required>
      Human-readable order number.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Current order status.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="lastPaymentId" type="string | null">
  UUID of the most recent [Payment](/core-resources/payment) for this subscription.
</ResponseField>

<ResponseField name="lastPaymentNumber" type="string | null">
  Human-readable number of the most recent payment.
</ResponseField>

<ResponseField name="lastPayment" type="Payment | null">
  Expanded [Payment object](/core-resources/payment) for the most recent charge.

  <Expandable title="lastPayment properties">
    <ResponseField name="object" type="string">
      Always `"payment"`.
    </ResponseField>

    <ResponseField name="id" type="string" required>
      Unique identifier (UUID) for this payment.
    </ResponseField>

    <ResponseField name="type" type="string" required>
      Payment type: `subscription_initial`, `subscription_interval`, `subscription_update`, `subscription_extra`
    </ResponseField>

    <ResponseField name="number" type="string" required>
      Human-readable payment number.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Current payment status.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Subscription lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> incomplete: Initial payment pending
    incomplete --> active: Payment successful
    incomplete --> incomplete_expired: Payment expired
    
    active --> past_due: Payment failed
    active --> canceled: User cancels
    active --> paused: Pause requested
    
    past_due --> active: Retry successful
    past_due --> unpaid: All retries failed
    past_due --> canceled: User cancels
    
    paused --> active: Resume
    paused --> canceled: User cancels
    
    unpaid --> canceled: Auto-cancel
    incomplete_expired --> [*]
    canceled --> [*]
```

***

## Example response

```json theme={null}
{
  "status": "success",
  "data": {
    "subscription": {
      "object": "subscription",
      "id": "#SUB123DEF456",
      "status": "active",
      "createdAt": 1705590000000,
      "currentIntervalStart": 1708268400000,
      "currentIntervalEnd": 1710946800000,
      "cancelAtIntervalEnd": false,
      "canceledAt": null,
      "userId": "123e4567-e89b-12d3-a456-426614174000",
      "user": {
        "object": "user",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "username": "johndoe"
      },
      "orderId": "550e8400-e29b-41d4-a716-446655440000",
      "orderNumber": "#ABC123DEF456",
      "order": {
        "object": "order",
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "number": "#ABC123DEF456",
        "status": "PAID"
      },
      "lastPaymentId": "660e8400-e29b-41d4-a716-446655440001",
      "lastPaymentNumber": "#PAY789GHI012",
      "lastPayment": {
        "object": "payment",
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "type": "subscription_interval",
        "number": "#PAY789GHI012",
        "status": "PAID"
      }
    }
  }
}
```

***

## Webhook events

| Event                    | Typical use                                                |
| ------------------------ | ---------------------------------------------------------- |
| `subscription_created`   | Subscription exists; first payment may still be processing |
| `payment_success`        | First or recurring charge succeeded — **fulfill here**     |
| `subscription_interval`  | New billing period charged (renewal)                       |
| `subscription_updated`   | Plan change, cancel-at-period-end, trial ended, etc.       |
| `subscription_cancelled` | Subscription ended                                         |

See [Event types](/core-resources/event#subscription-signup-events) and [Webhooks overview](/developers/webhooks/overview#subscription-checkouts-and-fulfillment) for why `subscription_created` can include `PENDING` payments and why you should not rely on it alone for access grants.

***

## Related resources

<CardGroup cols={2}>
  <Card title="Payments" icon="credit-card" href="/core-resources/payment">
    Payment transactions for subscriptions
  </Card>

  <Card title="Orders" icon="receipt" href="/core-resources/order">
    Initial orders creating subscriptions
  </Card>

  <Card title="Users" icon="user" href="/core-resources/user">
    Subscribed customers
  </Card>

  <Card title="Events" icon="bell" href="/core-resources/event">
    Subscription webhook events
  </Card>
</CardGroup>