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

# Checkout & Portal

Create hosted payment pages for checkout and customer self-service.

## Overview

Pre-built, conversion-optimized pages for checkout and customer management. No frontend code required.

## Checkout Sessions

Create a hosted checkout page for one-time payments or subscriptions.

### Create Checkout Session

```bash theme={null}
curl -X POST https://api.atlas.co/functions/v1/checkout-sessions \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "subscription",
    "line_items": [
      { "price": "price_xxx", "quantity": 1 }
    ],
    "success_url": "https://yoursite.com/success?session_id={CHECKOUT_SESSION_ID}",
    "cancel_url": "https://yoursite.com/canceled",
    "subscription_data": {
      "trial_period_days": 14
    }
  }'
```

**Parameters:**

| Parameter                             | Type    | Required | Description                           |
| ------------------------------------- | ------- | -------- | ------------------------------------- |
| `mode`                                | string  | Yes      | payment or subscription               |
| `line_items`                          | array   | Yes      | Array of price objects with quantity  |
| `success_url`                         | string  | Yes      | Redirect URL after successful payment |
| `cancel_url`                          | string  | Yes      | Redirect URL if customer cancels      |
| `customer`                            | string  | No       | Existing customer ID                  |
| `customer_email`                      | string  | No       | Pre-fill customer email               |
| `subscription_data.trial_period_days` | integer | No       | Free trial days                       |

**Response:**

```json theme={null}
{
  "id": "cs_xxx",
  "object": "checkout.session",
  "url": "https://checkout.atlas.co/abc123",
  "mode": "subscription",
  "status": "open",
  "expires_at": 1704931200
}
```

### Redirect to Checkout

```javascript theme={null}
// Create session on your server
const response = await fetch('/api/create-checkout', { method: 'POST' });
const { url } = await response.json();

// Redirect to hosted checkout
window.location.href = url;
```

## Customer Portal Sessions

Let customers manage their subscriptions, payment methods, and invoices.

### Create Portal Session

```bash theme={null}
curl -X POST https://api.atlas.co/functions/v1/portal-sessions \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_xxx",
    "return_url": "https://yoursite.com/account",
    "configuration": {
      "features": {
        "subscription_cancel": { "enabled": true },
        "subscription_pause": { "enabled": true },
        "payment_method_update": { "enabled": true },
        "invoice_history": { "enabled": true }
      }
    }
  }'
```

**Parameters:**

| Parameter                                      | Type   | Required | Description                   |
| ---------------------------------------------- | ------ | -------- | ----------------------------- |
| `customer`                                     | string | Yes      | Customer ID                   |
| `return_url`                                   | string | Yes      | URL to return to after portal |
| `configuration.features.subscription_cancel`   | object | No       | Object with enabled boolean   |
| `configuration.features.subscription_pause`    | object | No       | Object with enabled boolean   |
| `configuration.features.payment_method_update` | object | No       | Object with enabled boolean   |
| `configuration.features.invoice_history`       | object | No       | Object with enabled boolean   |

**Response:**

```json theme={null}
{
  "id": "bps_xxx",
  "object": "billing_portal.session",
  "url": "https://portal.atlas.co/xyz789",
  "customer": "cus_xxx",
  "return_url": "https://yoursite.com/account",
  "expires_at": 1704848400
}
```

### Portal Features

| Feature                     | Description                               |
| --------------------------- | ----------------------------------------- |
| **subscription\_cancel**    | Allow customers to cancel subscriptions   |
| **subscription\_pause**     | Allow customers to pause subscriptions    |
| **payment\_method\_update** | Allow customers to update payment methods |
| **invoice\_history**        | Show invoice history and download PDFs    |

## Full Integration Example

```javascript theme={null}
// Server-side: Create checkout session
app.post('/api/checkout', async (req, res) => {
  const session = await atlas.checkoutSessions.create({
    mode: 'subscription',
    line_items: [{ price: 'price_xxx', quantity: 1 }],
    success_url: 'https://yoursite.com/success?session_id={CHECKOUT_SESSION_ID}',
    cancel_url: 'https://yoursite.com/pricing',
  });

  res.json({ url: session.url });
});

// Server-side: Create portal session
app.post('/api/portal', async (req, res) => {
  const session = await atlas.portalSessions.create({
    customer: req.user.customerId,
    return_url: 'https://yoursite.com/account',
  });

  res.json({ url: session.url });
});
```

```html theme={null}
<!-- Client-side buttons -->
<button onclick="goToCheckout()">Subscribe</button>
<button onclick="goToPortal()">Manage Subscription</button>

<script>
async function goToCheckout() {
  const { url } = await fetch('/api/checkout', { method: 'POST' }).then(r => r.json());
  window.location.href = url;
}

async function goToPortal() {
  const { url } = await fetch('/api/portal', { method: 'POST' }).then(r => r.json());
  window.location.href = url;
}
</script>
```