Create a credit card entry

Operation ID: createCreditCardEntry

Group: Banking › Credit Card Entries

POST /banking/credit-card-entries

Retry-safe: A write that accepts Idempotency-Key: repeating a request with the same key replays the stored answer instead of executing twice.

Creates a credit card entry with its lines. If the accounting period that contains transactionDate is closed or locked in every full accounting book of the legal entity, the entry goes into the next period that is open in all of them, up to 11 periods later. If none of those periods is open in every book, or a period is open in some books and closed in others, the request fails with POSTING_PERIOD_NOT_OPEN.

The response contains only the new entry's id. Read the record with GET banking/credit-card-entries/:id.

Parameters

Name	In	Type	Required	Description
`Api-Version`	header	string · v1	yes	The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version `v1`.
`Idempotency-Key`	header	string	no	An opaque caller-chosen string (1-255 characters) that makes this request safe to retry. Repeating the same key with an identical request body replays the original response instead of re-executing - but only once that original request succeeded; a failed attempt re-executes on retry. Repeating the key with a different body is answered with 422. A key still in flight is answered with 409 - as is a key whose original request was interrupted before it finished, for a few minutes afterwards, until that attempt is presumed dead. A completed response stays replayable for 24 hours. The key is scoped to the caller, not to the action: reusing it for a different action is answered with 409 or 422 rather than treated independently. On read actions this header is ignored. On write actions that cannot offer the guarantee it is answered with `400 IDEMPOTENCY_NOT_SUPPORTED` rather than silently ignored.

Request body

Required, application/json: createCreditCardEntryInput.

Field	Type	Required	Description
`entityId`	string	yes	The legal entity the entry is posted under. See id on GET base/entities. Example: `"e8dc29b9-7e79-4709-bb32-95938bcb1bd1"`.
`creditCardAccountId`	string	yes	The general-ledger account behind the credit card account this entry posts against. See id on GET accounting/accounts/:id. Example: `"f50164c3-85e3-4dab-986e-3fdb39f8ecc1"`.
`transactionDate`	date	yes	The date the transaction took place. Use format YYYY-MM-DD. It decides the posting period. Example: `"2026-02-14"`.
`currency`	string	no	The currency of the entry. Format ISO 4217, for example 'USD'. It governs every amount on the entry. Omit to use the account's own currency. When supplied it must match the account's currency. Example: `"USD"`.
`status`	string	no	The reconciliation status. Accepted values: 'Matched', 'Unmatched', 'Posted', 'Voided', 'Integrated'. Defaults to 'Unmatched'. Example: `"unmatched"`.
`name`	string	no	A short name for the entry. Example: `"February bank fees"`.
`description`	string	no	A free-form description of the entry.
`serviceDate`	date	no	The date the goods or services were delivered. Use format YYYY-MM-DD.
`origin`	string	no	The system or process the entry originated from.
`externalUrl`	string	no	A link to the entry in the originating system.
`lines`	array<object>	yes	The lines of the entry, in the order they appear. At least one is required. No line may be zero, and the lines may not sum to zero. Example: `[{"accountId":"9994c3ed-f812-44c1-9454-7f36b2bfb0fb","amount":"-125.00","description":"Account maintenance fee","lineType":"oneTime"}]`.
`lines[].accountId`	string	yes	The general-ledger account this line posts to. It must not be a grouping account. See id on GET accounting/accounts/:id.
`lines[].amount`	decimal	yes	The line amount, as a decimal in the entry currency. It must be non-zero.
`lines[].description`	string	no	A free-form description of the line.
`lines[].departmentId`	string	no	The department this line is attributed to. See id on GET people/departments/:id.
`lines[].businessUnitId`	string	no	The business unit this line is attributed to. There is no endpoint for it.
`lines[].businessPartnerId`	string	no	The business partner this line is attributed to. Required when vatPercentage is supplied. There is no endpoint for it.
`lines[].lineType`	string	no	The kind of line. Accepted values: 'oneTime', 'prepaid'. Derived from the account's sub-type when omitted.
`lines[].vatPercentage`	decimal	no	The VAT rate applied, as a percentage. For example, 19 means 19%. Supplying it requires businessPartnerId.
`lines[].vatAccountId`	string	no	The general-ledger account the VAT posts to. See id on GET accounting/accounts/:id.
`lines[].reverseVatAccountId`	string	no	The general-ledger account the reverse-charge VAT posts to. See id on GET accounting/accounts/:id.
`lines[].vatAmount`	decimal	no	The VAT amount, as a decimal in the entry currency. Omit to derive it from vatPercentage.
`lines[].netAmount`	decimal	no	The net amount, as a decimal in the entry currency. Omit to derive it from amount less VAT.
`lines[].amortizationSchedules`	array<object>	no	The amortization schedules to defer this line over, one per accounting book. Only a prepaid line may carry them: on any other line they are refused with AMORTIZATION_NOT_ALLOWED_ON_LINE. Because lineType is derived from the account's sub-type when omitted, a line that resolves to a non-prepaid account is refused the same way.
`lines[].amortizationSchedules[].bookId`	string	no	The accounting book this schedule posts into. See id on GET accounting/books/:id. Omit it on a single-book entity to use that entity's default transaction book; send one entry per book otherwise. Two entries for the same book are refused with DUPLICATE_AMORTIZATION_BOOK.
`lines[].amortizationSchedules[].deferredAccountId`	string	no	The general ledger account the deferred balance sits on until it is recognized. See id on GET accounting/accounts/:id. Defaults to the line's own accountId.
`lines[].amortizationSchedules[].recognitionAccountId`	string	yes	The general ledger account where each schedule line recognizes the expense. See id on GET accounting/accounts/:id.
`lines[].amortizationSchedules[].amortizationMethod`	string	yes	How the schedule spreads its total. Values include 'exactDays', 'pointInTime', 'straightLine', 'straightLineProRateFirstLast' and 'usageBased'.
`lines[].amortizationSchedules[].amortizationStartDate`	date	yes	The first day the schedule amortizes over. Format YYYY-MM-DD. It must not be after amortizationEndDate.
`lines[].amortizationSchedules[].amortizationEndDate`	date	yes	The last day the schedule amortizes over, inclusive. Format YYYY-MM-DD.
`lines[].amortizationSchedules[].term`	decimal	yes	The number of months the schedule spreads over. Required, because the schedule lines are created from it when the entry's journal entry is posted.
`lines[].amortizationSchedules[].description`	string	no	A note to record against the schedule.
`attachments`	array<object>	no	Files to attach to the entry, each naming an already-uploaded file by its id. Required on a tenant configured to require an attachment.
`attachments[].fileName`	string	yes	The display name of the attached file.
`attachments[].fileId`	string	yes	The identifier of the already-uploaded file.

{
  "entityId": "e8dc29b9-7e79-4709-bb32-95938bcb1bd1",
  "creditCardAccountId": "f50164c3-85e3-4dab-986e-3fdb39f8ecc1",
  "transactionDate": "2026-02-14",
  "currency": "USD",
  "status": "unmatched",
  "name": "February bank fees",
  "description": "<description>",
  "serviceDate": "2026-01-15",
  "origin": "<origin>",
  "externalUrl": "<externalUrl>",
  "lines": [
    {
      "accountId": "9994c3ed-f812-44c1-9454-7f36b2bfb0fb",
      "amount": "-125.00",
      "description": "Account maintenance fee",
      "lineType": "oneTime"
    }
  ],
  "attachments": [
    {
      "fileName": "<fileName>",
      "fileId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ]
}

Response

200 Success

Under data (createCreditCardEntryOutput):

Field	Type	Required	Description
`id`	string	yes	The unique identifier for the created credit card entry. Example: `"c41d0b58-2e97-4f6a-8d13-7b5e9c204af6"`.

{
  "data": {
    "id": "c41d0b58-2e97-4f6a-8d13-7b5e9c204af6"
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Response headers

Idempotency-Replayed — Present and true only when this response replays a previously stored one for the same Idempotency-Key, rather than reflecting a live execution. Absent on a live response - never sent as false.

Errors

Code	Status
`REFERENCE_NOT_FOUND`	400
`INVALID_FIELD_VALUE`	400
`POSTING_PERIOD_NOT_OPEN`	400
`CURRENCY_MISMATCH`	400
`ACCOUNT_ENTITY_MISMATCH`	400
`GROUPING_ACCOUNT_NOT_ALLOWED`	400
`BUSINESS_PARTNER_REQUIRED_FOR_VAT`	400
`NO_LINES`	400
`ZERO_LINE_AMOUNT`	400
`ZERO_TOTAL_AMOUNT`	400
`ATTACHMENT_REQUIRED`	400
`AMORTIZATION_NOT_ALLOWED_ON_LINE`	400
`AMORTIZATION_DATE_RANGE_INVALID`	400
`AMORTIZATION_BOOK_NOT_CONFIGURED`	400
`DUPLICATE_AMORTIZATION_BOOK`	400
`AMORTIZATION_TERM_MISMATCH`	400
`AMORTIZATION_METHOD_INVALID`	400
`AMORTIZATION_SCHEDULE_NOT_FOUND`	400
`AMORTIZATION_SCHEDULE_POSTED`	400
`IDEMPOTENCY_KEY_CONFLICT`	409
`IDEMPOTENCY_PAYLOAD_MISMATCH`	422

Statuses

400 — Invalid request or business failure. Codes: REFERENCE_NOT_FOUND, INVALID_FIELD_VALUE, POSTING_PERIOD_NOT_OPEN, CURRENCY_MISMATCH, ACCOUNT_ENTITY_MISMATCH, GROUPING_ACCOUNT_NOT_ALLOWED, BUSINESS_PARTNER_REQUIRED_FOR_VAT, NO_LINES, ZERO_LINE_AMOUNT, ZERO_TOTAL_AMOUNT, ATTACHMENT_REQUIRED, AMORTIZATION_NOT_ALLOWED_ON_LINE, AMORTIZATION_DATE_RANGE_INVALID, AMORTIZATION_BOOK_NOT_CONFIGURED, DUPLICATE_AMORTIZATION_BOOK, AMORTIZATION_TERM_MISMATCH, AMORTIZATION_METHOD_INVALID, AMORTIZATION_SCHEDULE_NOT_FOUND, AMORTIZATION_SCHEDULE_POSTED
401 — The request carries no valid access token.
403 — Not authorized
404 — Not found
409 — The Idempotency-Key is still being processed by another request.
422 — The Idempotency-Key was already used with a different request payload.
429 — Too many requests from this client address. The response has no body and no Retry-After header.
500 — Internal server error