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