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

# Create a subscription with Checkout Sessions

> Learn how to create a subscription with Checkout Sessions.

export const APIBadge = () => {
  return <div style={{
    display: 'inline-block',
    backgroundColor: 'rgb(var(--primary-light))',
    color: '#ffffff',
    padding: '1px 4px',
    borderRadius: '.375rem',
    borderColor: 'rgb(var(--gray-200))',
    borderWidth: '1px',
    position: 'relative',
    top: '-2px',
    marginLeft: '4px',
    fontSize: '11px',
    fontWeight: 700,
    letterSpacing: '0.05em',
    lineHeight: '11px'
  }}>
      API
    </div>;
};

Checkout Sessions are a way to set up a subscription for your customers. You can create a Checkout Session for a specific amount and currency, and share the Checkout Session URL with your customers. Your customers can then subscribe using their preferred payment method.

## Create a customer

Before creating a Checkout Session, you need to create a customer. You can create a customer using the [Customers API<APIBadge />](https://docs.yorlet.com/api/core/customers/create).

```bash Create a customer theme={"theme":"dracula"}
curl https://api.yorlet.com/v1/customers \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Yorlet-Version: 2025-08-21.preview" \
  -H "Content-Type: application/json" \
  -d '{
        "email": "jane@example.com"
      }'
```

If the request completed successfully, the response contains the customer object.

```json Customer object theme={"theme":"dracula"}
{
  "id": "cus_lrhplff1u4ZhIPSU",
  "object": "customer",
  "email": "jane@example.com"
  // ... other fields on the Customer object
}
```

## Create a Checkout Session

To [create a Checkout Session<APIBadge />](https://docs.yorlet.com/api/checkout/checkout-sessions/create), you need to specify the `currency`, `customer`, `description`, and `subscription_data`.

```bash Create a Checkout Session theme={"theme":"dracula"}
curl https://api.yorlet.com/v1/checkout_sessions \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Yorlet-Version: 2025-08-21.preview" \
  -H "Content-Type: application/json" \
  -d '{
        "currency": "gbp",
        "customer": "{{CUSTOMER_ID}}",
        "description": "Monthly rent subscription",
        "payment_method_types": ["card", "bacs_debit"],
        "subscription_data": {
          "collection_method": "charge_automatically",
          "interval": "month",
          "interval_count": 1,
          "items": [
            {
              "description": "Monthly rent",
              "type": "rent",
              "price_data": {
                "amount": 10000,
                "currency": "gbp",
                "tax_percent": 0
              }
            }
          ],
          "start_date": 1719225600
        }
      }'
```

If the request completed successfully, the Checkout Session object contains the `url` parameter.

```json Checkout Session object theme={"theme":"dracula"}
{
  "id": "cks_lvu4xju9NAB38beQ",
  "object": "checkout_session",
  // ... other fields on the Checkout Session object
  "url": "https://pay.yorlet.com/checkout/cks_lvu4xju9NAB38beQ-eyJhbGciOiJIUzI1NiJ9"
}
```

### Required parameters

| Parameter           | Type   | Description                                                   |
| ------------------- | ------ | ------------------------------------------------------------- |
| `currency`          | string | Three-letter ISO currency code (`gbp`, `eur`, or `usd`)       |
| `customer`          | string | The ID of the customer to use for the Checkout Session        |
| `description`       | string | The description shown to the customer on the Checkout Session |
| `subscription_data` | object | Subscription configuration (see below)                        |

### Subscription data parameters

The `subscription_data` object defines the subscription that will be created when the Checkout Session completes. Only `collection_method` and `interval` are required.

| Parameter                 | Type      | Required | Description                                                                    |
| ------------------------- | --------- | -------- | ------------------------------------------------------------------------------ |
| `collection_method`       | string    | Yes      | `charge_automatically` or `send_invoice`                                       |
| `interval`                | string    | Yes      | Billing frequency: `month`, `week`, or `custom`                                |
| `interval_count`          | integer   | No       | Number of intervals between billing (required when `interval` is not `custom`) |
| `items`                   | array     | No       | Line items for each billing period (required when `interval` is not `custom`)  |
| `phases`                  | array     | No       | Subscription phases (required when `interval` is `custom`)                     |
| `application`             | string    | No       | The identifier of the application to associate with the subscription           |
| `description`             | string    | No       | The description of the subscription                                            |
| `start_date`              | timestamp | No       | When billing begins (Unix timestamp)                                           |
| `end_date`                | timestamp | No       | When billing ends (Unix timestamp)                                             |
| `start_date_config`       | object    | No       | Date object (`day`, `month`, `year`) as alternative to `start_date`            |
| `end_date_config`         | object    | No       | Date object (`day`, `month`, `year`) as alternative to `end_date`              |
| `billing_anchor`          | timestamp | No       | Date to anchor recurring billing (Unix timestamp)                              |
| `billing_anchor_config`   | object    | No       | Anchor config with `day_of_month` (1-31) as alternative to `billing_anchor`    |
| `days_until_due`          | integer   | No       | Days before invoice is due                                                     |
| `days_before_collection`  | integer   | No       | Days before billing date to create invoice (0-7)                               |
| `coupon`                  | string    | No       | Coupon ID to apply to the subscription                                         |
| `add_invoice_items`       | array     | No       | One-time invoice items added to the first invoice                              |
| `custom_fields`           | array     | No       | Custom fields on invoices (max 4, each with `name` and `value`)                |
| `invoice_settings`        | object    | No       | Invoice settings, including invoice-level `custom_fields`                      |
| `use_future_billing_date` | boolean   | No       | Whether to use a future billing date for the first invoice                     |
| `metadata`                | object    | No       | Set of key-value pairs to attach to the subscription                           |

### Subscription item parameters

Each item in `subscription_data.items` requires `price_data` and `type`.

| Parameter              | Type   | Required | Description                                                                |
| ---------------------- | ------ | -------- | -------------------------------------------------------------------------- |
| `type`                 | string | Yes      | `rent`, `charge`, or `product`                                             |
| `price_data`           | object | Yes      | Pricing object with `amount`, `currency`, and `tax_percent` (all required) |
| `description`          | string | No       | Display description for the line item                                      |
| `unit`                 | string | No       | Unit ID associated with the item                                           |
| `price`                | string | No       | Price ID (alternative to `price_data`)                                     |
| `proration_behavior`   | string | No       | `create_prorations` or `none`                                              |
| `schedule`             | array  | No       | Schedule for changing the item amount over time                            |
| `tax_rate`             | string | No       | Tax rate ID                                                                |
| `transfer_behavior`    | string | No       | `automatic`, `owner`, or `none`                                            |
| `transfer_destination` | string | No       | Owner ID for transfer (only when `transfer_behavior` is `owner`)           |
| `metadata`             | object | No       | Key-value pairs for storing additional information                         |

### Supported payment method types

Use `payment_method_types` to control which payment methods are offered to the customer.

| Type                  | Description                |
| --------------------- | -------------------------- |
| `card`                | Credit or debit card       |
| `bacs_debit`          | Bacs Direct Debit (UK)     |
| `sepa_debit`          | SEPA Direct Debit (EU)     |
| `autogiro`            | Autogiro (Sweden)          |
| `bank_transfer`       | Bank transfer              |
| `direct_transfer`     | Direct transfer            |
| `gbp_credit_transfer` | GBP credit transfer        |
| `pay_by_bank`         | Pay by Bank (Open Banking) |
| `card_present`        | In-person card payment     |

### Collect terms of service acceptance

Use `consent_collection` to require the customer to accept terms of service before completing the Checkout Session, and `custom_text.terms_of_service.message` to override the default terms text.

```bash Checkout Session with terms of service theme={"theme":"dracula"}
curl https://api.yorlet.com/v1/checkout_sessions \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Yorlet-Version: 2025-08-21.preview" \
  -H "Content-Type: application/json" \
  -d '{
        "currency": "gbp",
        "customer": "{{CUSTOMER_ID}}",
        "description": "Monthly rent subscription",
        "consent_collection": {
          "terms_of_service": true
        },
        "custom_text": {
          "terms_of_service": {
            "message": "By subscribing, you agree to our terms and conditions."
          }
        },
        "subscription_data": {
          "collection_method": "charge_automatically",
          "interval": "month",
          "interval_count": 1,
          "items": [
            {
              "description": "Monthly rent",
              "type": "rent",
              "price_data": {
                "amount": 10000,
                "currency": "gbp",
                "tax_percent": 0
              }
            }
          ]
        }
      }'
```

### Share the Checkout Session URL

After creating a Checkout Session, you will receive a Checkout Session URL. Share this link with your customers so they can subscribe using their preferred payment method.

<Note>
  By default, Yorlet automatically emails the URL to the customer. Set `send_email` to `false` if you'd rather share the URL through your own application.
</Note>

## Handle the Checkout Session completion

When your customers complete the checkout process, you will receive a webhook event. You can use the [Webhook Endpoints API<APIBadge />](https://docs.yorlet.com/api/core/webhook-endpoints/create) to set up a webhook endpoint and handle the event.