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

Handles Checkout Session resource endpoints.

## Endpoints

- POST   /v1/checkout/sessions            - Create checkout session
- GET    /v1/checkout/sessions/:id        - Retrieve checkout session
- POST   /v1/checkout/sessions/:id        - Update checkout session
- GET    /v1/checkout/sessions/:id/line_items - Retrieve checkout session line items
- GET    /v1/checkout/sessions            - List checkout sessions
- POST   /v1/checkout/sessions/:id/expire - Expire checkout session (Stripe API)

## Test Endpoints

- POST   /_test/checkout/sessions/:id/complete - Complete checkout session (test helper)

Note: Checkout sessions cannot be deleted.
The complete endpoint is a PaperTiger test helper - real Stripe completes sessions
automatically when payment succeeds.

## Checkout Session Object

    %{
      id: "cs_...",
      object: "checkout.session",
      created: 1234567890,
      customer: "cus_...",
      mode: "payment",
      payment_status: "unpaid",
      status: "open",
      success_url: "https://example.com/success",
      cancel_url: "https://example.com/cancel",
      line_items: [],
      metadata: %{},
      # ... other fields
    }

# `browser_complete`

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

Browser-accessible checkout completion endpoint.

GET /checkout/:id/complete

This is called when a user is redirected to the checkout URL. Unlike the
`/_test/checkout/sessions/:id/complete` POST endpoint (for programmatic use),
this handles the browser redirect flow:

1. Completes the checkout session (creates subscription/payment/setup intent)
2. Redirects the browser to the session's success_url

This makes checkout flows work transparently in tests - the application just
redirects to the checkout URL and the user ends up at success_url with the
session completed.

# `complete`

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

Completes a checkout session (test helper).

POST /_test/checkout/sessions/:id/complete

This is a PaperTiger test helper endpoint - real Stripe completes sessions
automatically when payment succeeds. Use this to simulate successful checkout
completion in tests.

Based on the session mode, this will:
- payment: Creates a succeeded PaymentIntent
- subscription: Creates an active Subscription with items
- setup: Creates a succeeded SetupIntent

Fires the checkout.session.completed webhook event.

# `create`

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

Creates a new checkout session.

## Required Parameters

- success_url - URL to redirect to after successful payment
- cancel_url - URL to redirect to if customer cancels payment
- mode - One of "payment", "setup", or "subscription"

## Optional Parameters

- customer - Customer ID
- line_items - Array of line items
- metadata - Key-value metadata
- payment_status - One of "paid", "unpaid", "no_payment_required"
- status - One of "open", "complete", "expired"

# `expire`

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

Expires an open checkout session.

POST /v1/checkout/sessions/:id/expire

A Checkout Session can only be expired when its status is "open".
After expiration, customers cannot complete the session.

# `line_items`

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

Lists a checkout session's line items with Stripe-style cursor pagination.

# `list`

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

Lists all checkout sessions with pagination.

## Parameters

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

# `retrieve`

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

Retrieves a checkout session by ID.

# `update`

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

Updates a checkout session.

Stable Stripe API versions allow metadata, collected_information, and
shipping_options updates. PaperTiger also supports preview-style full-array
line item replacement so tests can model dynamic Checkout updates.

---

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