Subscriptions
Subscriptions allow you to charge a customer on a recurring basis.
Subscriptions in Yorlet can be created as one of two variations:
- Send invoice: email your customer a link to a hosted invoice where they can pay manually using Card or UK bank transfer.
- Charge automatically: use a saved payment method such as Card or Bacs Direct Debit to automatically charge your customer when the subscription is due.
To create a subscription object you'll need a customer ID that has previously been created. For subscriptions with
collection_method=charge_automatically you will also need a payment method ID that has previously been created. See our guides on creating customers and collecting a payment method.To model the subscription you need to supply information relating to the billing dates and frequency you, and the subscription items you wish to charge for.
The
start_date can be used to activate the subscription at a future date or back date a subscription. When supplying a start_date in the future the subscription's initial status will be scheduled.The
end_date can be used to stop a subscription from creating any more invoices in the future. When a subscription ends due to the end_date passing, the subscription's status will change to complete. If you don't specify an end_date the subscription will bill the customer indefinitely or until it is canceled.The
interval parameter describes the frequency at which the subscription should be billed. It can be one of week, month, year or custom.The
interval_count describes number of intervals (specified in the interval attribute) between subscription billings. For example, interval=month and interval_count=3 bills every 3 months.The
items array describes each line item you'd like the subscription to bill the customer for. An item can have a type of rent or charge. We recommend using type=rent to charge for rent, when using type=rent you must also supply the unit ID the payment is for so Yorlet can provide robust reporting.The
price_data object contains information about the amount to charge. price_data[amount] must be a positive integer in the smallest currency unit (e.g., 100 pence to charge £1.00 GBP). The minimum amount is £1.00 GBP.When the subscription's
interval is set to custom you can provide a phases array which automates changes to a subscription over time.Each phase has a
start_date that determines when the phase will begin, the start_date of one phase can't be before the previous phase. Each phase should also include an items array of each line item to replace the previous phase.For example, a student that you want to charge before their student finance becomes available.
- The first phase will begin on 15/01/2021 and include a rent item for £3,000.
- The second phase will replace the first on the 16/03/2021 and charge £2,500 for rent.
"phases": [
{
"start_date": 1610668800,
"items": [
{
"description": "Rent for Apartment 1",
"price_data": {
"amount": 300000,
"currency": "gbp"
},
"type": "rent",
"unit": "unit_test"
}
]
},
{
"start_date": 1615852800,
"items": [
{
"description": "Rent for Apartment 1",
"price_data": {
"amount": 250000,
"currency": "gbp"
},
"type": "rent",
"unit": "unit_test"
}
]
},
]
}
Once all phases have completed the subscription
status will transition to complete.curl https://api.yorlet.com/v1/subscriptions \
-H "Authorization: Bearer {{API_KEY}}" \
-H "Content-Type: application/json" \
-d '{
"collection_method": "charge_automatically",
"customer": "{{CUSTOMER_ID}}",
"default_payment_method": "{{PAYMENT_METHOD_ID}}",
"interval": "month",
"interval_count": 1,
"items": [
{
"description": "Rent for Apartment 1",
"price_data": {
"amount": 10000,
"currency": "gbp"
},
"type": "rent",
"unit": "{{UNIT_ID}}"
}
]
}'
Last modified 2yr ago