---
title: "Import card transactions"
method: POST
path: "/v1/card-transactions/import"
tags: ["v1 - Card Transactions"]
---

# Import card transactions

`POST /v1/card-transactions/import`

## Request

- Base URL: `https://light.inc` (the document declares no server; this is the origin it was published from)
- URL: `https://light.inc/v1/card-transactions/import`
- Auth: one of:
  - API key in header `Authorization`
  - HTTP bearer

Imports a batch of up to 100 external card transactions. Each row is validated and created independently, so one bad row does not affect the others -- the response has one result per row, in the same order as the request. Larger batches are rejected as a whole. 'providerId' is the row's idempotency key: a row whose providerId was already imported comes back as SKIPPED_DUPLICATE with the existing transaction id. Always pass the issuer's own transaction id when you have one; when omitted, the key is derived from the row's card, amount, date and merchant, so re-sending the same rows is safe but two genuinely different transactions with identical content in one request are kept apart only by their order. Amounts are in minor units (cents). 'amount' and 'currency' are what settled on the card's balance account and must be in that account's currency; for a purchase made in another currency, pass the purchase-side amount as 'originalAmount' and 'originalCurrency'. Rules, each failing only that row: both or neither; the same currency must carry the same amount; both amounts are positive magnitudes and 'direction' carries the sign. When omitted they default to the settled amount. Each result echoes the row's index and providerId; a FAILED row carries the error as text and as a structured 'failure'.

## Request body

- ExternalImportCardTransactionsRequestV1Model
  - `transactions` ExternalImportCardTransactionRequestV1Model[], required: Rows to import. Maximum 100 per request.
    - `cardId` string, uuid, nullable: Light's id of the card. Give this or cardProviderId, not both.
    - `cardProviderId` string, nullable: The card's own provider id, as given when the card was created. Give this or cardId, not both.
    - `providerId` string, nullable: The issuer's own transaction id. Used as the idempotency key: a row whose providerId was already imported comes back as SKIPPED_DUPLICATE. When omitted, Light derives one from the card, amount, date and merchant.
    - `amount` integer, required: Amount settled on the balance account, in minor units (e.g. cents). Positive; 'direction' carries the sign.
    - `currency` string, required
    - `originalAmount` integer, nullable: Purchase-side amount in minor units when the purchase was made in another currency.
    - `originalCurrency` string, nullable
    - `direction` 'DEBIT' | 'CREDIT': ⚠️ This enum is not exhaustive; new values may be added in the future.
    - `merchantName` string, nullable
    - `performedAt` string, date-time
    - `postingDate` string, date, nullable: Posting date of the ledger document when the transaction is auto-posted. Defaults to the day of 'performedAt'.

## Response `default`

default response

- ExternalImportCardTransactionResultV1Model[]
  - `index` integer: Position of the row in the request.
  - `outcome` 'CREATED' | 'FAILED' | 'SKIPPED_DUPLICATE': ⚠️ This enum is not exhaustive; new values may be added in the future.
  - `cardTransactionId` string, uuid, nullable
  - `providerId` string, nullable: The row's providerId: the one sent, or the one Light derived for a created or skipped row.
  - `error` string, nullable
  - `failure` ExternalUiClientExceptionV1Model, nullable: Failure context when vendor onboarding fails.
    - `name` string: The error name
    - `type` 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'CONFLICT' | 'UNPROCESSABLE_CONTENT': The error type ⚠️ This enum is not exhaustive; new values may be added in the future.
    - `errors` ExternalUiClientExceptionErrorV1Model[]: List of errors providing details about what went wrong
      - `type` string: A string code identifying the error type
      - `message` string: A human-readable message providing more details about the error
      - `path` string[], nullable: Optional path of the error when the error is for a specific field. Used mostly on BAD_REQUEST errors, that path will match the field name on the request object
      - `context` object, nullable: Optional context providing additional information about the error. This can include any relevant data that might help in understanding or resolving the error

---

[API](https://skmtc.dev/light/apis/light-api.md) - [All operations](https://skmtc.dev/light/apis/light-api/llms.txt) - [OpenAPI document](https://skmtc.dev/light/apis/light-api/revisions/84f51306f648?raw)