# Create a credit card entry

Operation ID: `createCreditCardEntry`

Group: Banking › Credit Card Entries

[Open in the interactive reference](https://docs.api.lensing.ai/lensing/v1/endpoints/createCreditCardEntry)

`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. |

```json
{
  "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"`. |

```json
{
  "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