Create an invoice

POST

/invoices/

curl --request POST \
  --url https://app.commitly.com/api/invoices/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "reference": "AR-007", "name": "Equipment", "notes": "Special equipment", "type": "RE", "date": "2022-04-16", "amount": 7450, "due_date": "2022-04-28", "paid_amount": 0, "category": 1002 }'

• Production

Creates an invoice (open item).

Required: reference (invoice number), name, amount, due_date.

If type is omitted, it is derived from the sign of amount: a positive amount creates a receivable (RE), any other amount a payable (PA).

If expected_date is omitted, COMMITLY sets the expected payment date to the due date, or to the current date if the due date lies in the past.

Authorizations

• commitlyOAuth

Request Body^required

Media typeapplication/json

object

reference

required

Invoice number.

string

name

required

string

amount

required

Decimal with at most 10 digits and 2 decimal places. A JSON number or a numeric string ("7450.00").

number | string

due_date

required

string format: date

date

Invoice date.

string format: date

notes

Description of the invoice.

string

type

RE receivable, PA payable. Optional on create: if omitted, a positive amount sets RE, any other amount PA.

string

Allowed values: RE PA

tags

Additional information for mapping rules, e.g. the category.

string

paid_amount

Decimal with at most 10 digits and 2 decimal places. A JSON number or a numeric string ("7450.00").

number | string

category

ID of a leaf category of the company (from GET /categories/).

integer

expected_date

Expected payment date, if different from the due date. If omitted, it is set to the due date, or to the current date if the due date lies in the past.

string format: date

Example

{
  "reference": "AR-007",
  "name": "Equipment",
  "notes": "Special equipment",
  "type": "RE",
  "date": "2022-04-16",
  "amount": 7450,
  "due_date": "2022-04-28",
  "paid_amount": 0,
  "category": 1002
}

Responses

201

Invoice created.

Media typeapplication/json

object

id

Internal invoice ID. Used in /invoices/{id}/ and as id selector.

integer

transactions

Bank transactions matched to the invoice.

Array<object>

A bank transaction matched to the invoice.

object

id

integer

account

Bank account of the transaction.

value_date

string

amount

number

purpose

string

counterpart_name

string

reporting_amount

number

paid_amount

number

amount_due

number

date_created

string format: date-time

date_updated

string format: date-time

name

string

notes

string

amount

Decimal with at most 10 digits and 2 decimal places.

number

type

RE receivable, PA payable. Optional on create: if omitted, a positive amount sets RE, any other amount PA.

string

Allowed values: RE PA

reference

Invoice number.

string

date

Invoice date.

string format: date

due_date

string format: date

expected_date

Expected payment date.

string format: date

source

Origin of the invoice, e.g. direct_api or Manually Added.

string

source_id

ID of the invoice in its source.

string

status

Code	Label
OD	Overdue
PL	Expected
OR	Lead/Order
PD	Paid
PP	Partially Paid
IN	Installments
HD	On Hold
PR	Promised
DP	In Dispute
CA	Cancelled
IP	In Progress

string

Allowed values: OD PL OR PD PP IN HD PR DP CA IP

status_label

Label of status, e.g. Expected.

string

is_archived

boolean

category

Category ID.

integer | null

comment_count

Present in list responses.

integer

Examples

ExampleInvoiceCreated

Invoice

{
  "id": 3102,
  "transactions": [],
  "paid_amount": 0,
  "amount_due": 7450,
  "date_created": "2022-04-16T09:53:03.919398Z",
  "date_updated": "2022-04-16T09:53:03.919422Z",
  "name": "Equipment",
  "notes": "Special equipment",
  "amount": 7450,
  "type": "RE",
  "reference": "AR-007",
  "date": "2022-04-16",
  "due_date": "2022-04-28",
  "source": "direct_api",
  "source_id": "00000000-0000-4000-8000-000000000002",
  "status": "PL",
  "status_label": "Expected",
  "is_archived": false,
  "category": 1002
}

400

Invalid request body or parameters. The body lists the errors per field; errors not tied to a field are listed under non_field_errors. For request bodies that are arrays, the body is a list with one error object per item. Messages are localized (see Accept-Language).

Media typeapplication/json

One of:

object

Validation errors. Each key is a field of the request body; its value is the list of messages for that field. Errors not tied to a field are listed under non_field_errors.

object

non_field_errors

Array<string>

key

additional properties

Array<string>

Array<object>

Array<object>

Validation errors. Each key is a field of the request body; its value is the list of messages for that field. Errors not tied to a field are listed under non_field_errors.

object

non_field_errors

Array<string>

key

additional properties

Array<string>

Example

{
  "settlement_date": [
    "This field is required."
  ]
}

401

The access token is invalid or has expired. Request a new token. The message is localized (see Accept-Language).

Media typeapplication/json

object

detail

required

Error message.

string

code

Present only if the company’s edition does not include the function; value billing_plan_permission_denied.

string

Example

{
  "detail": "Invalid token."
}

Headers

WWW-Authenticate

string

Authentication scheme, Bearer.

Example

Bearer

403

No access token was sent, or the credentials are not allowed to call this endpoint. If the company’s COMMITLY edition does not include the requested function, the body additionally contains "code": "billing_plan_permission_denied".

Media typeapplication/json

object

detail

required

Error message.

string

code

Present only if the company’s edition does not include the function; value billing_plan_permission_denied.

string

Example

{
  "detail": "User must be authenticated to access this resource."
}