Skip to main content

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.

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"
}

​
Required parameters

ParameterTypeDescription
currencystringThree-letter ISO currency code (gbp, eur, or usd)
customerstringThe ID of the customer to use for the Checkout Session
descriptionstringThe description shown to the customer on the Checkout Session
subscription_dataobjectSubscription 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.
ParameterTypeRequiredDescription
collection_methodstringYescharge_automatically or send_invoice
intervalstringYesBilling frequency: month, week, or custom
interval_countintegerNoNumber of intervals between billing (required when interval is not custom)
itemsarrayNoLine items for each billing period (required when interval is not custom)
phasesarrayNoSubscription phases (required when interval is custom)
applicationstringNoThe identifier of the application to associate with the subscription
descriptionstringNoThe description of the subscription
start_datetimestampNoWhen billing begins (Unix timestamp)
end_datetimestampNoWhen billing ends (Unix timestamp)
start_date_configobjectNoDate object (day, month, year) as alternative to start_date
end_date_configobjectNoDate object (day, month, year) as alternative to end_date
billing_anchortimestampNoDate to anchor recurring billing (Unix timestamp)
billing_anchor_configobjectNoAnchor config with day_of_month (1-31) as alternative to billing_anchor
days_until_dueintegerNoDays before invoice is due
days_before_collectionintegerNoDays before billing date to create invoice (0-7)
couponstringNoCoupon ID to apply to the subscription
add_invoice_itemsarrayNoOne-time invoice items added to the first invoice
custom_fieldsarrayNoCustom fields on invoices (max 4, each with name and value)
invoice_settingsobjectNoInvoice settings, including invoice-level custom_fields
use_future_billing_datebooleanNoWhether to use a future billing date for the first invoice
metadataobjectNoSet of key-value pairs to attach to the subscription

​
Subscription item parameters

Each item in subscription_data.items requires price_data and type.
ParameterTypeRequiredDescription
typestringYesrent, charge, or product
price_dataobjectYesPricing object with amount, currency, and tax_percent (all required)
descriptionstringNoDisplay description for the line item
unitstringNoUnit ID associated with the item
pricestringNoPrice ID (alternative to price_data)
proration_behaviorstringNocreate_prorations or none
schedulearrayNoSchedule for changing the item amount over time
tax_ratestringNoTax rate ID
transfer_behaviorstringNoautomatic, owner, or none
transfer_destinationstringNoOwner ID for transfer (only when transfer_behavior is owner)
metadataobjectNoKey-value pairs for storing additional information

​
Supported payment method types

Use payment_method_types to control which payment methods are offered to the customer.
TypeDescription
cardCredit or debit card
bacs_debitBacs Direct Debit (UK)
sepa_debitSEPA Direct Debit (EU)
autogiroAutogiro (Sweden)
bank_transferBank transfer
direct_transferDirect transfer
gbp_credit_transferGBP credit transfer
pay_by_bankPay by Bank (Open Banking)
card_presentIn-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
              }
            }
          ]
        }
      }'

​
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. You can also set send_email to true to automatically email the URL to the customer.

​
Handle the Checkout Session completion

When your customers complete the checkout process, you will receive a webhook event. You can use the Webhooks API to handle the event.