Update invoices

PATCH

/invoices/

const url = 'https://app.commitly.com/api/invoices/';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '[{"reference":"AR-007","amount":3000},{"reference":"AR-008","status":"PD","paid_amount":500}]'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PATCH \
  --url https://app.commitly.com/api/invoices/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '[ { "reference": "AR-007", "amount": 3000 }, { "reference": "AR-008", "status": "PD", "paid_amount": 500 } ]'

Updates one or more invoices. The body must be a JSON array; a single object is rejected with 400.

Matching key. The key used to find the invoices is chosen from the first item of the array, and applies to all items:

id (internal invoice ID), if the first item contains id;
otherwise source_id together with source, if the first item contains source_id;
otherwise reference.

Send the same key in every item.

Behaviour.

Only the fields sent are changed. name is not required.
Items that match no invoice are skipped silently. The response contains only the invoices that were updated.
PATCH never creates an invoice.
category must be a leaf category of the company. tags and expected_date can be updated.
An expected_date in the past is set to the current date, unless the invoice status is PD (paid).

Authorizations

commitlyOAuth

Request Body^required

application/json

Array<object>

One item of a PATCH body. Identify the invoice by id, by source_id together with source, or by reference; the key is chosen from the first item of the array (see the operation). All other fields are optional; only the fields sent are changed.

object

Internal invoice ID (matching key).

integer

source_id

ID of the invoice in its source (matching key, together with source).

string

source

Source of the invoice (matching key, together with source_id).

string

reference

Invoice number (matching key, exact match).

string

name

string

notes

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

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

date

string format: date

amount

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

number | string

due_date

string format: date

expected_date

A date in the past is set to the current date, unless the status is PD.

string format: date

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.

integer

tags

Additional information for mapping rules.

string

Example

[
  {
    "reference": "AR-007",
    "amount": 3000
  },
  {
    "reference": "AR-008",
    "status": "PD",
    "paid_amount": 500
  }
]

Responses

200

The invoices that were updated.

application/json

Array<object>

object

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

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

InvoicesUpdated

Updated invoices (list)

[
  {
    "id": 3102,
    "transactions": [],
    "paid_amount": 0,
    "amount_due": 3000,
    "date_created": "2022-04-16T09:53:03.919398Z",
    "date_updated": "2022-04-16T10:02:11.000000Z",
    "name": "Equipment",
    "notes": "Special equipment",
    "amount": 3000,
    "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).

application/json

One of:

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>

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).

application/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".

application/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."
}

Update invoices

Authorizations

Request Bodyrequired

Example

Responses

200

Examples

400

Example

401

Example

Headers

Example

403

Example

Request Body^required