> ## 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 "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 "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 "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.