> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qonto.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a recurring invoice
> OAuth scope: `client_invoice.write`
Schedules recurring invoices for a client. On each occurrence's invoice date, following the frequency you configure, an invoice is generated. Its due date is the invoice date plus `payment_terms_days`.
**Price plans:** this endpoint requires a price plan or add-on that includes recurring invoices, such as the Invoice Automation add-on. Without it, requests return `403`. It is not available for organizations in Belgium or Portugal. Requests also return `403` with code `permission_denied` while the organization's KYB is not yet accepted.
**Automatic numbering required.** The organization must have `numbering_mode` set to `automatic` (see `GET /v2/settings`) before a recurring invoice can be created. Otherwise this call returns a `412` with `code` `invalid_numbering_mode`. Call `PUT /v2/settings` with `{"numbering_mode": "automatic"}` first.
**A create can generate a real invoice immediately.** If `start_date` is today (UTC), the first invoice is created in the same request, its id is returned as `invoice_id`, and the recurring invoice's `status` is `active`. When `invoice_status` is `unpaid`, that invoice is also emailed to the client straight away. If `start_date` is in the future, no invoice exists yet: `invoice_id` is absent and `status` is `scheduled`.
`start_date` cannot be in the past (UTC).
`email_template` is required when `invoice_status` is `unpaid` (the default), because the generated invoice is sent by email using it. It can be omitted when `invoice_status` is `draft`.
Organizations with an Italian legal country must send `payment_reporting`. Without it the create is rejected with a `422`.
**Not supported yet:** a recurring invoice cannot carry a welfare fund, a withholding tax or a stamp duty. `welfare_fund`, `withholding_tax` and `stamp_duty_amount` are accepted on `POST /v2/client_invoices`. Here they are ignored if sent, and no recurring invoice endpoint returns them. Use the Qonto app for a recurring invoice that needs one of them.
**Not supported at creation:** `discount` (a discount covering the whole invoice), `purchase_order`, `terms_and_conditions`, `header`, `footer`, `end_date` and `payment_link` are ignored if sent here. They can be set afterwards with `PUT /v2/recurring_invoices/{id}`. A per-item `discount` is supported at creation.
## OpenAPI
````yaml post /v2/recurring_invoices
openapi: 3.1.1
info:
version: v2
title: Qonto
servers:
- url: https://thirdparty.qonto.com
description: Production URL
- url: https://thirdparty-sandbox.staging.qonto.co
description: Sandbox URL
security:
- OAuth:
- organization.read
- membership.read
- membership.write
- attachment.write
- internal_transfer.write
- payment.write
- supplier_invoice.write
- supplier_invoice.read
- client_invoices.read
- client_invoice.write
- client.read
- client.write
- product.read
- product.write
- request_review.write
- request_review.read
- team.read
- team.write
- request_transfers.write
- insurance_contract.read
- insurance_contract.write
- card.read
- card.write
- bank_account.write
- beneficiary.trust
- webhook
- payment_link.write
- payment_link.read
- sepa_direct_debit.read
- sepa_direct_debit.write
- terminal.read
- terminal.write
- SecretKey: []
paths:
/v2/recurring_invoices:
post:
tags:
- Recurring Invoices
summary: Create a recurring invoice
description: >
OAuth scope: `client_invoice.write`
Schedules recurring invoices for a client. On each occurrence's invoice
date, following the frequency you configure, an invoice is generated.
Its due date is the invoice date plus `payment_terms_days`.
**Price plans:** this endpoint requires a price plan or add-on that includes recurring invoices, such as the Invoice Automation add-on. Without it, requests return `403`. It is not available for organizations in Belgium or Portugal. Requests also return `403` with code `permission_denied` while the organization's KYB is not yet accepted.
**Automatic numbering required.** The organization must have `numbering_mode` set to `automatic` (see `GET /v2/settings`) before a recurring invoice can be created. Otherwise this call returns a `412` with `code` `invalid_numbering_mode`. Call `PUT /v2/settings` with `{"numbering_mode": "automatic"}` first.
**A create can generate a real invoice immediately.** If `start_date` is today (UTC), the first invoice is created in the same request, its id is returned as `invoice_id`, and the recurring invoice's `status` is `active`. When `invoice_status` is `unpaid`, that invoice is also emailed to the client straight away. If `start_date` is in the future, no invoice exists yet: `invoice_id` is absent and `status` is `scheduled`.
`start_date` cannot be in the past (UTC).
`email_template` is required when `invoice_status` is `unpaid` (the
default), because the generated invoice is sent by email using it. It
can be omitted when `invoice_status` is `draft`.
Organizations with an Italian legal country must send
`payment_reporting`. Without it the create is rejected with a `422`.
**Not supported yet:** a recurring invoice cannot carry a welfare fund, a withholding tax or a stamp duty. `welfare_fund`, `withholding_tax` and `stamp_duty_amount` are accepted on `POST /v2/client_invoices`. Here they are ignored if sent, and no recurring invoice endpoint returns them. Use the Qonto app for a recurring invoice that needs one of them.
**Not supported at creation:** `discount` (a discount covering the whole invoice), `purchase_order`, `terms_and_conditions`, `header`, `footer`, `end_date` and `payment_link` are ignored if sent here. They can be set afterwards with `PUT /v2/recurring_invoices/{id}`. A per-item `discount` is supported at creation.
operationId: create_recurring_invoice
parameters:
- $ref: '#/components/parameters/X-Qonto-Staging-Token'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RecurringInvoiceCreatePayload'
responses:
'201':
description: Returns the created recurring invoice.
content:
application/json:
schema:
type: object
required:
- recurring_invoice
properties:
recurring_invoice:
$ref: '#/components/schemas/RecurringInvoiceCreated'
'400':
$ref: '#/components/responses/400-Bad-request'
'401':
$ref: '#/components/responses/401-Unauthorized'
'403':
$ref: '#/components/responses/403-Forbidden'
'404':
description: >-
Returns a not found error when `client_id` does not match a client
of the organization.
content:
application/json:
schema:
type: object
required:
- errors
properties:
errors:
type: array
items:
type: object
required:
- code
properties:
status:
type: string
example: '404'
code:
type: string
example: customer_not_found
detail:
type: string
'412':
description: >-
Returns a precondition-failed error when automatic numbering isn't
enabled.
content:
application/json:
schema:
type: object
required:
- errors
properties:
errors:
type: array
items:
type: object
required:
- code
properties:
status:
type: string
example: '412'
code:
type: string
example: invalid_numbering_mode
'422':
$ref: '#/components/responses/422-Unprocessable-Entity'
'500':
$ref: '#/components/responses/500-Internal-Server-Error'
security:
- OAuth:
- client_invoice.write
- SecretKey: []
components:
parameters:
X-Qonto-Staging-Token:
name: X-Qonto-Staging-Token
in: header
description: >-
Required only for Sandbox API requests; to get one, please sign up to
the [Developer Portal](https://developers.qonto.com/).
schema:
type: string
schemas:
RecurringInvoiceCreatePayload:
type: object
required:
- client_id
- start_date
- payment_terms_days
- frequency
- bank_account
- items
properties:
client_id:
type: string
format: uuid
description: The client this recurring invoice bills.
example: 5c1f4e3a-9b7d-4a1e-8f2c-3d6b8a0e7f11
start_date:
type: string
format: date
description: The date of the first occurrence. Cannot be in the past (UTC).
example: '2030-01-01'
frequency:
$ref: '#/components/schemas/RecurringInvoiceFrequency'
payment_terms_days:
type: integer
minimum: 0
maximum: 365
description: Days between an occurrence's invoice date and its due date.
example: 30
invoice_status:
type: string
enum:
- draft
- unpaid
default: unpaid
description: The status each generated invoice is created as.
currency:
type: string
description: >-
Currency for the recurring invoice and its items, as an ISO 4217
trigram. Defaults to `EUR`. Every item without its own
`unit_price.currency` uses this value.
default: EUR
example: EUR
bank_account:
$ref: '#/components/schemas/RecurringInvoiceBankAccountPayload'
email_template:
$ref: '#/components/schemas/RecurringInvoiceEmailTemplatePayload'
items:
$ref: '#/components/schemas/RecurringInvoiceItemsPayload'
payment_reporting:
$ref: '#/components/schemas/RecurringInvoicePaymentReportingPayload'
RecurringInvoiceCreated:
type: object
required:
- id
- status
- start_date
- frequency
- payment_terms_days
- invoice_status
properties:
id:
type: string
format: uuid
status:
type: string
enum:
- scheduled
- active
- suspended
- canceled
- finished
description: >-
`scheduled` until the first occurrence is generated, then `active`.
See `POST /v2/recurring_invoices/{id}/cancel`, `/suspend` and
`/reactivate` for the other transitions.
start_date:
type: string
format: date
frequency:
type: object
required:
- value
- recurrence
properties:
value:
type: integer
recurrence:
type: string
enum:
- weekly
- monthly
- quarterly
- yearly
payment_terms_days:
type: integer
invoice_status:
type: string
enum:
- draft
- unpaid
invoice_id:
type: string
format: uuid
description: >-
The id of the invoice created by this request, when `start_date` is
today. Absent otherwise.
RecurringInvoiceFrequency:
type: object
required:
- value
- recurrence
properties:
value:
type: integer
minimum: 1
description: How many `recurrence` units elapse between two occurrences.
example: 1
recurrence:
type: string
enum:
- weekly
- monthly
- quarterly
- yearly
example: monthly
description: >-
Together, `value` and `recurrence` define the schedule. For example,
`{"value": 2, "recurrence": "monthly"}` bills every two months.
RecurringInvoiceBankAccountPayload:
type: object
required:
- iban
properties:
iban:
type: string
description: >-
The IBAN generated invoices are paid to. When it is not one of the
organization's bank accounts, it is saved as a manual bank account.
example: FR7630006000011234567890189
description: The bank account generated invoices are paid to, identified by IBAN.
RecurringInvoiceEmailTemplatePayload:
type: object
required:
- send_to
- email_title
description: >-
How each generated invoice is emailed to the client. Required when
`invoice_status` is `unpaid` (or omitted, since that's the default);
optional when `invoice_status` is `draft`.
properties:
send_to:
type: array
minItems: 1
items:
type: string
format: email
description: The email addresses each generated invoice is sent to.
example:
- accounting@acme.com
copy_to_self:
type: boolean
default: false
description: >-
Whether a copy of each generated invoice email is also sent to your
organization's contact email.
email_title:
type: string
description: The subject of the email each generated invoice is sent with.
example: Your invoice
email_body:
type: string
description: The body of the email each generated invoice is sent with.
RecurringInvoiceItemsPayload:
type: array
minItems: 1
description: The line items billed on every occurrence.
items:
type: object
required:
- title
- quantity
- unit_price
- vat_rate
properties:
title:
type: string
maxLength: 120
description: The item's title.
example: Consulting
description:
type: string
maxLength: 1800
description: The item's description.
quantity:
type: string
description: The item's quantity. Decimals are separated by a period ".".
example: '1'
unit:
type: string
maxLength: 50
description: The item's unit, for example `hour` or `day`.
unit_price:
type: object
required:
- value
properties:
value:
type: string
description: Price per unit. Decimals are separated by a period ".".
example: '100.00'
currency:
type: string
description: >-
ISO 4217 currency trigram. Defaults to the recurring invoice's
top-level `currency` when omitted. A different currency is
rejected with a `422`.
example: EUR
vat_rate:
type: string
description: >-
VAT rate, written as a decimal between `0` and `1`. For example,
`0.2` for a 20% VAT rate.
example: '0.2'
vat_exemption_code:
type: string
description: >-
VAT exemption code. Only allowed when `vat_rate` is `0`. Required
when `vat_rate` is `0` for Italian organizations and for French
organizations subject to e-reporting. The allowed codes depend on
the organization's country and are the same as for
`vat_exemption_reason` on client invoice items.
discount:
type: object
required:
- type
- value
properties:
type:
type: string
enum:
- percentage
- absolute
description: Type of the discount for that item.
value:
type: string
description: >-
The rate (for `percentage`, between `0` and `1`) or amount
(for `absolute`) discounted.
example: '0.1'
RecurringInvoicePaymentReportingPayload:
type: object
description: >-
Italian payment reporting details, required for organizations with an
Italian legal country. When sent, both `method` and `conditions` are
required. Non-Italian organizations should not send this property.
required:
- method
- conditions
properties:
method:
type: string
enum:
- MP01
- MP02
- MP03
- MP04
- MP05
- MP06
- MP07
- MP08
- MP09
- MP10
- MP11
- MP12
- MP13
- MP14
- MP15
- MP16
- MP17
- MP18
- MP19
- MP20
- MP21
- MP22
- MP23
description: Payment method of the generated invoices.
example: MP01
conditions:
type: string
enum:
- TP01
- TP02
- TP03
description: Payment conditions of the generated invoices.
example: TP01
BadRequestResponseBody:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/BadRequestError'
required:
- errors
UnauthorizedResponseBody:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/UnauthorizedError'
required:
- errors
ForbiddenResponseBody:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ForbiddenError'
required:
- errors
UnprocessableEntityError:
type: object
properties:
status:
type: string
example: unprocessable entity
code:
type: string
description: Error code.
example: missing_key
detail:
type: string
description: Human readable error that explains error `code`.
example: property is missing
message:
type: string
example: property id is missing
source:
type: object
properties:
pointer:
type: string
description: >-
The property and the item in an array (if applicable) that
causes the error.
example: id
required:
- code
- detail
BadRequestError:
type: object
properties:
code:
type: string
description: Error code.
detail:
type: string
description: Human readable error that explains error `code`.
source:
type: object
properties:
pointer:
type: string
description: >-
The property in the request body that caused the error
(optional).
parameter:
type: string
description: The query parameter that caused the error (optional).
required:
- code
- detail
x-examples:
Authorization field missing:
code: bad_request
detail: Authorization field missing
UnauthorizedError:
type: object
properties:
code:
type: string
description: Error code.
detail:
type: string
description: Human readable error that explains error `code`.
required:
- code
- detail
x-examples:
Invalid credentials:
code: unauthorized
detail: Invalid credentials
ForbiddenError:
type: object
properties:
code:
type: string
description: Error code.
detail:
type: string
description: Human readable error that explains error `code`.
required:
- code
- detail
x-examples:
Insufficient permissions:
code: forbidden
detail: User does not have sufficient permissions for this action.
responses:
400-Bad-request:
description: Returns a bad request error.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseBody'
examples:
Authorization field missing:
value:
errors:
- code: bad_request
detail: Authorization field missing
401-Unauthorized:
description: Returns an unauthorized error.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponseBody'
examples:
authorization_header_missing:
value:
errors:
- code: authorization_header_missing
detail: authorization header missing
authorization_token_invalid:
value:
errors:
- code: authorization_token_invalid
detail: authorization token invalid
403-Forbidden:
description: Returns a forbidden error.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseBody'
examples:
Insufficient permissions:
value:
errors:
- code: forbidden
detail: User does not have sufficient permissions for this action.
422-Unprocessable-Entity:
description: Returns an unprocessable entity error.
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/UnprocessableEntityError'
500-Internal-Server-Error:
description: Returns an internal server error.
securitySchemes:
OAuth:
type: oauth2
description: >
Bearer authorization header: `Bearer `, where `` is the
access token received from the authorization server at the end of the
[OAuth 2.0
flow](/get-started/business-api/authentication/oauth/oauth-flow).
flows:
authorizationCode:
refreshUrl: https://oauth.qonto.com/oauth2/token
authorizationUrl: https://oauth.qonto.com/oauth2/auth
scopes:
attachment.read: Retrieve attachments
attachment.write: Upload attachments and remove attachments from transactions
bank_account.write: Create, update and close bank accounts
beneficiary.trust: Trust SEPA beneficiaries
card.read: Retrieve cards
card.write: Create or update cards
cash_flow_category.read: Retrieve cash flow categories
cash_flow_category.write: >-
Create, update and delete cash flow categories, and assign them to
transactions
client.read: Retrieve clients
client.write: Create clients
client_invoice.write: Create client invoices
client_invoices.read: Retrieve client invoices and credit notes
einvoicing.read: Retrieve e-invoicing settings
embed_auth_link.write: Create Embed auth links
insurance_contract.read: Retrieve insurance contracts
insurance_contract.write: Create and update insurance contracts
internal_transfer.write: >-
Create internal transfers (between 2 Qonto accounts of the same
organization)
international_transfer.write: Create international transfers
membership.read: Retrieve the authentified membership
membership.write: Invite team members
offline_access: Retrieve a refresh token
organization.read: >-
Retrieve organization, bank accounts, transactions, transfers,
beneficiaries, labels, memberships, requests & statements
payment.write: Create external transfers and untrust beneficiaries
payment_link.read: >-
Retrieve payment links, their payments, and the available payment
methods
payment_link.write: >-
Connect to the payment links provider, create and deactivate
payment links
product.read: Retrieve products
product.write: Create products
request_cards.write: Create card requests
request_review.write: Approve or decline requests
request_transfers.write: Create transfer requests
sepa_direct_debit.read: View SEPA Direct Debit payments
sepa_direct_debit.write: Manage SEPA Direct Debit payments
subscription.read: Retrieve the organization's current subscription plan
supplier_invoice.read: Retrieve supplier invoices
supplier_invoice.write: Create supplier invoices
team.read: Retrieve teams
team.write: Create teams
terminal.read: View your payment terminals
terminal.write: Configure your terminals and initiate payments
user_organization.read: View the organizations the user has granted access to
webhook: >-
Receive a notification each time a particular event occurs in
Qonto
tokenUrl: https://oauth.qonto.com/oauth2/token
SecretKey:
type: apiKey
description: cf. [API key](/get-started/business-api/authentication/api-key)
name: Authorization
in: header
````