Create a subscription with Checkout Sessions

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.

Create a customer

curl https://api.yorlet.com/v1/customers \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
        "email": "[email protected]"
      }'

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

Customer object

{
  "id": "cus_lrhplff1u4ZhIPSU",
  "object": "customer",
  "email": "[email protected]"
  // ... other fields on the Customer object
}

Create a Checkout Session

To create a Checkout Session, you need to specify the currency, customer, description, and subscription_data.

Create a Checkout Session

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.

Checkout Session object

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

Checkout Session with terms of service

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
              }
            }
          ]
        }
      }'

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.

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.

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 to set up a webhook endpoint and handle the event.

Developer tools

Essentials

Integrations

Platforms

Create a subscription with Checkout Sessions

Create a customer

Create a Checkout Session

Required parameters

Subscription data parameters

Subscription item parameters

Supported payment method types

Collect terms of service acceptance

Handle the Checkout Session completion

​Create a customer

​Create a Checkout Session

​Required parameters

​Subscription data parameters

​Subscription item parameters

​Supported payment method types

​Collect terms of service acceptance

​Share the Checkout Session URL

​Handle the Checkout Session completion

Create a customer

Create a Checkout Session

Required parameters

Subscription data parameters

Subscription item parameters

Supported payment method types

Collect terms of service acceptance

Share the Checkout Session URL

Handle the Checkout Session completion