Start from the API
Create a Direct Debit subscription through the API against a mandate the customer has already set up
The first period is billed when you create the subscription, at the price's amount for the quantity. By Direct Debit, the first collection is scheduled with advance notice, typically 5 to 7 working days after you create it. On card, the saved card (paymentMethodId, required unless the subscription starts in a trial) is charged straight away. With a trial, nothing is collected until the trial ends.
POST /v2/subscriptions can create a subscription that collects by Direct Debit against a mandate the customer already has.
Request
{
"customerId": "…",
"priceId": "…",
"paymentRail": "direct_debit",
"mandateId": "…"
}The response includes payment_rail, mandate_id and payment_method_id, so you can read back how the subscription collects.
What is checked
| Check | Answer when it fails |
|---|---|
mandateId sent without paymentRail: direct_debit | 400 mandate_requires_direct_debit |
paymentRail: direct_debit without a mandateId | 400 mandate_required |
A paymentMethodId on a Direct Debit subscription | 400 payment_method_not_allowed_on_direct_debit |
| Direct Debit is not enabled for your account | 403 direct_debit_not_enabled |
| The price is not in GBP | 400 direct_debit_requires_gbp |
| The mandate does not exist, or belongs to another customer | 404 mandate_not_found |
| The mandate cannot collect yet (for example, still being set up) | 422 mandate_not_active |
A mandate that does not exist and a mandate that belongs to someone else get the same answer.
Who can call it
Creating a Direct Debit subscription needs a signed-in team member or an OAuth app with access to mandates. API keys are refused with 403: attaching a mandate authorises future debits, so it needs a person. That refusal is specific to creating the subscription. A key with the mandates:read scope can still list and retrieve mandates, and a key with the mandates:write scope can schedule collections (see below). A key cannot create, cancel, suspend or reinstate a mandate.
Scheduling a one-off collection
POST /v2/mandates/{id}/collections schedules a one-off collection against an Active mandate. When the source is an invoice, the invoice must be issued and still owe money. Issue the invoice before you schedule: a collection for a draft or pending_approval invoice is never submitted to the bank, and neither is one for a paid, void or otherwise closed invoice. It is refused at the final check before submission with 409 invoice_not_collectable. See which invoices can be collected.
Scheduling a collection moves money, so it needs both the mandates:write scope and a team member who is allowed to schedule collections. An API key acts as the team member who created it, as that member's role is now: a key created by an owner, admin or finance member can schedule a collection, and a key whose creator no longer has that role is refused with 403. Each time an API key schedules a new collection, the account's owners and admins receive an email. A retry that returns an existing collection does not send one.
Setting up the mandate first
The customer sets up the mandate themselves, from a mandate request, checkout or an invoice. You cannot create a mandate through this endpoint.
Owner: david · Reviewed 30 Sep 2026 · Next review 29 Dec 2026