> ## 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.
# Suspend a recurring invoice
> OAuth scope: `client_invoice.write`
Suspends the recurring invoice identified by the `id` path parameter, so no invoice is generated while it stays `suspended`. Invoices already generated are not changed.
**Suspending does not pause the schedule.** While suspended, `next_invoice_date` is left out of responses, but the schedule keeps moving. If you suspend for three months and then reactivate, generation resumes at the next scheduled date. The three skipped invoices are not generated.
**Only an `active` recurring invoice can be suspended.** A `scheduled` one, whose first invoice has not been generated yet, returns `412 recurring_invoice_status_transition_forbidden`. Cancel it instead. `canceled` and `finished` are final and cannot be suspended either.
Takes no request body.
## OpenAPI
````yaml post /v2/recurring_invoices/{id}/suspend
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}/suspend:
post:
tags:
- Recurring Invoices
summary: Suspend a recurring invoice
description: >
OAuth scope: `client_invoice.write`
Suspends the recurring invoice identified by the `id` path parameter, so
no invoice is generated while it stays `suspended`. Invoices already
generated are not changed.
**Suspending does not pause the schedule.** While suspended, `next_invoice_date` is left out of responses, but the schedule keeps moving. If you suspend for three months and then reactivate, generation resumes at the next scheduled date. The three skipped invoices are not generated.
**Only an `active` recurring invoice can be suspended.** A `scheduled`
one, whose first invoice has not been generated yet, returns `412
recurring_invoice_status_transition_forbidden`. Cancel it instead.
`canceled` and `finished` are final and cannot be suspended either.
Takes no request body.
operationId: suspend_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
responses:
'200':
description: The recurring invoice, now suspended.
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':
$ref: '#/components/responses/404-Not-Found'
'412':
description: >-
The recurring invoice cannot move to `suspended` from its current
status.
content:
application/json:
schema:
$ref: '#/components/schemas/RecurringInvoiceStatusTransitionForbidden'
example:
errors:
- code: recurring_invoice_status_transition_forbidden
detail: >-
A scheduled recurring invoice cannot be moved to
suspended.
meta:
current_status: scheduled
status: suspended
'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:
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
RecurringInvoiceStatusTransitionForbidden:
type: object
required:
- errors
properties:
errors:
type: array
items:
type: object
required:
- code
- detail
properties:
status:
type: string
example: '412'
code:
type: string
example: recurring_invoice_status_transition_forbidden
detail:
type: string
meta:
type: object
properties:
current_status:
type: string
description: The status the recurring invoice is in.
status:
type: string
description: >-
The status the request tried to move it to. On the `412`
of `PUT /v2/recurring_invoices/{id}`, `meta.status` is the
current status instead.
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
NotFoundError:
type: object
properties:
code:
type: string
description: Error code.
detail:
type: string
description: Human readable error that explains error `code`.
source:
type: object
properties:
parameter:
type: string
description: The parameter that causes the error.
required:
- code
- detail
x-examples:
Object not found:
code: not_found
detail: Object not found
source:
parameter: id
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.
404-Not-Found:
description: Returns a not found error.
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/NotFoundError'
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
````