Skip to content
COMMITLYCOMMITLYCOMMITLY Developers

Create transactions in an account

POST
/accounts/{account_id}/transactions/
curl --request POST \
  --url https://app.commitly.com/api/accounts/4003/transactions/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '[ { "counterpart_name": "Example Provider GmbH", "purpose": "Transaction created via API", "value_date": "2024-07-11", "amount": -12500.01, "tags": [ "my-integration" ] } ]'

Creates one or more transactions in the given bank account. The body is a single transaction object or an array of up to 1000 transactions.

  • Required: value_date (on or after 2000-01-01) and amount.
  • Optional: purpose, counterpart_name, tags.
  • category cannot be set on create; COMMITLY assigns a default category. Change it afterwards with PATCH /transactions/ or PATCH /transactions/{id}/.

Only offline accounts accept new transactions. Accounts linked to a bank connection and accounts with status API or DISCONNECTED are refused with 403.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
account_id
required
integer

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

Example
4003

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
One of:
object
value_date
required

Value date, on or after 2000-01-01.

string format: date
amount
required

Negative for outflows, positive for inflows. A JSON number or a numeric string.

number | string
purpose
string
counterpart_name
string
tags
Array<string>
Example
[
  {
    "counterpart_name": "Example Provider GmbH",
    "purpose": "Transaction created via API",
    "value_date": "2024-07-11",
    "amount": -12500.01,
    "tags": [
      "my-integration"
    ]
  }
]

Responses

Section titled “Responses”

201

Section titled “201”

Transactions created. The response contains the created transaction, or a list of the created transactions if a list was sent.

Media typeapplication/json
One of:
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
category
One of:

Short form of a category, embedded in transactions and budgets.

object
id
integer
name
string
description
string
predicted_category
One of:

Extended category representation, embedded as predicted_category in transactions.

object
id
integer
name
string
slug
string
description
string
type

AG aggregating, EX expenses, IN incomes.

string
Allowed values: AG EX IN
order

Display position.

integer
date_created
string format: date-time
is_default
boolean
is_obsolete
boolean
lft

Internal; can be ignored.

integer
rght

Internal; can be ignored.

integer
tree_id

Internal; can be ignored.

integer
level

Internal; can be ignored.

integer
tenant
integer
company
integer
parent

ID of the parent category.

integer | null
source
integer | null
invoice

Invoice linked to the transaction, or null.

parent
One of:
object recursive
value_date

Value date (YYYY-MM-DD).

string format: date
value_time

Value time (HH:MM:SS), or null. Most banks supply only the date of a transaction, not the time, so expect null in most cases and do not rely on this field for ordering within a day.

string | null
/^\d{2}:\d{2}:\d{2}$/
bank_booking_date

Booking date as reported by the bank (YYYY-MM-DD), or null.

string | null format: date
amount

Negative for outflows, positive for inflows. In the currency of the account.

number
reporting_amount

amount converted to the company currency. Equal to amount for accounts in the company currency.

number
purpose
string
counterpart_name
string
counterpart_iban
string
is_adjusting_entry
boolean
is_payment
boolean
is_leaf_node
boolean
tags
Array<string> | null
comment_count

Present in list responses.

integer
Example
[
  {
    "id": 8001,
    "account": {
      "id": 4003,
      "bank": "Offline",
      "name": "API account",
      "alias": "",
      "currency": "EUR"
    },
    "category": {
      "id": 1004,
      "name": "Uncategorized outflows",
      "description": ""
    },
    "predicted_category": null,
    "invoice": null,
    "parent": null,
    "value_date": "2024-07-11",
    "value_time": null,
    "bank_booking_date": null,
    "amount": -12500.01,
    "reporting_amount": -12500.01,
    "purpose": "Transaction created via API",
    "counterpart_name": "Example Provider GmbH",
    "counterpart_iban": "",
    "is_adjusting_entry": false,
    "is_payment": true,
    "is_leaf_node": true,
    "tags": [
      "my-integration"
    ]
  }
]

400

Section titled “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:

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

Section titled “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

Section titled “Headers”
WWW-Authenticate
string

Authentication scheme, Bearer.

Example
Bearer

403

Section titled “403”

No access token, or the account does not accept new transactions (linked to a bank connection, or status API or DISCONNECTED).

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
Examplegenerated
{
  "detail": "example",
  "code": "example"
}

404

Section titled “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
Examplegenerated
{
  "detail": "example",
  "code": "example"
}