> ## 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.
# Update a recurring invoice
> OAuth scope: `client_invoice.write`
Replaces the recurring invoice identified by the `id` path parameter. The body is the complete recurring invoice. To change one field, send the current values of all the others alongside it. `GET /v2/recurring_invoices/{id}` returns them.
**Leaving a field out clears or resets it.** `purchase_order`, `terms_and_conditions`, `header`, `footer`, `end_date`, `discount`, `email_template`, `payment_link` and `payment_reporting` are removed if the body does not carry them, even when they were set in the Qonto app. `currency` is reset to `EUR` and `invoice_status` to `unpaid`. `items` is replaced as a whole, and the new items get new ids.
Settings this endpoint does not accept are kept: direct debit, welfare fund, withholding tax, stamp duty, e-invoicing and the attachment.
**What you can change depends on the current status.**
- `scheduled`: every field can change.
- `active` and `suspended`: `frequency` and `start_date` cannot change. Sending a different value returns a `422` with `code` `frequency_not_updatable` or `start_date_not_updatable`. Every other field can still change.
- `canceled` and `finished`: the recurring invoice cannot be updated. A valid request returns a `412` with `code` `recurring_invoice_not_updatable`.
Updating a `scheduled` recurring invoice whose `start_date` is today generates an invoice immediately, and the recurring invoice becomes `active`. The response does not include the id of that invoice.
Organizations with an Italian legal country must send `payment_reporting`. Without it the request returns a `422`.
## OpenAPI
````yaml put /v2/recurring_invoices/{id}
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/{id}:
put:
tags:
- Recurring Invoices
summary: Update a recurring invoice
description: >
OAuth scope: `client_invoice.write`
Replaces the recurring invoice identified by the `id` path parameter.
The body is the complete recurring invoice. To change one field, send
the current values of all the others alongside it. `GET
/v2/recurring_invoices/{id}` returns them.
**Leaving a field out clears or resets it.** `purchase_order`, `terms_and_conditions`, `header`, `footer`, `end_date`, `discount`, `email_template`, `payment_link` and `payment_reporting` are removed if the body does not carry them, even when they were set in the Qonto app. `currency` is reset to `EUR` and `invoice_status` to `unpaid`. `items` is replaced as a whole, and the new items get new ids.
Settings this endpoint does not accept are kept: direct debit, welfare fund, withholding tax, stamp duty, e-invoicing and the attachment.
**What you can change depends on the current status.**
- `scheduled`: every field can change.
- `active` and `suspended`: `frequency` and `start_date` cannot change. Sending a different value returns a `422` with `code` `frequency_not_updatable` or `start_date_not_updatable`. Every other field can still change.
- `canceled` and `finished`: the recurring invoice cannot be updated. A valid request returns a `412` with `code` `recurring_invoice_not_updatable`.
Updating a `scheduled` recurring invoice whose `start_date` is today
generates an invoice immediately, and the recurring invoice becomes
`active`. The response does not include the id of that invoice.
Organizations with an Italian legal country must send
`payment_reporting`. Without it the request returns a `422`.
operationId: update_recurring_invoice
parameters:
- $ref: '#/components/parameters/X-Qonto-Staging-Token'
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The unique identifier of the recurring invoice.
example: 0198f2c1-8a3e-7c11-9f4d-2b6a7c8e9d01
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RecurringInvoiceUpdatePayload'
responses:
'200':
description: Returns the updated recurring invoice.
content:
application/json:
schema:
type: object
required:
- recurring_invoice
properties:
recurring_invoice:
$ref: '#/components/schemas/RecurringInvoice'
'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 with code `subscription_not_found` when no
recurring invoice with this id exists in the organization, or
`customer_not_found` 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
enum:
- subscription_not_found
- customer_not_found
example: subscription_not_found
detail:
type: string
'412':
description: >
Returns a precondition-failed error when the recurring invoice is
`canceled` or `finished`.
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: recurring_invoice_not_updatable
detail:
type: string
example: >-
A canceled or finished recurring invoice cannot be
updated.
meta:
type: object
properties:
status:
type: string
description: The current status of the recurring invoice.
example: canceled
'422':
description: >
Returns an unprocessable-entity error when the payload is invalid,
when `id` is not a UUID (code `invalid`), or when the request
changes a field that cannot change in the current status.
content:
application/json:
schema:
type: object
required:
- errors
properties:
errors:
type: array
items:
type: object
required:
- code
properties:
status:
type: string
example: '422'
code:
type: string
description: >
`frequency_not_updatable` or
`start_date_not_updatable` when the recurring
invoice is `active` or `suspended` and the request
changes that field. Any other code indicates an
invalid payload.
example: frequency_not_updatable
detail:
type: string
example: >-
frequency cannot be changed once the recurring
invoice is active or suspended.
source:
type: object
properties:
pointer:
type: string
description: The request field that caused the error.
example: frequency
'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:
RecurringInvoiceUpdatePayload:
type: object
description: >-
The complete recurring invoice. A field you leave out is cleared or
reset to its default, so send every field you want to keep. Settings
this endpoint does not accept, such as direct debit, welfare fund,
withholding tax and stamp duty, are kept as they are.
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 change once the recurring
invoice is `active` or `suspended`.
example: '2030-01-01'
end_date:
type: string
format: date
nullable: true
description: >-
The date after which no further invoice is generated. Must be on or
after `start_date`. Leave it out to remove it.
example: '2031-01-01'
currency:
type: string
description: >-
Currency for the recurring invoice and its items, as an ISO 4217
trigram. Every item's currency has to match it. Reset to `EUR` when
left out, even if the recurring invoice used another currency.
example: EUR
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
description: >-
The status each generated invoice is created as. Reset to `unpaid`
when left out, even if it was `draft`.
frequency:
$ref: '#/components/schemas/RecurringInvoiceFrequency'
description: Cannot change once the recurring invoice is `active` or `suspended`.
bank_account:
$ref: '#/components/schemas/RecurringInvoiceBankAccountPayload'
email_template:
$ref: '#/components/schemas/RecurringInvoiceEmailTemplatePayload'
description: >-
How each generated invoice is emailed to the client. Required when
`invoice_status` is `unpaid`. Leave it out to remove it, which is
only valid when `invoice_status` is `draft`.
items:
$ref: '#/components/schemas/RecurringInvoiceItemsPayload'
description: >-
The line items billed on every occurrence. The whole list is
replaced, and the new items get new ids.
purchase_order:
type: string
maxLength: 40
nullable: true
description: >-
The purchase order reference printed on every generated invoice.
Leave it out to remove it.
example: PO-2026-001
terms_and_conditions:
type: string
nullable: true
maxLength: 50000
description: >-
The terms and conditions printed on every generated invoice. Leave
them out to remove them.
header:
type: string
nullable: true
maxLength: 50000
description: >-
The header printed on every generated invoice. Leave it out to
remove it.
footer:
type: string
nullable: true
maxLength: 50000
description: >-
The footer printed on every generated invoice. Leave it out to
remove it.
discount:
type: object
nullable: true
description: >-
An overall discount applied to every generated invoice. Leave it out
to remove the discount.
required:
- type
- value
properties:
type:
type: string
enum:
- percentage
- absolute
value:
type: string
description: >-
The rate (for `percentage`, between `0` and `1`) or amount (for
`absolute`) discounted.
example: '0.1'
payment_link:
type: object
nullable: true
description: >-
The payment methods offered on every generated invoice. Leave it
out, or send an empty `methods` list, to remove the payment link.
properties:
methods:
type: array
items:
type: string
enum:
- credit_card
- apple_pay
- paypal
- bank_transfer
- ideal
example:
- credit_card
payment_reporting:
$ref: '#/components/schemas/RecurringInvoicePaymentReportingPayload'
description: >-
Italian payment reporting details. Required for organizations with
an Italian legal country. For other organizations, leave them out to
remove them.
RecurringInvoice:
type: object
required:
- id
- status
- client_id
- start_date
- frequency
- payment_terms_days
- invoice_status
- purchase_order
- terms_and_conditions
- header
- footer
- currency
- amount_due
- bank_account
- email_template
- direct_debit_enabled
- is_einvoice
- items
- created_at
- updated_at
properties:
id:
type: string
format: uuid
example: 0198f2c1-8a3e-7c11-9f4d-2b6a7c8e9d01
status:
type: string
enum:
- scheduled
- active
- suspended
- canceled
- finished
description: >-
- `scheduled`: no invoice has been generated yet.
- `active`: invoices are generated on each occurrence.
- `suspended`: paused with `POST
/v2/recurring_invoices/{id}/suspend`. No invoice is generated until
it is reactivated.
- `canceled`: stopped with `POST
/v2/recurring_invoices/{id}/cancel`.
- `finished`: `end_date` has passed. Set automatically.
`canceled` and `finished` are final.
client_id:
type: string
format: uuid
description: The client this recurring invoice bills.
example: 5c1f4e3a-9b7d-4a1e-8f2c-3d6b8a0e7f11
client_name:
type: string
description: >-
The client's name as of the last create or update of the recurring
invoice. Absent when the client has no name.
example: ACME SAS
start_date:
type: string
format: date
description: The date of the first occurrence.
example: '2026-09-01'
end_date:
type: string
format: date
description: >-
The date after which no further invoice is generated. Absent when
the schedule has no end. Can only be set with `PUT
/v2/recurring_invoices/{id}`.
next_invoice_date:
type: string
format: date
description: >-
The next date on which an invoice is scheduled to be generated.
Absent while `status` is `suspended`. It is not cleared when the
recurring invoice is canceled or finished, so check `status` to know
whether the schedule is still running.
example: '2026-10-01'
prev_invoice_date:
type: string
format: date
description: >-
The date the most recent invoice was generated. Only set on some
older recurring invoices. Absent otherwise.
frequency:
type: object
required:
- value
- recurrence
properties:
value:
type: integer
example: 1
recurrence:
type: string
enum:
- weekly
- monthly
- quarterly
- yearly
example: monthly
payment_terms_days:
type: integer
description: Days between an occurrence's invoice date and its due date.
example: 30
invoice_status:
type: string
enum:
- draft
- unpaid
description: The status each generated invoice is created as.
purchase_order:
type: string
description: >-
The purchase order reference printed on every generated invoice. An
empty string when none is set. Can only be set with `PUT
/v2/recurring_invoices/{id}`.
example: PO-2026-042
terms_and_conditions:
type: string
description: >-
The terms and conditions printed on every generated invoice. An
empty string when none are set. Can only be set with `PUT
/v2/recurring_invoices/{id}`.
header:
type: string
description: >-
The header printed on every generated invoice. An empty string when
none is set. Can only be set with `PUT /v2/recurring_invoices/{id}`.
footer:
type: string
description: >-
The footer printed on every generated invoice. An empty string when
none is set. Can only be set with `PUT /v2/recurring_invoices/{id}`.
currency:
type: string
description: ISO 4217 currency trigram.
example: EUR
amount_due:
type: object
description: The total amount each occurrence bills.
required:
- value
- currency
properties:
value:
type: string
example: '120.00'
currency:
type: string
example: EUR
discount:
type: object
description: >-
A discount covering the whole invoice, applied to every occurrence.
Absent when none is set. Can only be set with `PUT
/v2/recurring_invoices/{id}`.
required:
- type
- value
properties:
type:
type: string
enum:
- percentage
- absolute
value:
type: string
description: >-
The rate (for `percentage`, between `0` and `1`, with 4
decimals) or amount (for `absolute`, with 2 decimals)
discounted.
example: '0.1000'
bank_account:
type: object
description: The bank account generated invoices are paid to.
properties:
iban:
type: string
example: FR7630006000011234567890189
bic:
type: string
example: QNTOFRP1XXX
email_template:
type: object
nullable: true
description: >-
How each generated invoice is emailed to the client. `null` when no
template is configured, which is only possible when `invoice_status`
is `draft`.
required:
- send_to
- copy_to_self
- email_title
- email_body
properties:
send_to:
type: array
items:
type: string
format: email
example:
- accounting@acme.com
copy_to_self:
type: boolean
email_title:
type: string
example: Your invoice
email_body:
type: string
payment_link:
type: object
description: >-
The payment methods offered on each generated invoice. Absent when
no payment method is enabled. Can only be set with `PUT
/v2/recurring_invoices/{id}`.
required:
- methods
properties:
methods:
type: array
items:
type: string
enum:
- credit_card
- apple_pay
- paypal
- bank_transfer
- ideal
example: credit_card
payment_reporting:
type: object
description: Italian payment reporting details. Absent when none are set.
properties:
method:
type: string
example: MP01
conditions:
type: string
example: TP01
direct_debit_enabled:
type: boolean
description: >-
Whether generated invoices are collected by SEPA direct debit. Set
in the Qonto app only.
is_einvoice:
type: boolean
description: >-
Whether generated invoices are issued as electronic invoices. Set in
the Qonto app only.
items:
type: array
description: The line items billed on every occurrence.
items:
type: object
required:
- title
- description
- quantity
- unit_price
- vat_rate
properties:
title:
type: string
example: Consulting
description:
type: string
quantity:
type: string
example: '1'
unit:
type: string
example: hour
unit_price:
type: object
required:
- value
- currency
properties:
value:
type: string
example: '100.00'
currency:
type: string
example: EUR
vat_rate:
type: string
example: '0.2'
vat_exemption_code:
type: string
discount:
type: object
required:
- type
- value
properties:
type:
type: string
enum:
- percentage
- absolute
value:
type: string
description: >-
The rate (for `percentage`, with 4 decimals) or amount
(for `absolute`, with 2 decimals) discounted.
example: '0.1000'
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
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
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.
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
````