openapi: 3.2.0
info:
title: Cobot Invoice API
termsOfService: https://www.cobot.me/terms
x-logo:
url: /api2_logo.webp
backgroundColor: '#FFFFFF'
altText: Cobot logo
description: "This is the 2.0 version of the Cobot API. You can find version 1.0\nas well as various tutorials under [/api-docs](/api-docs).\n\n## JSON API\n\nThis API follows the [JSON API](http://jsonapi.org) standard. This means:\n\n* requests and responses are sent in JSON\n* all requests MUST send a `Accept: application/vnd.api+json` header\n* non-GET requests MUST send a `Content-Type: application/vnd.api+json` header\n* all responses send a `Content-Type: application/vnd.api+json` header\n* all JSON formats are standardized (requests, responses, errors)\n\n## Cross-Origin Resource Sharing (CORS)\n\nAll endpoints send [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)\nheaders so that the API can be used from within browsers.\n\n## Rate Limiting\n\nIn general, the rate limit for an endpoint is 60 requests per minute per user.\nIf applicable, alternative limits are given in the documentation for\nparticular endpoints.\n\nIf you've exceeded the limit, Cobot will return a 429 status code and a JSON\nerror message. The response will also contain a *Retry-After* header, this\ndenotes the number of seconds to wait before your client may retry.\n\n## Times and Dates\n\nTimes and Dates must be in ISO 8601 formats. e.g. date: `2021-01-07`, datetime: `2021-01-07T16:25:51Z`, time: `16:25:51`.\nMillisecond are ommited, so `16:25:51.811` will become `16:25:51`.\nTime zone offsets must be provided by the client, e.g. `16:25:51+02:00` or '16:25:51Z' for UTC.\n\nTimes are always returned in UTC.\n## Sparse Fieldsets\n\nThis API supports [sparse fieldsets](https://jsonapi.org/format/#fetching-sparse-fieldsets),\nso clients can request which attributes they are interested in.\n\nExample:\n```\nGET https://api.cobot.me/user?fields[users]=email\n```\nThis will only return the user's email.\n\n## Query params\n\nWhen passing query params, arrays of data are expected to be sent as a string of comma separated values.\n\n## Pagination\n\nAll collections are paginated. Pagination follows [JSON-API standards](https://jsonapi.org/format/#fetching-pagination).\n\nExample:\n```json\n{\n \"meta\": {\n \"totalPages\": 2,\n \"currentPage\": 1\n },\n \"data\": [{\n \"id\": \"1\",\n \"type\": \"users\",\n }],\n \"links\": {\n \"self\": \"/users?page[size]=100&page[number]=1\",\n \"first\": \"/users?page[size]=100&page[number]=1\",\n \"prev\": null,\n \"next\": \"/users?page[size]=100&page[number]=2\",\n \"last\": \"/users?page[size]=100&page[number]=1\"\n }\n}\n```\n\nDefault page size is 72 and can be changed by passing a `page[size]` parameter. Maximum page size is 200.\n\n## Errors\n\nWhen a client sends invalid data in a request, Cobot returns a\n422 status code and a JSON-API error response.\n\nExample:\n```json\n{\n \"errors\": [\n {\n \"source\": {\n \"pointer\": \"/data/attributes/name\"\n },\n \"detail\": \"can't be blank\"\n },\n {\n \"source\": {\n \"pointer\": \"/data/attributes/password\"\n },\n \"detail\": \"is too short\"\n }\n ]\n}\n```\n"
version: '2.0'
contact:
name: Cobot Support
url: https://dev.cobot.me/
email: support@cobot.me
servers:
- url: https://api.cobot.me
security:
- OAuth2: []
tags:
- name: Invoice
description: Invoices are automatically generated once a month, based on members' activity. In addition, manual invoices can be generated at any time.
paths:
/invoice_charges:
post:
summary: Charge invoices
description: 'Bulk-charge invoices. The invoices will be charged in the background.
**Access**: The current user must be an admin of the space of each invoice.
'
operationId: create-invoice-charges
security:
- OAuth2:
- write_invoices
tags:
- Invoice
requestBody:
description: Invoices to be charged.
required: true
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/create-invoice-charges'
examples:
default:
value:
data:
type: invoiceCharges
relationships:
invoices:
data:
- id: 411f2702c500049ef4dc94229517631b
type: invoices
- id: 511f2702c500049ef4dc94229517631c
type: invoices
responses:
'202':
description: Invoice charges scheduled.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/invoice-charges'
examples:
default:
value:
data:
id: 123e4567-e89b-12d3-a456-426614174000
type: invoiceCharges
relationships:
invoices:
data:
- id: 411f2702c500049ef4dc94229517631b
type: invoices
- id: 511f2702c500049ef4dc94229517631c
type: invoices
/invoices:
post:
summary: Create custom
description: 'Create a custom invoice in a space.
Pass a *membership* relationship to assign the invoice to a membership.
Pass a *correctedInvoice* relationship and optional *writeOffCorrectedInvoice* flag to create a correction invoice.
**Access**: The current user must be an admin of the space where the invoice is created.
'
operationId: post-invoices
security:
- OAuth2:
- write_invoices
tags:
- Invoice
requestBody:
description: Data required to create an invoice.
required: true
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/create-custom-invoice'
examples:
default:
value:
data:
type: invoices
attributes:
invoiceText: Thanks for your business!
invoiceDate: '2019-01-10'
notes: Thanks for your business!
items:
- description: 2h meeting room
quantity: '2.0'
accountingCode: MTR-200
costCenter:
name: Bookings
number: MTR-200
revenueAccount:
name: Bookings
number: '4000'
amount:
net: '20.0'
taxes:
- name: VAT
rate: '19.0'
relationships:
debitor:
data:
id: 32c76cb66b5e6b39007690854fd668a1
type: memberships
correctedInvoice:
data:
id: 12376af66b5e6b39007690854fd668f4
type: invoices
space:
data:
id: 12376af66b5e6b39007690854fd668f4
type: spaces
responses:
'201':
description: 'Creates and returns a custom invoice, meaning the line items are
not based on any previous actions in Cobot, but are passed in.
'
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/invoice'
examples:
default:
value:
data:
id: 14c12f62ac8df98d29de357180d673e1
type: invoices
attributes:
invoiceText: Thanks for your business!
invoiceDate: '2019-01-10'
paidDate: null
dueDate: '2019-01-10'
eInvoicingReady: false
remindAt: '2019-01-17'
number: CW-2019-100
senderTaxId: DE753207
taxId: DE12345
taxIdName: UID
customerNumber: '100'
pdf:
archived: false
eInvoiceStandard: null
eInvoice: false
url: https://api.cobot.me/invoices/14c12f62ac8df98d29de357180d673e1.pdf?token=34976
recipientAddress:
name: Jane Smith
company: Acme Inc.
fullAddress: 2 Coworking Road, Big City 88888, Coworking State
street: 2 Coworking Road
postCode: '88888'
city: Big City
state: Coworking State
countryCode: US
senderAddress:
name: null
company: Coworking Ltd.
fullAddress: 1 Coworking Road, Big City 88888, Coworking State
street: 1 Coworking Road
postCode: '88888'
city: Big City
state: Coworking State
countryCode: US
notes: Customer will pay later.
billingEmails:
- mupi@lubbuw.bh
items:
- description: 2h meeting room
quantity: '2.0'
accountingCode: MTR-200
costCenter:
name: Bookings
number: MTR-200
revenueAccount:
name: Bookings
number: '4000'
paid: false
amount:
net: '20.0'
gross: '22.0'
currency: EUR
taxes:
- name: VAT
rate: '10.0'
amount: '2.0'
totalAmount:
net: '40.0'
gross: '44.0'
currency: EUR
taxes:
- name: VAT
rate: '10.0'
amount: '4.0'
payableAmount: '44.0'
paidAmount: '0.0'
paidStatus: unpaid
reminderStatus: sent
sentRemindersCount: 1
lastReminderSentAt: '2019-01-17T00:00:00Z'
chargeAt: '2019-01-02T11:00:00Z'
canCharge: true
canUpdate: true
sentStatus: unsent
totalAmount:
net: '40.0'
gross: '44.0'
currency: EUR
taxes:
- name: VAT
rate: '10.0'
amount: '4.0'
relationships:
debitor:
data:
id: c9a99a71ac8df98d29de357180d273d3
type: memberships
space:
data:
id: e0c19a71ac8df98d29de357180d27339
type: spaces
paymentMethods:
links:
related: https://api.cobot.me/api/invoices/14c12f62ac8df98d29de357180d673e1/payment_methods
'422':
description: 'Creating the invoice failed because of missing/invalid data.
'
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/failure'
examples:
default:
value:
errors:
- source:
pointer: /data/attributes/items
detail: can't be empty
/invoices/{id}:
get:
summary: Single invoice
description: 'Show a single invoice.
**Access**: The current user must be an admin of the space where
the invoice was created, and admin of any space in the network,
or the user of the membership the invoice belongs to.
'
operationId: get-invoice
parameters:
- name: id
in: path
required: true
description: The id of the invoice.
schema:
type: string
security:
- OAuth2:
- read_invoices
tags:
- Invoice
responses:
'200':
description: Details of an invoice.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/invoice'
examples:
default:
value:
data:
id: 14c12f62ac8df98d29de357180d673e1
type: invoices
attributes:
invoiceText: Thanks for your business!
invoiceDate: '2019-01-10'
paidDate: null
dueDate: '2019-01-10'
eInvoicingReady: false
remindAt: '2019-01-17'
number: CW-2019-100
senderTaxId: DE753207
taxId: DE12345
taxIdName: UID
customerNumber: '100'
pdf:
archived: false
eInvoiceStandard: null
eInvoice: false
url: https://api.cobot.me/invoices/14c12f62ac8df98d29de357180d673e1.pdf?token=34976
recipientAddress:
name: Jane Smith
company: Acme Inc.
fullAddress: 2 Coworking Road, Big City 88888, Coworking State
street: 2 Coworking Road
postCode: '88888'
city: Big City
state: Coworking State
countryCode: US
senderAddress:
name: null
company: Coworking Ltd.
fullAddress: 1 Coworking Road, Big City 88888, Coworking State
street: 1 Coworking Road
postCode: '88888'
city: Big City
state: Coworking State
countryCode: US
notes: Customer will pay later.
billingEmails:
- mupi@lubbuw.bh
items:
- description: 2h meeting room
quantity: '2.0'
accountingCode: MTR-200
costCenter:
name: Bookings
number: MTR-200
revenueAccount:
name: Bookings
number: '4000'
paid: false
amount:
net: '20.0'
gross: '22.0'
currency: EUR
taxes:
- name: VAT
rate: '10.0'
amount: '2.0'
totalAmount:
net: '40.0'
gross: '44.0'
currency: EUR
taxes:
- name: VAT
rate: '10.0'
amount: '4.0'
payableAmount: '44.0'
paidAmount: '0.0'
paidStatus: unpaid
reminderStatus: sent
sentRemindersCount: 1
lastReminderSentAt: '2019-01-17T00:00:00Z'
chargeAt: '2019-01-02T11:00:00Z'
canCharge: true
canUpdate: true
sentStatus: unsent
totalAmount:
net: '40.0'
gross: '44.0'
currency: EUR
taxes:
- name: VAT
rate: '10.0'
amount: '4.0'
relationships:
debitor:
data:
id: c9a99a71ac8df98d29de357180d273d3
type: memberships
space:
data:
id: e0c19a71ac8df98d29de357180d27339
type: spaces
paymentMethods:
links:
related: https://api.cobot.me/api/invoices/14c12f62ac8df98d29de357180d673e1/payment_methods
/invoices/{id}.pdf:
get:
summary: Single invoice PDF
description: 'Show a single invoice PDF.
**Access**: The current user must be an admin of the space where
the invoice was created, and admin of any space in the network,
or the user of the membership the invoice belongs to.
Alternatively, a token parameter can be provided to acces the PDF.
'
operationId: get-invoice-pdf
parameters:
- name: id
in: path
required: true
description: The id of the invoice.
schema:
type: string
- name: token
in: query
required: false
description: Optional token to access the PDF without API authentication.
schema:
type: string
- name: e_invoice
in: query
required: false
description: If set to true, returns the PDF without any payment related information.
schema:
type: boolean
security:
- OAuth2:
- read_invoices
tags:
- Invoice
responses:
'200':
description: An invoice's PDF.
/invoices/{id}/lock:
post:
summary: Lock invoice
description: 'Locks an invoice so it can not be edited anymore.
**Access**: The current user must be an admin of the space where
the invoice was created.
'
operationId: lock-invoice
parameters:
- name: id
in: path
required: true
description: The id of the invoice.
schema:
type: string
security:
- OAuth2:
- write_invoices
tags:
- Invoice
responses:
'200':
description: The locked invoice. `canUpdate` will be false.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/invoice'
examples:
default:
value:
data:
id: 14c12f62ac8df98d29de357180d673e1
type: invoices
attributes:
invoiceText: Thanks for your business!
invoiceDate: '2019-01-10'
paidDate: null
dueDate: '2019-01-10'
eInvoicingReady: false
remindAt: '2019-01-17'
number: CW-2019-100
senderTaxId: DE753207
taxId: DE12345
taxIdName: UID
customerNumber: '100'
pdf:
archived: false
eInvoiceStandard: null
eInvoice: false
url: https://api.cobot.me/invoices/14c12f62ac8df98d29de357180d673e1.pdf?token=34976
recipientAddress:
name: Jane Smith
company: Acme Inc.
fullAddress: 2 Coworking Road, Big City 88888, Coworking State
street: 2 Coworking Road
postCode: '88888'
city: Big City
state: Coworking State
countryCode: US
senderAddress:
name: null
company: Coworking Ltd.
fullAddress: 1 Coworking Road, Big City 88888, Coworking State
street: 1 Coworking Road
postCode: '88888'
city: Big City
state: Coworking State
countryCode: US
notes: Customer will pay later.
billingEmails:
- mupi@lubbuw.bh
items:
- description: 2h meeting room
quantity: '2.0'
accountingCode: MTR-200
costCenter:
name: Bookings
number: MTR-200
revenueAccount:
name: Bookings
number: '4000'
paid: false
amount:
net: '20.0'
gross: '22.0'
currency: EUR
taxes:
- name: VAT
rate: '10.0'
amount: '2.0'
totalAmount:
net: '40.0'
gross: '44.0'
currency: EUR
taxes:
- name: VAT
rate: '10.0'
amount: '4.0'
payableAmount: '44.0'
paidAmount: '0.0'
paidStatus: unpaid
reminderStatus: sent
sentRemindersCount: 1
lastReminderSentAt: '2019-01-17T00:00:00Z'
chargeAt: '2019-01-02T11:00:00Z'
canCharge: true
canUpdate: false
sentStatus: unsent
totalAmount:
net: '40.0'
gross: '44.0'
currency: EUR
taxes:
- name: VAT
rate: '10.0'
amount: '4.0'
relationships:
debitor:
data:
id: c9a99a71ac8df98d29de357180d273d3
type: memberships
space:
data:
id: e0c19a71ac8df98d29de357180d27339
type: spaces
paymentMethods:
links:
related: https://api.cobot.me/api/invoices/14c12f62ac8df98d29de357180d673e1/payment_methods
delete:
summary: Remove invoice lock
description: 'Removes the invoice lock so the invoice can be edited again (for example after external
e-invoice generation failed). This is not allowed if the invoice already has a final PDF
or e-invoicing data attached; in that case the request fails with
HTTP 409.
**Access**: The current user must be an admin of the space where
the invoice was created.
'
operationId: unlock-invoice
parameters:
- name: id
in: path
required: true
description: The id of the invoice.
schema:
type: string
security:
- OAuth2:
- write_invoices
tags:
- Invoice
responses:
'200':
description: The invoice after removing the lock.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/invoice'
examples:
default:
value:
data:
id: 14c12f62ac8df98d29de357180d673e1
type: invoices
attributes:
invoiceText: Thanks for your business!
invoiceDate: '2019-01-10'
paidDate: null
dueDate: '2019-01-10'
eInvoicingReady: false
remindAt: '2019-01-17'
number: CW-2019-100
senderTaxId: DE753207
taxId: DE12345
taxIdName: UID
customerNumber: '100'
pdf:
archived: false
eInvoiceStandard: null
eInvoice: false
url: https://api.cobot.me/invoices/14c12f62ac8df98d29de357180d673e1.pdf?token=34976
recipientAddress:
name: Jane Smith
company: Acme Inc.
fullAddress: 2 Coworking Road, Big City 88888, Coworking State
street: 2 Coworking Road
postCode: '88888'
city: Big City
state: Coworking State
countryCode: US
senderAddress:
name: null
company: Coworking Ltd.
fullAddress: 1 Coworking Road, Big City 88888, Coworking State
street: 1 Coworking Road
postCode: '88888'
city: Big City
state: Coworking State
countryCode: US
notes: Customer will pay later.
billingEmails:
- mupi@lubbuw.bh
items:
- description: 2h meeting room
quantity: '2.0'
accountingCode: MTR-200
costCenter:
name: Bookings
number: MTR-200
revenueAccount:
name: Bookings
number: '4000'
paid: false
amount:
net: '20.0'
gross: '22.0'
currency: EUR
taxes:
- name: VAT
rate: '10.0'
amount: '2.0'
totalAmount:
net: '40.0'
gross: '44.0'
currency: EUR
taxes:
- name: VAT
rate: '10.0'
amount: '4.0'
payableAmount: '44.0'
paidAmount: '0.0'
paidStatus: unpaid
reminderStatus: sent
sentRemindersCount: 1
lastReminderSentAt: '2019-01-17T00:00:00Z'
chargeAt: '2019-01-02T11:00:00Z'
canCharge: true
canUpdate: true
sentStatus: unsent
totalAmount:
net: '40.0'
gross: '44.0'
currency: EUR
taxes:
- name: VAT
rate: '10.0'
amount: '4.0'
relationships:
debitor:
data:
id: c9a99a71ac8df98d29de357180d273d3
type: memberships
space:
data:
id: e0c19a71ac8df98d29de357180d27339
type: spaces
paymentMethods:
links:
related: https://api.cobot.me/api/invoices/14c12f62ac8df98d29de357180d673e1/payment_methods
'409':
description: The invoice has an e-invoice or final PDF attached and cannot be unlocked.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/failure'
examples:
e_invoice_attached:
value:
errors:
- detail: This invoice has an e-invoice or final PDF attached and cannot be unlocked.
/invoices/{id}/e_invoice:
post:
summary: Create an e-invoice for invoice
description: 'Create an e-invoice for the passed invoice and attach it to the PDF.
This will lock the invoice, preventing it from being changed manually afterwards.
If generation fails before a PDF is attached, call `DELETE /invoices/{id}/lock` so the invoice can be edited again.
After an e-invoice or final PDF is attached, `DELETE /invoices/{id}/lock` returns HTTP 409 and does not unlock.
Supports e-invoicing in Germany (ZUGFeRD) and Poland (KSeF).
For Polish KSeF e-invoices, pass `e_invoice_standard: "KSeF"` along with
`ksef_reference_number` and `ksef_acceptance_timestamp` in the request body.
These will be stored on the invoice and the reference number will be displayed
on the PDF.
**Access**: The current user must be an admin of the space where
the invoice was created.
'
operationId: create-e-invoice
parameters:
- name: id
in: path
required: true
description: The id of the invoice.
schema:
type: string
security:
- OAuth2:
- write_invoices
tags:
- Invoice
requestBody:
description: Optional e-invoicing metadata (required for Polish KSeF).
required: false
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/create_e_invoice'
examples:
ksef:
summary: Polish KSeF e-invoice
value:
data:
type: invoices
attributes:
e_invoice_standard: KSeF
ksef_reference_number: 1234567890-20260126-ABC123DEF456-00
ksef_acceptance_timestamp: '2026-01-26T10:30:00Z'
responses:
'200':
description: The invoice.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/invoice'
examples:
defau
# --- truncated at 32 KB (103 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cobot/refs/heads/main/openapi/cobot-invoice-api-openapi.yml