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

# Subscription Object

> The Subscription object represents a recurring payment schedule for a product or service

# Subscription Object

Subscriptions enable recurring payments for memberships, services, or product deliveries. They automatically charge customers at specified intervals using their stored HSA/FSA or regular payment method.

## The Subscription Object

```json theme={null}
{
  "id": "sub_abc123xyz",
  "customer_id": "cus_xyz789",
  "status": "active",
  "product_id": 12345,
  "merchant_product_id": "MEMBERSHIP-PREMIUM",
  "amount_cents": 9900,
  "currency": "USD",
  "interval": "monthly",
  "interval_count": 1,
  "trial_period_days": 7,
  "trial_end": "2025-10-25T14:30:00Z",
  "current_period_start": "2025-10-18T14:30:00Z",
  "current_period_end": "2025-11-18T14:30:00Z",
  "next_billing_date": "2025-11-18T14:30:00Z",
  "cancel_at_period_end": false,
  "cancelled_at": null,
  "ended_at": null,
  "payment_method": {
    "type": "hsa_fsa_card",
    "last4": "1111",
    "brand": "visa"
  },
  "metadata": {
    "tier": "premium",
    "features": "unlimited_access,priority_support"
  },
  "created_at": "2025-10-18T14:30:00Z",
  "updated_at": "2025-10-18T14:30:00Z"
}
```

## Attributes

| Attribute              | Type      | Description                                              |
| ---------------------- | --------- | -------------------------------------------------------- |
| `id`                   | string    | Unique subscription identifier                           |
| `customer_id`          | string    | Customer ID                                              |
| `status`               | enum      | Subscription status (see below)                          |
| `product_id`           | integer   | Associated product ID                                    |
| `merchant_product_id`  | string    | Your product reference ID                                |
| `amount_cents`         | integer   | Recurring charge amount in cents                         |
| `currency`             | string    | ISO 4217 currency code                                   |
| `interval`             | enum      | Billing interval: `daily`, `weekly`, `monthly`, `yearly` |
| `interval_count`       | integer   | Number of intervals between billings                     |
| `trial_period_days`    | integer   | Free trial duration in days                              |
| `trial_end`            | timestamp | When trial ends (null if no trial)                       |
| `current_period_start` | timestamp | Start of current billing period                          |
| `current_period_end`   | timestamp | End of current billing period                            |
| `next_billing_date`    | timestamp | Next scheduled charge date                               |
| `cancel_at_period_end` | boolean   | Whether subscription cancels at period end               |
| `cancelled_at`         | timestamp | When subscription was cancelled (null if active)         |
| `ended_at`             | timestamp | When subscription ended (null if active)                 |
| `payment_method`       | object    | Stored payment method details                            |
| `metadata`             | object    | Custom key-value pairs                                   |
| `created_at`           | timestamp | When subscription was created                            |
| `updated_at`           | timestamp | When subscription was last updated                       |

## Subscription Status

| Status      | Description                       |
| ----------- | --------------------------------- |
| `trialing`  | In free trial period              |
| `active`    | Active and billing normally       |
| `past_due`  | Payment failed, retrying          |
| `cancelled` | Cancelled, will end at period end |
| `ended`     | Subscription has ended            |
| `paused`    | Temporarily paused                |

## Billing Intervals

| Interval  | `interval_count` | Billing Frequency          |
| --------- | ---------------- | -------------------------- |
| `daily`   | 1                | Every day                  |
| `daily`   | 7                | Every 7 days               |
| `weekly`  | 1                | Every week                 |
| `weekly`  | 2                | Every 2 weeks (bi-weekly)  |
| `monthly` | 1                | Every month                |
| `monthly` | 3                | Every 3 months (quarterly) |
| `yearly`  | 1                | Every year                 |

## Subscription Lifecycle

A subscription moves through these states:

* **trialing** - Subscription created with trial period
* **active** - Subscription is active and billing normally (can come from trialing or be created without trial)
* **past\_due** - Payment failed, retrying (can come from trialing or active)
* **cancelled** - Cancel requested, will end at period end
* **ended** - Subscription has ended (can come from cancelled, past\_due after max retries, or active for immediate cancellation)

## Trial Periods

Subscriptions can include a free trial period:

```json theme={null}
{
  "trial_period_days": 7,
  "trial_end": "2025-10-25T14:30:00Z",
  "status": "trialing",
  "next_billing_date": "2025-10-25T14:30:00Z"
}
```

During trial:

* Customer is not charged
* Payment method is verified
* First charge occurs when trial ends

## Payment Method

```json theme={null}
{
  "payment_method": {
    "type": "hsa_fsa_card",
    "last4": "1111",
    "brand": "visa",
    "exp_month": 12,
    "exp_year": 2026
  }
}
```

| Type           | Description         |
| -------------- | ------------------- |
| `hsa_fsa_card` | HSA/FSA debit card  |
| `credit_card`  | Regular credit card |
| `debit_card`   | Regular debit card  |

## Cancellation Behavior

### Cancel at Period End

```json theme={null}
{
  "status": "cancelled",
  "cancel_at_period_end": true,
  "current_period_end": "2025-11-18T14:30:00Z",
  "cancelled_at": "2025-10-20T10:00:00Z",
  "ended_at": null
}
```

Customer retains access until period end.

### Immediate Cancellation

```json theme={null}
{
  "status": "ended",
  "cancel_at_period_end": false,
  "cancelled_at": "2025-10-20T10:00:00Z",
  "ended_at": "2025-10-20T10:00:00Z"
}
```

Access ends immediately.

## Past Due Handling

When a payment fails:

1. Status changes to `past_due`
2. Automatic retry attempts (days 3, 7, 14)
3. Customer receives notification
4. After max retries, subscription ends

```json theme={null}
{
  "status": "past_due",
  "next_billing_date": "2025-10-21T14:30:00Z",
  "retry_count": 2,
  "max_retries": 3
}
```

## Examples

### Monthly Membership

```json theme={null}
{
  "id": "sub_membership_001",
  "amount_cents": 9900,
  "interval": "monthly",
  "interval_count": 1,
  "status": "active",
  "trial_period_days": 14
}
```

### Quarterly Subscription

```json theme={null}
{
  "id": "sub_quarterly_001",
  "amount_cents": 24900,
  "interval": "monthly",
  "interval_count": 3,
  "status": "active"
}
```

### Annual Plan with Trial

```json theme={null}
{
  "id": "sub_annual_001",
  "amount_cents": 99900,
  "interval": "yearly",
  "interval_count": 1,
  "status": "trialing",
  "trial_period_days": 30,
  "trial_end": "2025-11-18T14:30:00Z"
}
```

## Related Endpoints

* [Create Subscription](/api-reference/endpoint/create-subscription) - POST /api/v2/subscriptions
* [Get Subscription](/api-reference/endpoint/get-subscription) - GET /api/v2/subscriptions/{id}
* [List Subscriptions](/api-reference/endpoint/list-subscriptions) - GET /api/v2/subscriptions
* [Cancel Subscription](/api-reference/endpoint/cancel-subscription) - POST /api/v2/subscriptions/{id}/cancel
* [Update Subscription](/api-reference/endpoint/update-subscription) - PUT /api/v2/subscriptions/{id}