Update the balance of an offline or disconnected account

PATCH

/accounts/{account_id}/

curl --request PATCH \
  --url https://app.commitly.com/api/accounts/4003/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "balance": 7500 }'

• Production

Sets the current balance of an account that COMMITLY does not update from a bank: accounts with status OFFLINE or DISCONNECTED. Accounts linked to a bank connection are refused with 400.

• balance is the current balance of the account, as a JSON number or a numeric string with up to two decimal places (same format as when creating an offline account).
• COMMITLY calculates the balance history backwards from the current balance: current balance minus the transactions gives the balance on every earlier day.
• Creating transactions does not change the balance. Whenever you add transactions with POST /accounts/{account_id}/transactions/, send the new current balance with this request as well, otherwise the balance history is wrong.
• Company level only: update the accounts of each company with that company’s credentials.

Authorizations

• commitlyOAuth

Parameters

Path Parameters

account_id

required

integer

Bank account ID (id from GET /accounts/).

Example

4003

Request Body^required

Media typeapplication/json

object

balance

required

New current balance of the account, up to two decimal places.

number | string

Example

{
  "balance": 7500
}

Responses

200

Balance updated. The response contains the updated account.

Media typeapplication/json

object

id

integer

bank

Bank data embedded in an account.

object

open_banking_connection_id

integer | null

name

string

bic

string

transaction_count

integer

last_transaction

Present in GET /accounts/ only.

object

id

integer

account

Short form of a bank account, embedded in transactions.

object

id

integer

name

string

alias

string

bank

Bank name. Present in the create-transactions response only.

string

currency

Present in the create-transactions response only.

string

value_date

string format: date

amount

number

purpose

string

counterpart_name

string

currency

ISO 4217 currency code.

string

date_created

string format: date-time

date_updated

string format: date-time

name

string

alias

string

iban

string

type_name

Account type as supplied by the bank provider (free text, e.g. Checking). Empty for offline accounts.

string

balance

number

overdraft_limit

number | null

status

Account status. Only offline accounts accept transactions via POST /accounts/{account_id}/transactions/; accounts with status API or DISCONNECTED, and accounts linked to a bank connection, do not.

string

Allowed values: UPDATED UPDATED_FIXED DOWNLOAD_IN_PROGRESS DOWNLOAD_FAILED DEPRECATED DISCONNECTED API OFFLINE

last_successful_update

string | null format: date-time

last_update_attempt

string | null format: date-time

banking_api_account

integer | null

Example

{
  "id": 4003,
  "bank": {
    "open_banking_connection_id": null,
    "name": "ERP cash accounts",
    "bic": ""
  },
  "transaction_count": 214,
  "currency": "EUR",
  "date_created": "2024-02-01T09:12:44.120511Z",
  "date_updated": "2024-07-11T08:30:02.518734Z",
  "name": "Petty cash",
  "alias": "",
  "iban": "",
  "type_name": "",
  "balance": 7500,
  "overdraft_limit": null,
  "status": "OFFLINE",
  "last_successful_update": null,
  "last_update_attempt": null,
  "banking_api_account": null
}

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

404

The resource does not exist or is not accessible with these credentials.

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^generated

{
  "detail": "example",
  "code": "example"
}