invoiceninja/openapi/paths/recurring_invoices.yaml

706 lines
24 KiB
YAML

/api/v1/recurring_invoices:
get:
tags:
- Recurring Invoices
summary: "List recurring invoices"
description: |
## GET /api/v1/recurring_invoices
Lists invoices with the option to chain multiple query parameters allowing fine grained filtering of the list.
x-codeSamples:
- lang: php
label: php
source: |
$ninja = new InvoiceNinja("your_token");
$invoices = $ninja->recurring_invoices->all([
'per_page' => 10,
'page' => 1,
'sort' => 'number|asc'
]);
- lang: curl
label: curl
source: |
curl --request GET \
--url 'https://invoicing.co/api/v1/recurring_invoices?per_page=10&page=1&sort=number&sort_dir=asc' \
--header 'X-API-TOKEN: YOUR_API_TOKEN_HERE' \
--header 'Accept: application/json'
operationId: getRecurringInvoices
parameters:
- $ref: "#/components/parameters/X-API-TOKEN"
- $ref: "#/components/parameters/X-Requested-With"
- $ref: "#/components/parameters/include"
- $ref: "#/components/parameters/client_id"
- $ref: "#/components/parameters/created_at"
- $ref: "#/components/parameters/updated_at"
- $ref: "#/components/parameters/is_deleted"
- $ref: "#/components/parameters/filter_deleted_clients"
- $ref: "#/components/parameters/vendor_id"
- name: filter
in: query
description: |
Searches across a range of columns including:
- custom_value1
- custom_value2
- custom_value3
- custom_value4
required: false
schema:
type: string
example: ?filter=bob
- name: client_status
in: query
description: |
A comma separated list of invoice status strings. Valid options include:
- all
- active
- paused
- completed
required: false
schema:
type: string
example: ?client_status=active,paused
- name: sort
in: query
description: Returns the list sorted by column in ascending or descending order.
required: false
schema:
type: string
example: id|desc number|desc balance|asc
- name: number
in: query
description: |
Filters the list by number.
required: false
schema:
type: string
example: ?number=123
- name: product_key
in: query
description: |
Filters the list by product_key.
required: false
schema:
type: string
example: ?product_key=123
- name: next_send_between
in: query
description: |
Filters the list by next_send_between.
required: false
schema:
type: string
example: ?next_send_between=2025-01-01|2025-01-31
- name: frequency_id
in: query
description: |
Filters the list by frequency_id.
required: false
schema:
type: string
example: ?frequency_id=1,2,3
responses:
200:
description: "A list of recurring_invoices"
headers:
X-MINIMUM-CLIENT-VERSION:
$ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
X-RateLimit-Remaining:
$ref: "#/components/headers/X-RateLimit-Remaining"
X-RateLimit-Limit:
$ref: "#/components/headers/X-RateLimit-Limit"
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/RecurringInvoice'
meta:
type: object
$ref: '#/components/schemas/Meta'
401:
$ref: "#/components/responses/401"
403:
$ref: "#/components/responses/403"
422:
$ref: '#/components/responses/422'
429:
$ref: '#/components/responses/429'
5XX:
description: 'Server error'
default:
$ref: "#/components/responses/default"
post:
tags:
- Recurring Invoices
summary: "Create recurring invoice"
description: |
## POST /api/v1/recurring_invoices
Adds a Recurring Invoice to the system
operationId: storeRecurringInvoice
parameters:
- $ref: "#/components/parameters/X-API-TOKEN"
- $ref: "#/components/parameters/X-Requested-With"
- $ref: "#/components/parameters/include"
x-codeSamples:
- lang: php
label: php
source: |
$ninja = new InvoiceNinja("your_token");
$invoices = $ninja->recurring_invoices->create([
'client_id' => 'AxP7K9nY5z',
'date' => '2022-01-01',
'due_date' => '2022-01-31',
'private_notes' => 'super secret',
'public_notes' => 'public notes',
'custom_value1' => 'custom value 1',
'custom_value2' => 'custom value 2',
'line_items' => [
[
'quantity' => 1,
'cost' => 14,
'product_key' => 'sku_4_u',
'notes' => 'The actual product description',
'discount' => 0,
'is_amount_discount' => true,
'tax_name1' => '',
'tax_rate1' => 0,
'tax_name2' => '',
'tax_rate2' => 0,
'tax_name3' => '',
'tax_rate3' => 0,
'sort_id' => '0',
'custom_value1' => 'https://picsum.photos/200',
'custom_value2' => '94',
'custom_value3' => 'Alias vel eveniet.',
'custom_value4' => 'Iusto aut quis qui.',
'type_id' => '1',
'tax_id' => '1'
]
]
]);
- lang: curl
label: curl
source: |
curl --request POST \
--url 'https://invoicing.co/api/v1/recurring_invoices' \
--header 'X-API-TOKEN: YOUR_API_TOKEN_HERE' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"client_id": "AxP7K9nY5z",
"date": "2022-01-01",
"due_date": "2022-01-31",
"private_notes": "super secret",
"public_notes": "public notes",
"custom_value1": "custom value 1",
"custom_value2": "custom value 2",
"line_items": [
{
"quantity": 1,
"cost": 14,
"product_key": "sku_4_u",
"notes": "The actual product description",
"discount": 0,
"is_amount_discount": true,
"tax_name1": "",
"tax_rate1": 0,
"tax_name2": "",
"tax_rate2": 0,
"tax_name3": "",
"tax_rate3": 0,
"sort_id": "0",
"custom_value1": "https://picsum.photos/200",
"custom_value2": "94",
"custom_value3": "Alias vel eveniet.",
"custom_value4": "Iusto aut quis qui.",
"type_id": "1",
"tax_id": "1"
}
]
}'
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/RecurringInvoiceRequest"
responses:
200:
description: "Returns the saved RecurringInvoice object"
headers:
X-MINIMUM-CLIENT-VERSION:
$ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
X-RateLimit-Remaining:
$ref: "#/components/headers/X-RateLimit-Remaining"
X-RateLimit-Limit:
$ref: "#/components/headers/X-RateLimit-Limit"
content:
application/json:
schema:
$ref: "#/components/schemas/RecurringInvoice"
401:
$ref: "#/components/responses/401"
403:
$ref: "#/components/responses/403"
422:
$ref: '#/components/responses/422'
429:
$ref: '#/components/responses/429'
5XX:
description: 'Server error'
default:
$ref: "#/components/responses/default"
"/api/v1/recurring_invoices/{id}":
get:
tags:
- Recurring Invoices
summary: "Show recurring invoice"
description: "Displays an RecurringInvoice by id"
operationId: showRecurringInvoice
parameters:
- $ref: "#/components/parameters/X-API-TOKEN"
- $ref: "#/components/parameters/X-Requested-With"
- $ref: "#/components/parameters/include"
- name: id
in: path
description: "The RecurringInvoice Hashed ID"
required: true
schema:
type: string
format: string
example: D2J234DFA
responses:
200:
description: "Returns the RecurringInvoice object"
headers:
X-MINIMUM-CLIENT-VERSION:
$ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
X-RateLimit-Remaining:
$ref: "#/components/headers/X-RateLimit-Remaining"
X-RateLimit-Limit:
$ref: "#/components/headers/X-RateLimit-Limit"
content:
application/json:
schema:
$ref: "#/components/schemas/RecurringInvoice"
401:
$ref: "#/components/responses/401"
403:
$ref: "#/components/responses/403"
422:
$ref: '#/components/responses/422'
429:
$ref: '#/components/responses/429'
5XX:
description: 'Server error'
default:
$ref: "#/components/responses/default"
put:
tags:
- Recurring Invoices
summary: "Update recurring invoice"
description: "Handles the updating of an RecurringInvoice by id"
operationId: updateRecurringInvoice
parameters:
- $ref: "#/components/parameters/X-API-TOKEN"
- $ref: "#/components/parameters/X-Requested-With"
- $ref: "#/components/parameters/include"
- name: id
in: path
description: "The RecurringInvoice Hashed ID"
required: true
schema:
type: string
format: string
example: D2J234DFA
responses:
200:
description: "Returns the RecurringInvoice object"
headers:
X-MINIMUM-CLIENT-VERSION:
$ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
X-RateLimit-Remaining:
$ref: "#/components/headers/X-RateLimit-Remaining"
X-RateLimit-Limit:
$ref: "#/components/headers/X-RateLimit-Limit"
content:
application/json:
schema:
$ref: "#/components/schemas/RecurringInvoice"
401:
$ref: "#/components/responses/401"
403:
$ref: "#/components/responses/403"
422:
$ref: '#/components/responses/422'
429:
$ref: '#/components/responses/429'
5XX:
description: 'Server error'
default:
$ref: "#/components/responses/default"
delete:
tags:
- Recurring Invoices
summary: "Delete recurring invoice"
description: "Handles the deletion of an RecurringInvoice by id"
operationId: deleteRecurringInvoice
parameters:
- $ref: "#/components/parameters/X-API-TOKEN"
- $ref: "#/components/parameters/X-Requested-With"
- $ref: "#/components/parameters/include"
- name: id
in: path
description: "The RecurringInvoice Hashed ID"
required: true
schema:
type: string
format: string
example: D2J234DFA
responses:
200:
description: "Returns a HTTP status"
headers:
X-MINIMUM-CLIENT-VERSION:
$ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
X-RateLimit-Remaining:
$ref: "#/components/headers/X-RateLimit-Remaining"
X-RateLimit-Limit:
$ref: "#/components/headers/X-RateLimit-Limit"
401:
$ref: "#/components/responses/401"
403:
$ref: "#/components/responses/403"
422:
$ref: '#/components/responses/422'
429:
$ref: '#/components/responses/429'
5XX:
description: 'Server error'
default:
$ref: "#/components/responses/default"
"/api/v1/recurring_invoices/{id}/edit":
get:
tags:
- Recurring Invoices
summary: "Edit recurring invoice"
description: "Displays an RecurringInvoice by id"
operationId: editRecurringInvoice
parameters:
- $ref: "#/components/parameters/X-API-TOKEN"
- $ref: "#/components/parameters/X-Requested-With"
- $ref: "#/components/parameters/include"
- name: id
in: path
description: "The RecurringInvoice Hashed ID"
required: true
schema:
type: string
format: string
example: D2J234DFA
responses:
200:
description: "Returns the RecurringInvoice object"
headers:
X-MINIMUM-CLIENT-VERSION:
$ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
X-RateLimit-Remaining:
$ref: "#/components/headers/X-RateLimit-Remaining"
X-RateLimit-Limit:
$ref: "#/components/headers/X-RateLimit-Limit"
content:
application/json:
schema:
$ref: "#/components/schemas/RecurringInvoice"
401:
$ref: "#/components/responses/401"
403:
$ref: "#/components/responses/403"
422:
$ref: '#/components/responses/422'
429:
$ref: '#/components/responses/429'
5XX:
description: 'Server error'
default:
$ref: "#/components/responses/default"
/api/v1/recurring_invoices/create:
get:
tags:
- Recurring Invoices
summary: "Blank recurring invoice"
description: "Returns a blank object with default values"
operationId: getRecurringInvoicesCreate
parameters:
- $ref: "#/components/parameters/X-API-TOKEN"
- $ref: "#/components/parameters/X-Requested-With"
- $ref: "#/components/parameters/include"
responses:
200:
description: "A blank RecurringInvoice object"
headers:
X-MINIMUM-CLIENT-VERSION:
$ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
X-RateLimit-Remaining:
$ref: "#/components/headers/X-RateLimit-Remaining"
X-RateLimit-Limit:
$ref: "#/components/headers/X-RateLimit-Limit"
content:
application/json:
schema:
$ref: "#/components/schemas/RecurringInvoice"
401:
$ref: "#/components/responses/401"
403:
$ref: "#/components/responses/403"
422:
$ref: '#/components/responses/422'
429:
$ref: '#/components/responses/429'
5XX:
description: 'Server error'
default:
$ref: "#/components/responses/default"
/api/v1/recurring_invoices/bulk:
post:
tags:
- Recurring Invoices
summary: "Bulk recurring invoice actions"
description: |
There are multiple actions that are available including:
operationId: bulkRecurringInvoices
parameters:
- $ref: "#/components/parameters/X-API-TOKEN"
- $ref: "#/components/parameters/X-Requested-With"
- $ref: "#/components/parameters/index"
requestBody:
description: "Bulk action details"
required: true
content:
application/json:
schema:
type: object
properties:
action:
type: string
description: |
The action to be performed, options include:
- `start`
Starts (or restarts) the recurring invoice. **note** if the recurring invoice has been stopped for a long time, it will attempt to catch back up firing a new Invoice every hour per interval that has been missed.
If you do not wish to have the recurring invoice catch up, you should set the next_send_date to the correct date you wish the recurring invoice to commence from.
- `stop`
Stops the recurring invoice.
- `send_now`
Force sends the recurring invoice - this option is only available when the recurring invoice is in a draft state.
- `restore`
Restores the recurring invoice from an archived or deleted state.
- `archive`
Archives the recurring invoice. The recurring invoice will not fire in this state.
- `delete`
Deletes a recurring invoice.
ids:
type: array
items:
description: "Array of hashed IDs to be bulk 'actioned - ['D2J234DFA','D2J234DFA','D2J234DFA']"
type: string
example:
action: start
ids: ['D2J234DFA','D2J234DFA','D2J234DFA']
responses:
200:
description: "The RecurringInvoice response"
headers:
X-MINIMUM-CLIENT-VERSION:
$ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
X-RateLimit-Remaining:
$ref: "#/components/headers/X-RateLimit-Remaining"
X-RateLimit-Limit:
$ref: "#/components/headers/X-RateLimit-Limit"
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/RecurringInvoice"
meta:
type: object
$ref: '#/components/schemas/Meta'
401:
$ref: "#/components/responses/401"
403:
$ref: "#/components/responses/403"
422:
$ref: '#/components/responses/422'
429:
$ref: '#/components/responses/429'
5XX:
description: 'Server error'
default:
$ref: "#/components/responses/default"
"/api/v1/recurring_invoices/{id}/{action}":
get:
deprecated: true
tags:
- Recurring Invoices
summary: "Custom recurring invoice action"
description: "Performs a custom action on an RecurringInvoice.\n\n The current range of actions are as follows\n - clone_to_RecurringInvoice\n - clone_to_quote\n - history\n - delivery_note\n - mark_paid\n - download\n - archive\n - delete\n - email"
operationId: actionRecurringInvoice
parameters:
- $ref: "#/components/parameters/X-API-TOKEN"
- $ref: "#/components/parameters/X-Requested-With"
- $ref: "#/components/parameters/include"
- name: id
in: path
description: "The RecurringInvoice Hashed ID"
required: true
schema:
type: string
format: string
example: D2J234DFA
- name: action
in: path
description: "The action string to be performed"
required: true
schema:
type: string
format: string
example: clone_to_quote
responses:
200:
description: "Returns the RecurringInvoice object"
headers:
X-MINIMUM-CLIENT-VERSION:
$ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
X-RateLimit-Remaining:
$ref: "#/components/headers/X-RateLimit-Remaining"
X-RateLimit-Limit:
$ref: "#/components/headers/X-RateLimit-Limit"
content:
application/json:
schema:
$ref: "#/components/schemas/RecurringInvoice"
401:
$ref: "#/components/responses/401"
403:
$ref: "#/components/responses/403"
422:
$ref: '#/components/responses/422'
429:
$ref: '#/components/responses/429'
5XX:
description: 'Server error'
default:
$ref: "#/components/responses/default"
"/api/v1/recurring_invoice/{invitation_key}/download":
get:
tags:
- Recurring Invoices
summary: "Download recurring invoice PDF"
description: "Downloads a specific invoice"
operationId: downloadRecurringInvoice
parameters:
- $ref: "#/components/parameters/X-API-TOKEN"
- $ref: "#/components/parameters/X-Requested-With"
- $ref: "#/components/parameters/include"
- name: invitation_key
in: path
description: "The Recurring Invoice Invitation Key"
required: true
schema:
type: string
format: string
example: D2J234DFA
responses:
200:
description: "Returns the recurring invoice pdf"
headers:
X-MINIMUM-CLIENT-VERSION:
$ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
X-RateLimit-Remaining:
$ref: "#/components/headers/X-RateLimit-Remaining"
X-RateLimit-Limit:
$ref: "#/components/headers/X-RateLimit-Limit"
401:
$ref: "#/components/responses/401"
403:
$ref: "#/components/responses/403"
422:
$ref: '#/components/responses/422'
429:
$ref: '#/components/responses/429'
5XX:
description: 'Server error'
default:
$ref: "#/components/responses/default"
"/api/v1/recurring_invoices/{id}/upload":
post:
tags:
- Recurring Invoices
summary: "Add recurring invoice document"
description: "Handles the uploading of a document to a recurring_invoice"
operationId: uploadRecurringInvoice
parameters:
- $ref: "#/components/parameters/X-API-TOKEN"
- $ref: "#/components/parameters/X-Requested-With"
- $ref: "#/components/parameters/include"
- name: id
in: path
description: "The RecurringInvoice Hashed ID"
required: true
schema:
type: string
format: string
example: D2J234DFA
requestBody:
description: "File Upload Body"
required: true
content:
multipart/form-data:
schema:
type: object
properties:
_method:
type: string
example: PUT
documents:
type: array
items:
description: "Array of binary documents for upload"
type: string
format: binary
responses:
200:
description: "Returns the RecurringInvoice object"
headers:
X-MINIMUM-CLIENT-VERSION:
$ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
X-RateLimit-Remaining:
$ref: "#/components/headers/X-RateLimit-Remaining"
X-RateLimit-Limit:
$ref: "#/components/headers/X-RateLimit-Limit"
content:
application/json:
schema:
$ref: "#/components/schemas/RecurringInvoice"
401:
$ref: "#/components/responses/401"
403:
$ref: "#/components/responses/403"
422:
$ref: '#/components/responses/422'
429:
$ref: '#/components/responses/429'
5XX:
description: 'Server error'
default:
$ref: "#/components/responses/default"