---
updatedAt: 2026-07-08T07:28:10.000Z
agentTools:
projectIndex: https://pennylane.readme.io/llms.txt
---
# Create a ledger entry
Create a ledger entry
> ℹ️
> This endpoint requires the following scope: `ledger_entries:all`
###
This endpoint requires one of the following scopes: `ledger_entries:all`
# OpenAPI definition
```json
{
"openapi": "3.0.1",
"info": {
"title": "Company V2",
"description": "Automate your accounting with the Pennylane API. [Documentation](https://pennylane.readme.io/)",
"contact": {
"email": "tech@pennylane.com"
},
"version": "2.0"
},
"x-readme": {
"samples-languages": [
"curl",
"node",
"ruby",
"php",
"python",
"java"
]
},
"servers": [
{
"url": "https://app.pennylane.com"
}
],
"paths": {
"/api/external/v2/ledger_entries": {
"post": {
"operationId": "postLedgerEntries",
"summary": "Create a ledger entry",
"description": "Create a ledger entry\n\n\n> ℹ️\n> This endpoint requires the following scope: `ledger_entries:all`",
"tags": [
"Ledger Entries"
],
"security": [
{
"oauth2": [
"ledger_entries:all"
]
}
],
"parameters": [
{
"name": "X-Company-Id",
"description": "Numeric ID of the company to act on. Required when authenticating with a firm token. Ignored when the token is already bound to a company.",
"in": "header",
"schema": {
"type": "string",
"example": "12345"
},
"required": false
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"date": {
"description": "Date of the ledger entry (ISO 8601)",
"type": "string",
"format": "date",
"example": "2023-08-30"
},
"due_date": {
"description": "Due date of the ledger entry (ISO 8601)",
"type": "string",
"format": "date",
"nullable": true,
"example": "2023-09-30"
},
"label": {
"description": "Label that describes the ledger entry",
"type": "string",
"example": "Payment for Services"
},
"journal_id": {
"type": "integer",
"format": "int64",
"description": "The journal ID where you want to create the ledger entry",
"example": 123
},
"file_attachment_id": {
"type": "integer",
"format": "int64",
"description": "File attachment ID.\n\n> ⚠️ Passing this field will soon be deprecated. We will provide an alternative using `/api/external/v2/ledger_entries/{id}/dms_files`.\n",
"example": 42
},
"currency": {
"description": "Currency code of the ledger entry as per ISO 4217. If not provided, EUR will be used. This currency is applicable to all ledger_entry_lines",
"example": "EUR",
"type": "string",
"enum": [
"EUR",
"USD",
"GBP",
"AED",
"AFN",
"ALL",
"AMD",
"ANG",
"AOA",
"ARS",
"AUD",
"AWG",
"AZN",
"BAM",
"BBD",
"BDT",
"BGN",
"BHD",
"BIF",
"BMD",
"BND",
"BOB",
"BRL",
"BSD",
"BTN",
"BWP",
"BYN",
"BYR",
"BZD",
"CAD",
"CDF",
"CHE",
"CHF",
"CLF",
"CLP",
"CNY",
"COP",
"CRC",
"CUC",
"CUP",
"CVE",
"CZK",
"DJF",
"DKK",
"DOP",
"DZD",
"EGP",
"ERN",
"ETB",
"FJD",
"FKP",
"GEL",
"GGP",
"GHS",
"GIP",
"GMD",
"GNF",
"GTQ",
"GYD",
"HKD",
"HNL",
"HRK",
"HTG",
"HUF",
"IDR",
"ILS",
"IMP",
"INR",
"IQD",
"IRR",
"ISK",
"JEP",
"JMD",
"JOD",
"JPY",
"KES",
"KGS",
"KHR",
"KMF",
"KPW",
"KRW",
"KWD",
"KYD",
"KZT",
"LAK",
"LBP",
"LKR",
"LRD",
"LSL",
"LTL",
"LVL",
"LYD",
"MAD",
"MDL",
"MGA",
"MKD",
"MMK",
"MNT",
"MOP",
"MRO",
"MRU",
"MUR",
"MVR",
"MWK",
"MXN",
"MYR",
"MZN",
"NAD",
"NGN",
"NIO",
"NOK",
"NPR",
"NZD",
"OMR",
"PAB",
"PEN",
"PGK",
"PHP",
"PKR",
"PLN",
"PYG",
"QAR",
"RON",
"RSD",
"RUB",
"RWF",
"SAR",
"SBD",
"SCR",
"SDG",
"SEK",
"SGD",
"SHP",
"SLL",
"SLE",
"SOS",
"SRD",
"STD",
"SVC",
"SYP",
"SZL",
"THB",
"TJS",
"TMT",
"TND",
"TOP",
"TRY",
"TTD",
"TWD",
"TZS",
"UAH",
"UGX",
"UYU",
"UZS",
"VEF",
"VES",
"VND",
"VUV",
"WST",
"XAF",
"XCD",
"XDR",
"XOF",
"XPF",
"YER",
"ZAR",
"ZMK",
"ZMW",
"ZWL"
]
},
"piece_number": {
"description": "A piece number you can provide to track this ledger entry. If not provided, Pennylane will generate an identifier for you.",
"type": "string",
"example": "TENSNYLUGV"
},
"ledger_entry_lines": {
"description": "Array of ledger entry lines. The entry lines must be\nbalanced. The max number of ledger entry lines that you can create\nusing this endpoint is 1000 per request.\n\n> ⚠️ The order of `ledger_entry_lines` in the response is not guaranteed to match the order in which they were sent. To map source lines to their returned `ledger_entry_line.id`, match by content (e.g. `debit`, `credit`, `label`) rather than by position.\n",
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"debit": {
"allOf": [
{
"type": "string",
"pattern": "^(-?\\d+(\\.\\d+)?)?$",
"example": "100.00"
},
{
"description": "Debit amount for the entry line",
"example": "100.00"
}
]
},
"credit": {
"allOf": [
{
"type": "string",
"pattern": "^(-?\\d+(\\.\\d+)?)?$",
"example": "100.00"
},
{
"description": "Credit amount for the entry line",
"example": "0.00"
}
]
},
"ledger_account_id": {
"type": "integer",
"format": "int64",
"description": "Ledger account ID",
"example": 987
},
"label": {
"description": "Label that describes the entry line",
"type": "string",
"example": "Transaction label"
}
},
"required": [
"debit",
"credit",
"ledger_account_id"
]
},
"minItems": 1
}
},
"required": [
"date",
"label",
"journal_id",
"ledger_entry_lines"
]
}
}
}
},
"responses": {
"201": {
"description": "Returns the created ledger entry",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "ID of the ledger entry",
"example": 1
},
"label": {
"description": "Label that describes the ledger entry",
"type": "string",
"example": "Payment for Services"
},
"piece_number": {
"type": "string",
"nullable": true,
"example": "TENSNYLUGV"
},
"date": {
"description": "Date of the ledger entry (ISO 8601)",
"type": "string",
"format": "date",
"example": "2023-08-30"
},
"due_date": {
"description": "The date the invoice is due",
"type": "string",
"format": "date",
"nullable": true,
"example": "2023-08-30"
},
"invoice_number": {
"description": "Invoice number of the document linked to the ledger entry",
"type": "string",
"nullable": true,
"example": "FAC-2024-001"
},
"journal_id": {
"type": "integer",
"format": "int64",
"description": "This attribute is **deprecated**. Please use `journal` instead. The journal ID where the ledger entry was created",
"example": 123,
"deprecated": true
},
"journal": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "integer",
"format": "int64",
"example": 123
},
"url": {
"type": "string",
"example": "https://app.pennylane.com/api/external/v2/journals/123"
}
},
"required": [
"id",
"url"
]
},
"status": {
"description": "The accounting state of the entry.\n- `archived`: The entry has been archived.\n- `draft`: The customer invoice is still in draft and has not been finalized.\n- `entry`: The invoice is incomplete, some information is missing and needs to be completed.\n- `waiting_details`: The entry is awaiting additional accounting details.\n- `validation_needed`: The entry is sent to the accountant and needs validation.\n- `accounting_needed`: The entry needs to be processed by the accountant.\n- `complete`: The entry has been validated by the accountant.\n- `null` : The entry is neither a transaction nor an invoice that needs to be processed on Pennylane\n",
"type": "string",
"nullable": true,
"enum": [
"accounting_needed",
"archived",
"complete",
"draft",
"entry",
"validation_needed",
"waiting_details"
]
},
"categories": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "integer",
"format": "int64",
"example": 421
},
"label": {
"type": "string",
"example": "HR - Salaries"
},
"weight": {
"type": "string",
"example": "0.25"
},
"category_group": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "integer",
"format": "int64",
"example": 229
}
},
"required": [
"id"
]
},
"analytical_code": {
"type": "string",
"nullable": true,
"example": "CODE123"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2023-08-30T10:08:08.146343Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2023-08-30T10:08:08.146343Z"
}
},
"required": [
"id",
"label",
"weight",
"category_group",
"analytical_code",
"created_at",
"updated_at"
]
}
},
"ledger_attachment_filename": {
"description": "This attribute is deprecated. Please use `filename` from `attachment` instead.",
"type": "string",
"nullable": true,
"example": "filename.pdf",
"deprecated": true
},
"ledger_attachment_id": {
"type": "integer",
"format": "int64",
"description": "This attribute is deprecated. Ledger attachment ID",
"deprecated": true,
"nullable": true,
"example": 42
},
"attachment": {
"description": "The primary accounting file of this ledger entry.\nFor invoices and most document types this is auto-generated by Pennylane.\nFor miscellaneous entries (OD) it can be set via `file_attachment_id` on create/update, though that behavior will soon be deprecated.\nFiles attached through the Pennylane UI are exposed separately via `GET /api/external/v2/ledger_entries/{id}/dms_files`.\n",
"type": "object",
"nullable": true,
"additionalProperties": false,
"properties": {
"filename": {
"type": "string",
"example": "filename.pdf"
},
"url": {
"description": "URL to the uploaded file.",
"type": "string",
"example": "http://www.pennylane.com/rails/active_storage/blobs/redirect/eyJfc..==--26d6e7391dd728fae2cde59bd3fbe4dd11e20a95/filename.pdf"
}
},
"required": [
"filename",
"url"
]
},
"ledger_entry_lines": {
"description": "Array of entry lines",
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "ID of the entry line",
"example": 42
},
"debit": {
"description": "Debit amount for the entry line",
"type": "string",
"example": "100.00"
},
"credit": {
"description": "Credit amount for the entry line",
"type": "string",
"example": "0.00"
},
"ledger_account_id": {
"description": "This attribute is deprecated. Please use `id` from `ledger_account` instead.",
"deprecated": true,
"type": "integer",
"format": "int64",
"example": 987
},
"ledger_account": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "Ledger account ID",
"example": 987
},
"number": {
"description": "Ledger account number",
"type": "string",
"example": "411000"
},
"url": {
"description": "The URL to the ledger account",
"type": "string",
"example": "https://app.pennylane.com/api/external/v2/ledger_accounts/42"
}
},
"required": [
"id",
"number",
"url"
]
},
"label": {
"description": "Label that describes the entry line",
"type": "string",
"example": "Transaction label"
}
},
"required": [
"id",
"debit",
"credit",
"ledger_account_id",
"ledger_account",
"label"
]
}
}
},
"required": [
"id",
"label",
"piece_number",
"date",
"due_date",
"invoice_number",
"journal_id",
"journal",
"status",
"categories",
"ledger_attachment_filename",
"ledger_attachment_id",
"attachment",
"ledger_entry_lines"
]
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"additionalProperties": false,
"properties": {
"error": {
"type": "string"
},
"status": {
"type": "integer"
}
},
"required": [
"error",
"status"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"InvalidDateFormat",
"InvalidDateTimeFormat",
"InvalidEmailFormat",
"InvalidPattern",
"InvalidUUIDFormat",
"LessThanExclusiveMinimum",
"LessThanMinimum",
"LessThanMinItems",
"LessThanMinLength",
"MoreThanExclusiveMaximum",
"MoreThanMaximum",
"MoreThanMaxItems",
"MoreThanMaxLength",
"NotAMultipartFile",
"NotAnyOf",
"NotEnumInclude",
"NotExistContentTypeDefinition",
"NotExistDiscriminatorMappedSchema",
"NotExistDiscriminatorPropertyName",
"NotExistPropertyDefinition",
"NotExistRequiredKey",
"NotExistStatusCodeDefinition",
"NotNullError",
"NotOneOf",
"ValidateError"
]
}
},
"required": [
"message",
"code"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"message": {
"type": "string"
},
"field": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"InvalidDateFormat",
"InvalidDateTimeFormat",
"InvalidEmailFormat",
"InvalidPattern",
"InvalidUUIDFormat",
"LessThanExclusiveMinimum",
"LessThanMinimum",
"LessThanMinItems",
"LessThanMinLength",
"MoreThanExclusiveMaximum",
"MoreThanMaximum",
"MoreThanMaxItems",
"MoreThanMaxLength",
"NotAMultipartFile",
"NotAnyOf",
"NotEnumInclude",
"NotExistContentTypeDefinition",
"NotExistDiscriminatorMappedSchema",
"NotExistDiscriminatorPropertyName",
"NotExistPropertyDefinition",
"NotExistRequiredKey",
"NotExistStatusCodeDefinition",
"NotNullError",
"NotOneOf",
"ValidateError"
]
}
},
"required": [
"message",
"field",
"code"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"message": {
"type": "string"
},
"payload": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"InvalidDateFormat",
"InvalidDateTimeFormat",
"InvalidEmailFormat",
"InvalidPattern",
"InvalidUUIDFormat",
"LessThanExclusiveMinimum",
"LessThanMinimum",
"LessThanMinItems",
"LessThanMinLength",
"MoreThanExclusiveMaximum",
"MoreThanMaximum",
"MoreThanMaxItems",
"MoreThanMaxLength",
"NotAMultipartFile",
"NotAnyOf",
"NotEnumInclude",
"NotExistContentTypeDefinition",
"NotExistDiscriminatorMappedSchema",
"NotExistDiscriminatorPropertyName",
"NotExistPropertyDefinition",
"NotExistRequiredKey",
"NotExistStatusCodeDefinition",
"NotNullError",
"NotOneOf",
"ValidateError"
]
}
},
"required": [
"message",
"payload",
"code"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"message": {
"type": "string"
},
"field": {
"type": "string"
},
"payload": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"InvalidDateFormat",
"InvalidDateTimeFormat",
"InvalidEmailFormat",
"InvalidPattern",
"InvalidUUIDFormat",
"LessThanExclusiveMinimum",
"LessThanMinimum",
"LessThanMinItems",
"LessThanMinLength",
"MoreThanExclusiveMaximum",
"MoreThanMaximum",
"MoreThanMaxItems",
"MoreThanMaxLength",
"NotAMultipartFile",
"NotAnyOf",
"NotEnumInclude",
"NotExistContentTypeDefinition",
"NotExistDiscriminatorMappedSchema",
"NotExistDiscriminatorPropertyName",
"NotExistPropertyDefinition",
"NotExistRequiredKey",
"NotExistStatusCodeDefinition",
"NotNullError",
"NotOneOf",
"ValidateError"
]
}
},
"required": [
"message",
"field",
"payload",
"code"
]
}
]
}
}
}
},
"401": {
"description": "Access token is missing or invalid",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"error": {
"type": "string",
"example": "The access token is invalid"
},
"status": {
"type": "integer",
"example": 401
}
},
"required": [
"error",
"status"
]
}
}
}
},
"403": {
"description": "Access to this resource forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"error": {
"type": "string",
"example": "Access to this resource requires scope \"ledger\"."
},
"status": {
"type": "integer",
"example": 403
}
},
"required": [
"error",
"status"
]
}
}
}
},
"404": {
"description": "The resource was not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"error": {
"type": "string",
"example": "Not Found"
},
"status": {
"type": "integer",
"example": 404
}
},
"required": [
"error",
"status"
]
}
}
}
},
"422": {
"description": "Unprocessable content",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"error": {
"type": "string",
"example": "Entry lines are not balanced"
},
"status": {
"type": "integer",
"example": 422
}
},
"required": [
"error",
"status"
]
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"oauth2": {
"type": "oauth2",
"flows": {
"authorizationCode": {
"authorizationUrl": "https://app.pennylane.com/oauth/authorize",
"tokenUrl": "https://app.pennylane.com/oauth/oauth/token",
"refreshUrl": "https://app.pennylane.com/oauth/oauth/token",
"scopes": {
"ledger": "Grant create, update and read access to Ledger Entries and its related resources"
}
}
}
}
}
}
}
```