> ## Documentation Index > Fetch the complete documentation index at: https://docs.chift.eu/llms.txt > Use this file to discover all available pages before exploring further. # Create Journal Entry > Create a new Journal Entry in the accounting system ## OpenAPI ````yaml post /consumers/{consumer_id}/accounting/journal-entries openapi: 3.1.0 info: title: Chift API description: >- The Chift API is a universal API giving you access to financial data from the software of your clients. It helps software companies to offer native integrations to their clients without the effort needed to maintain those native integrations. By using the APIs (Accounting, POS, eCommerce) of Chift, you connect once and allow your clients to use their software packages. version: 1.0.0 servers: - url: https://api.chift.eu description: Chift security: - bearerAuth: [] paths: /consumers/{consumer_id}/accounting/journal-entries: post: tags: - Accounting - Journal entries summary: Create Journal Entry description: Create a new Journal Entry in the accounting system operationId: accounting_create_generic_journal_entry parameters: - name: consumer_id in: path required: true schema: type: string format: uuid title: Consumer Id - name: folder_id in: query required: false schema: anyOf: - type: string - type: 'null' title: Folder Id description: >- Id of the accounting folder instance. A folder represents a legal entity within the system. Required when the multiple folders feature is enabled. - name: force_currency_exchange in: query required: false schema: anyOf: - $ref: '#/components/schemas/BoolParam' - type: 'null' default: 'false' title: Force Currency Exchange description: >- Boolean flag indicating whether to force the use of the provided currency exchange rate instead of the rate used by the accounting software. - name: ignore_accounting_id in: query required: false schema: type: boolean default: false title: Ignore Accounting Id description: >- If set to true, Chift will not wait for the invoice to be processed to return, use this when you do not need the ID in the return value.Note that this might also change the output of the call. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GenericJournalEntry' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/JournalEntryMultiAnalyticPlan' '400': content: application/json: examples: Could not create entry (sage 100): value: message: >- The entry couldn't be created in the accounting system. The journal is already open via the Sage 100 interface. status: error Can not link entry to multiple partner: value: message: >- A sale/purchase entry cannot be linked to multiple partner accounts. status: error Unbalanced entry: value: message: The entry is not balanced. status: error schema: $ref: '#/components/schemas/ChiftError' description: Bad Request '404': content: application/json: examples: Unsupported journal: value: message: Only entries in a sale or purchase journal can be created. status: error Journal not found: value: message: The journal doesn't exist in the accounting system. status: error Account not found: value: message: The account number doesn't exist in the accounting system. status: error Partner not found: value: message: >- The client/supplier doesn't exist in the accounting system. status: error Currency not found: value: message: >- The currency doesn't exist or is not active in the accounting system. status: error schema: $ref: '#/components/schemas/ChiftError' description: Not Found '422': content: application/json: examples: Partner missing: value: message: >- Please provide a client/supplier account in the partner_id field. status: error Invalid supplier: value: message: The partner must be a supplier. status: error Invalid client: value: message: The partner must be a client/customer. status: error Missing collective account: value: message: Please provide a client/supplier collective account. status: error Missing product: value: message: Please provide at least one charge/product account. status: error Invalid currency format: value: message: >- The currency format is not correct. Please use the ISO 4217 codes. status: error Multi currency error: value: message: Only one currency can be used. status: error Invalid exchange rates: value: message: Exchange rates must be equal. status: error Debit/credit both negative: value: message: Debit and credit cannot be negative. status: error Debit/credit no positive: value: message: Debit or credit must be positive. status: error Debit/credit both positive: value: message: Debit and credit cannot be both positive. status: error schema: $ref: '#/components/schemas/ChiftError' description: Unprocessable Entity security: - mcp_auth: - accounting - accounting.journal_entries components: schemas: BoolParam: type: string enum: - 'true' - 'false' title: BoolParam GenericJournalEntry: properties: reference: anyOf: - type: string - type: 'null' title: Reference description: >- Optional reference field used to store an external or contextual identifier related to the entry. For example, it can be used to store a reference number, the invoice number issued by the suppllier or any other relevant information. due_date: anyOf: - type: string format: date - type: 'null' title: Due Date description: >- If the journal entry relates to an invoice, this is the due date for payment or settlement (format: YYYY-MM-DD). journal_id: type: string title: Journal Id description: >- Id of the journal instance in the accounting system in which the journal entry is recorded. number: type: string minLength: 1 title: Number description: >- Unique 'number' of the journal entry in the accounting software. This is an internal number or ID assigned to the journal entry, not necessarily the label or number visible on an invoice. It is recommended to use this number for idempotency to prevent duplicate entries. Refer to the idempotency documentation in the Developer Guides for more details. currency: type: string minLength: 1 title: Currency description: Indicates the currency of the journal entry (e.g., EUR, USD). currency_exchange_rate: anyOf: - type: number - type: 'null' title: Currency Exchange Rate description: >- Indicates the exchange rate at the date of the journal entry. Must be filled in when creating the entry in another currency from the folder's default currency. default: 1 date: type: string format: date title: Date description: >- Accounting date of the journal entry (format: YYYY-MM-DD). This is the date when the journal entry is recorded in the accounting system. items: items: $ref: '#/components/schemas/GenericJournalItem' type: array minItems: 2 title: Items description: >- List of journal items that make up the journal entry. Each item represents a line in the journal entry, and the sum of debits must equal the sum of credits to ensure the entry is balanced. There must always be at least 2 lines/items. pdf: anyOf: - type: string - type: 'null' title: Pdf description: Base 64 string representing the PDF attached to the item. pdf_name: anyOf: - type: string maxLength: 200 minLength: 1 pattern: ^[a-zA-Z0-9\-_ ]{1,196}(?:.pdf)?$ - type: 'null' title: Pdf Name description: >- A name for the PDF file to be created for accounting software that support it. posted: anyOf: - type: boolean - type: 'null' title: Posted description: >- Indicates if the journal entry has been posted (finalized) in the accounting system. If not provided, it defaults to True. default: true start_date: anyOf: - type: string format: date - type: 'null' title: Start Date description: >- Start date of the period covered by the journal entry (format: YYYY-MM-DD). This field should be used when the entry relates to prepaid income or expenses (accruals and deferrals), indicating when the covered period begins. end_date: anyOf: - type: string format: date - type: 'null' title: End Date description: >- End date of the period covered by the journal entry (format: YYYY-MM-DD). This field should be used when the entry relates to prepaid income or expenses (accruals and deferrals), indicating when the covered period ends. type: object required: - journal_id - number - currency - date - items title: GenericJournalEntry JournalEntryMultiAnalyticPlan: properties: reference: anyOf: - type: string - type: 'null' title: Reference description: >- Optional reference field used to store an external or contextual identifier related to the entry. For example, it can be used to store a reference number, the invoice number issued by the suppllier or any other relevant information. due_date: anyOf: - type: string format: date - type: 'null' title: Due Date description: >- If the journal entry relates to an invoice, this is the due date for payment or settlement (format: YYYY-MM-DD). journal_id: type: string title: Journal Id description: >- Id of the journal instance in the accounting system in which the journal entry is recorded. name: anyOf: - type: string - type: 'null' title: Name journal_name: anyOf: - type: string - type: 'null' title: Journal Name description: Name of the journal in which the journal entry is recorded. date: anyOf: - type: string format: date - type: 'null' title: Date description: >- Accounting date of the journal entry. It is automatically set to '1970-01-01' if the value is not available/empty in the accounting system. default: '1970-01-01' posted: anyOf: - type: boolean - type: 'null' title: Posted description: >- Indicates if the journal entry has been posted (finalized) in the accounting system. default: false id: type: string title: Id description: Unique id of the journal entry instance in the accounting system. due_dates: anyOf: - items: $ref: '#/components/schemas/JournalItemDueDatesOut' type: array - type: 'null' title: Due Dates description: List of all due dates of a journal entry. default: [] attachments_info: $ref: '#/components/schemas/ItemAttachmentInfoOut' description: >- Indicates whether a file attachment (e.g. PDF or image) is linked to this journal entry and how to retrieve it. Check the status field: 'yes' means a direct download URL is available in the attachments array; 'yes_to_request' means the file exists but must be fetched separately via GET /accounting/attachments?type=entry&document_id={id}, which returns the file as a base64-encoded string. 'no' means no attachment is linked. 'unknown' means the connector does not support this. items: anyOf: - items: $ref: '#/components/schemas/JournalItemMultiAnalyticPlan' type: array - type: 'null' title: Items description: >- List of journal items that make up the journal entry. Each item represents a line in the journal entry, and the sum of debits must equal the sum of credits to ensure the entry is balanced. default: [] type: object required: - journal_id - id title: JournalEntryMultiAnalyticPlan ChiftError: properties: message: type: string title: Message status: anyOf: - type: string - type: 'null' title: Status default: error detail: anyOf: - type: string - type: 'null' title: Detail default: '' type: object required: - message title: ChiftError GenericJournalItem: properties: account_type: $ref: '#/components/schemas/EntryLineType' description: >- account_type can be either general ('general_account') or thirdparty ('customer', 'supplier' or 'employee') account: anyOf: - type: string minLength: 1 - type: 'null' title: Account description: >- Depending on account_type, if the account_type is 'general_account', this is the general ledger account number used to book the journal item against. If the account_type is 'customer_account', 'supplier_account' or 'employee_account', this is the thirdparty_id (id of the customer, supplier or employee in the accounting system). force_general_account: anyOf: - type: string - type: 'null' title: Force General Account description: >- Overrides the default general account for customer, supplier, or employee accounts. If provided, this value will be used as the general account instead of the one determined by the accounting system's configuration. prioritise_thirdparty_account: anyOf: - type: boolean - type: 'null' title: Prioritise Thirdparty Account description: >- If True, prioritize using the third-party account information when a general account is forced in accounting software that only allows one account. Recommended to set it to True default: false description: anyOf: - type: string - type: 'null' title: Description description: >- Text description for this journal item. This is typically used to provide additional context or information. debit: type: number title: Debit description: Amount to debit on the account. Must be 0 if credit line is not 0 credit: type: number title: Credit description: Amount to credit on the account. Must be 0 if debit line is not 0 analytic_distribution: anyOf: - items: $ref: '#/components/schemas/AnalyticDistribution' type: array - type: 'null' title: Analytic Distribution description: >- List of analytic distributions for the journal item. Each distribution specifies an analytic plan and the allocation of the journal entry item's amount across analytic accounts using percentages. default: [] tax_code: anyOf: - type: string - type: 'null' title: Tax Code description: >- Indicates the Tax Code used for the entry item. This is the Id of the Tax Code instance in the accounting software. tax_info: anyOf: - $ref: '#/components/schemas/TaxInfo' - type: 'null' description: >- Tax information related to the journal item. The provided tax amount is added to the amount (debit or credit) of the journal item. This is only supported for general accounts. account_info: anyOf: - $ref: '#/components/schemas/AccountToCreate' - type: 'null' description: >- (For certain specific connectors only) Details of the account (third-party or general ledger) to be created if it does not already exist in the accounting system. Some softwares do not support creating accounts via API; in such cases, this information must be provided to allow the accounting software to automatically create the missing account (e.g., for Tiime). type: object required: - account_type - debit - credit title: GenericJournalItem JournalItemDueDatesOut: properties: due_date: type: string format: date title: Due Date description: Due date of the item. payment_method: anyOf: - type: string - type: 'null' title: Payment Method description: Payment method used to pay the entry on that due date. payment_method_id: anyOf: - type: string - type: 'null' title: Payment Method Id description: >- Technical ID of the payment method used to pay the entry on that due date. debit: anyOf: - type: number - type: 'null' title: Debit description: Debit of the item on this due date. default: 0 credit: anyOf: - type: number - type: 'null' title: Credit description: Credit of the item on this due date. default: 0 type: object required: - due_date title: JournalItemDueDatesOut ItemAttachmentInfoOut: properties: status: $ref: '#/components/schemas/ItemAttachmentInfoStatus' description: >- Indicates whether an attachment (e.g. PDF or image) is available for this entry, and how to retrieve it. 'yes': one or more attachments are available directly — each entry in the attachments array contains a filename and a download URL. 'yes_to_request': an attachment exists but cannot be returned inline. Call GET /accounting/attachments with type and document_id to retrieve the file as a base64-encoded string. The attachments array may be empty in this case. 'no': no attachment is linked to this entry. 'unknown': the connector does not support attachment detection for this provider. attachments: anyOf: - items: $ref: '#/components/schemas/ItemAttachmentInfoAttachment' type: array - type: 'null' title: Attachments description: >- List of attachments available directly for this entry. Populated only when status is 'yes'. When status is 'yes_to_request', this list is empty — use GET /accounting/attachments to fetch the file content. default: [] type: object required: - status title: ItemAttachmentInfoOut JournalItemMultiAnalyticPlan: properties: account_number: type: string minLength: 1 title: Account Number description: >- Depending on account_type, if the account_type is 'general_account', this is the general ledger account number used to book the journal item against. If the account_type is 'customer_account', 'supplier_account' or 'employee_account', this is the thirdparty_id (id of the customer, supplier or employee in the accounting system). partner_id: anyOf: - type: string - type: 'null' title: Partner Id description: >- Id of the thirdparty (customer, supplier or employee) in the accounting system if the journal item relates to a thirdparty (e.g., an invoice). description: anyOf: - type: string - type: 'null' title: Description description: >- Text description for this journal item. This is typically used to provide additional context or information. debit: type: number title: Debit description: Amount to debit on the account. Must be 0 if credit field is not 0 credit: type: number title: Credit description: Amount to credit on the account. Must be 0 if debit field is not 0 currency: type: string minLength: 1 title: Currency description: Currency code (e.g., USD, EUR) used for the journal item amounts. currency_exchange_rate: anyOf: - type: number - type: 'null' title: Currency Exchange Rate description: >- Exchange rate applicable at the date of the journal item. Required when currency is different from the folder's default currency. default: 1 id: type: string title: Id description: Unique id of the journal item instance in the accounting system. partner_name: anyOf: - type: string - type: 'null' title: Partner Name description: >- Name of the thirdparty (customer, supplier or employee) linked to the journal item if journal item relates to a thirdparty (e.g., an invoice). account_name: type: string title: Account Name description: >- Name or label of the ledger account used to book the journal item against. matching_numbers: anyOf: - items: type: string type: array - type: 'null' title: Matching Numbers description: >- List of matching numbers used to link this journal item to other entries in the accounting system. This is used for reconciliation/lettering purposes. default: [] analytic_distribution: anyOf: - items: $ref: '#/components/schemas/AnalyticDistribution' type: array - type: 'null' title: Analytic Distribution description: >- List of analytic distributions for the journal item. Each distribution specifies an analytic plan and the allocation of the journal entry item's amount across analytic accounts using percentages. default: [] type: object required: - account_number - debit - credit - currency - id - account_name title: JournalItemMultiAnalyticPlan EntryLineType: type: string enum: - customer_account - supplier_account - employee_account - general_account title: EntryLineType AnalyticDistribution: properties: analytic_plan: type: string title: Analytic Plan description: Id of the analytic plan to which the distribution applies. analytic_accounts: items: $ref: '#/components/schemas/AnalyticDistributionDetail' type: array title: Analytic Accounts description: >- List of analytic accounts and their respective percentages for the distribution. type: object required: - analytic_plan - analytic_accounts title: AnalyticDistribution TaxInfo: properties: tax_code: type: string title: Tax Code description: >- VAT code of the tax line. This is the Id of the Tax code instance in the accounting software. tax_amount: type: number title: Tax Amount description: >- Amount of the tax line. The amount must be positive and is required even with reversed VAT. vat_account: anyOf: - type: string - type: 'null' title: Vat Account description: >- VAT ledger account of the tax line. This is the ledger account number used to book the tax amount. The account is mandatory if tax amount is different from 0. The ledger account will ONLY be used when it is mandatory to pass this information to the accounting software. reversed_vat_account: anyOf: - type: string - type: 'null' title: Reversed Vat Account description: >- Reversed VAT ledger account of the tax line. This is the ledger account number used to book the reversed tax amount. The account is mandatory if you are using a reversed VAT code. The ledger account will ONLY be used when it is mandatory to pass this information to the accounting software. description: anyOf: - type: string - type: 'null' title: Description description: Optional extra description of the tax line. type: object required: - tax_code - tax_amount title: TaxInfo AccountToCreate: properties: account_number: type: string minLength: 1 title: Account Number account_name: type: string minLength: 1 title: Account Name type: object required: - account_number - account_name title: AccountToCreate ItemAttachmentInfoStatus: type: string enum: - unknown - 'yes' - yes_to_request - 'no' title: ItemAttachmentInfoStatus ItemAttachmentInfoAttachment: properties: filename: anyOf: - type: string - type: 'null' title: Filename description: The name of the attachment. url: anyOf: - type: string - type: 'null' title: Url description: >- Direct download URL for the attachment file. Only populated when the parent attachments_info.status is 'yes'. When status is 'yes_to_request', this field is null and the file must be retrieved via GET /accounting/attachments with the appropriate type and document_id, which returns the content as a base64-encoded string. type: object title: ItemAttachmentInfoAttachment AnalyticDistributionDetail: properties: analytic_account: type: string title: Analytic Account percentage: type: number title: Percentage description: >- Percentage of the untaxed amount attributed to this analytic account. Only whole numbers (no decimals) are allowed. The total across the analytic distribution (all accounts in a given analytic plan) must equal 100%. type: object required: - analytic_account - percentage title: AnalyticDistributionDetail securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- This access token needs to be included in each of your request to the Chift API. ````