Direct Debits: Dates and Amounts

In the case of a sales funnel with products involving a subscription via direct debit, you will want to show your end user the dates on which they will be charged, the initial amount to be paid, and the amount of subsequent installments.

The start date of direct debit

A customer can be debited on different days of the month (only once, but with several options).
The end user can choose the day of the month on which they wish to be debited, among the dates offered by the club (the dates when the club triggers its debits).

To retrieve these dates, you can use the endpoint GET /{client_token}/allowed_debit_days.

This endpoint takes a startDate filter parameter which allows you to retrieve the upcoming debit dates starting from a given date.

bash

curl 'https://{{base_url}}/{{client_token}}/allowed_debit_days?startDate=2024-11-18'   -H 'accept: application/json, text/plain, */*'   -H 'authorization: Bearer ...' ```

This endpoint returns the list of debit days: 

```json
[
    {
        "debitDay": 1,
        "date": "2024-11-18"
    },
    {
        "debitDay": 2,
        "date": "2024-11-19"
    },
    ...
]

Providing the debit date when adding to cart

Offer one of these dates to your customer, and keep it in memory to use it when adding the product to the cart.

When calling POST /{client_token}/articles, specify the desired start date of debits in the repaymentSchedule.

bash

curl 'https://{{base_url}}/{{client_token}}/sales/{{saleId}}/articles'   -H 'accept: application/json, text/plain, */*'   --data-raw '{"parent":null,"offerId":"/{{client_token}}/offers/{{offerId}}","implementation":{"startDate":"2024-11-22"},"repaymentSchedule":{"specificDay":true,"debitDay":null,"startDate":"2024-11-23","debitWeekDay":6}}'

The important information here is:

json

{
    ...
    "offerId":"/{{client_token}}/offers/{{offerId}}",
    "implementation":{
        "startDate":"2024-11-22"
    },
    "repaymentSchedule":{
        "specificDay":true,
        "debitDay":null,
        "startDate":"2024-11-23",
        "debitWeekDay":6
    }
    ...
}

parameter	description	example
`offerId`	The ID of the offer	/demo/offers/12345
`implementation.startDate`	Subscription start date	`2024-11-22`
`repaymentSchedule.specificDay`	Specify a specific debit day	`true` or `false`
`repaymentSchedule.startDate`	Date of the first debit	`2024-11-23`
`repaymentSchedule.debitWeekDay`	Day of the week the user wishes to be debited	`6` (Saturday)

Presenting amounts

Several amounts should be presented to the customer:

The amount to be paid immediately
Registration fees (often included)
The first installment amount (may differ, and may also be included in the immediate payment)
The amount of each subsequent installment

⚠️ CAUTION: It is important to note that a subscription via direct debit may not have an end date (automatic renewal). This makes it difficult to provide a "total" subscription amount.

Where to retrieve this information

You can retrieve all the information you need in the offer details of the product the user wants to buy.

GET /{client_token}/offers?product=/{client_token}/products/12345

parameter	description	example
`registrationFeeTI`	The amount of the registration fees, including taxes	`4900`
`registrationFeeName`	The name given to the registration fees	`Registration fees`
`totalPriceTI`	The initial amount to be paid, including taxes	`8896`
`isFirstMonthPayed`	Whether the first installment is included in the immediate payment	`true` or `false`
`rhythmBilling`	The billing rhythm	`week4` (Every 4 weeks)
`product.productBehaviors[].configuration.validityPeriod`	The subscription validity period	`P52W` (52 weeks)
`articleBehaviors.implementation.isProrated`	Whether the first installment is prorated depending on the subscription start date	`true` or `false`
`repaymentSchedule.occurrences`	Installments for a limited period	See below
`repaymentSchedule.recurrences`	Installments for an unlimited period: This array is empty in the case of a fixed-term contract	See below

Registration fees

The registration fees registrationFeeTI are included in the initial offer amount totalPriceTI. Their separation allows you to present/detail them.

Immediate payment amount

This amount is retrieved from the totalPriceTI property. It automatically includes the first installment amount (if it must be included), you don’t need to add it yourself.

Installment amount

A common way to present it is to display a message such as:
“You will be debited X€ per (week|month) every X (weeks|months).”

To obtain this information, you must retrieve the details from occurrences and recurrences as described below.

How occurrences and recurrences work

Occurrences and recurrences follow the same schema: they indicate the amounts to be billed per period, for a given number of periods.

They allow you to establish a schedule with the due dates and amounts to be debited.

⚠️ CAUTION: They represent billing periods, not debit periods. They must be combined with rhythmBilling (see below).

Example repaymentSchedule:

json

{
  "occurrences": [
    {
      "offset": "P4W", // The duration of this occurrence
      "interval": "P1W", // The repetition interval of this occurrence
      "loop": 0, // If 0: offset/interval loops
      "taxRate": 2000,
      "priceTI": 749, // Amount billed including taxes per occurrence
      "priceTE": 624,
      "tax": 125,
      "priceCurrency": "EUR"
    },
    {
      "offset": "P0W", // If 0: use loop
      "interval": "P1W", // The repetition interval of this occurrence
      "loop": 48, // Number of repetitions
      "taxRate": 2000,
      "priceTI": 999,
      "priceTE": 833,
      "tax": 166,
      "priceCurrency": "EUR"
    }
  ],
  "recurrences": [
    {
      // No loop or offset: This recurrence repeats indefinitely
      "tax": 166,
      "interval": "P1W",
      "priceCurrency": "EUR",
      "taxRate": 2000,
      "priceTI": 1999,
      "priceTE": 833,
      "offset": "P0W"
    }
  ]
}

This schedule would be described as follows:

For 4 weeks (offset P4W and loop 0), bill every 1 week (interval P1W) 7.49€
Then for 48 weeks (offset 0 and loop 48), the subscription costs 9.99€ per week
Indefinitely after the recurrences, the subscription costs 9.99€ per week

For an offer where rhythmBilling is week4, the user would be debited as follows:

7.49€*4 = 29.96€ the first time, after 4 weeks
9.99€*4 = 39.96€ every 4 weeks, for 48 weeks
19.99€*4 = 79.96€ every 4 weeks indefinitely

ℹ️ NOTE: It is rare for the amount to vary between occurrences and recurrences; it is shown here only for example. However, it is common for the first occurrence to differ, typically if it includes additional fees.

⚠️ CAUTION: occurrences and recurrences are arrays that may contain multiple objects as described above. You must add them together.

Billing rhythms `rhythmBilling`

The 3 most common billing rhythms are:

Rhythm	description	Equivalent interval
`week1`	Every week	`P1W`
`week4`	Every 4 weeks	`P4W`
`monthly`	Every month	`P1M`

Direct Debits: Dates and Amounts ​

The start date of direct debit ​

Providing the debit date when adding to cart ​

Presenting amounts ​

Where to retrieve this information ​

Registration fees ​

Immediate payment amount ​

Installment amount ​

How occurrences and recurrences work ​

Billing rhythms rhythmBilling ​