# `PaperTiger.Resources.Subscription`
[🔗](https://github.com/EnaiaInc/paper_tiger/blob/v1.2.2/lib/paper_tiger/resources/subscription.ex#L1)

Handles Subscription resource endpoints.

## Endpoints

- POST   /v1/subscriptions      - Create subscription
- GET    /v1/subscriptions/:id  - Retrieve subscription
- POST   /v1/subscriptions/:id  - Update subscription
- DELETE /v1/subscriptions/:id  - Cancel subscription
- GET    /v1/subscriptions      - List subscriptions

## Subscription Object

    %{
      id: "sub_...",
      object: "subscription",
      created: 1234567890,
      status: "active",
      customer: "cus_...",
      items: %{
        data: [%{id: "si_...", price: %{id: "price_...", object: "price", ...}, quantity: 1}]
      },
      current_period_start: 1234567890,
      current_period_end: 1237159890,
      # ... other fields
    }

## Subscription Statuses

- active - Subscription is active
- trialing - In trial period
- past_due - Payment failed
- canceled - Canceled
- unpaid - Unpaid and canceled
- incomplete - Incomplete (needs payment)
- incomplete_expired - Incomplete and expired

# `cancel`

```elixir
@spec cancel(Plug.Conn.t(), String.t()) :: Plug.Conn.t()
```

Cancels a subscription immediately.

POST /v1/subscriptions/:id/cancel

Cancels the subscription right away without waiting for the current period to end.

# `create`

```elixir
@spec create(Plug.Conn.t()) :: Plug.Conn.t()
```

Creates a new subscription.

## Required Parameters

- customer - Customer ID
- items - Array of subscription items (each with price and quantity)

## Optional Parameters

- id - Custom ID (must start with "sub_"). Useful for seeding deterministic data.
- default_payment_method - Payment method ID
- trial_period_days - Days of trial period
- metadata - Key-value metadata
- billing_cycle_anchor - Anchor for billing cycle
- cancel_at_period_end - Cancel at end of current period

# `delete`

```elixir
@spec delete(Plug.Conn.t(), String.t()) :: Plug.Conn.t()
```

Cancels a subscription.

Note: DELETE /v1/subscriptions/:id cancels the subscription.
For immediate cancellation, set cancel_at_period_end=false.

# `list`

```elixir
@spec list(Plug.Conn.t()) :: Plug.Conn.t()
```

Lists all subscriptions with pagination.

## Parameters

- limit - Number of items (default: 10, max: 100)
- starting_after - Cursor for pagination
- ending_before - Reverse cursor
- customer - Filter by customer
- status - Filter by status

# `retrieve`

```elixir
@spec retrieve(Plug.Conn.t(), String.t()) :: Plug.Conn.t()
```

Retrieves a subscription by ID.

# `search`

```elixir
@spec search(Plug.Conn.t()) :: Plug.Conn.t()
```

Searches subscriptions with Stripe-style search query syntax.

# `update`

```elixir
@spec update(Plug.Conn.t(), String.t()) :: Plug.Conn.t()
```

Updates a subscription.

## Updatable Fields

- items - Update subscription items
- default_payment_method
- trial_end
- cancel_at_period_end
- metadata
- proration_behavior

---

*Consult [api-reference.md](api-reference.md) for complete listing*