# Create a vendor credit

Operation ID: `createVendorCredit`

Group: Accounting › Vendor Credits

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

`POST /accounting/vendor-credits`

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 vendor credit. The credit is created with its line items, and the response contains only its id. A new credit is always 'unapplied'. To apply it to a vendor bill, use POST accounting/vendor-credits/:id/apply.

To see the credit, including its vendorCreditNumber once one is assigned, use GET accounting/vendor-credits/: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`: createVendorCreditInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `vendorId` | string | yes | The vendor being credited. See id on GET accounting/vendors/:id. Example: `"3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45"`. |
| `entityId` | string | yes | The legal entity the credit is booked under. See id on GET base/entities. Example: `"8f2c1d40-5a6b-4c7d-9e80-1f2a3b4c5d6e"`. |
| `referenceNumber` | string | yes | The vendor's credit memo reference number, as printed on the document. Example: `"CN-4471"`. |
| `creditDate` | date | yes | The date on the vendor's credit memo. Use format YYYY-MM-DD. Example: `"2026-08-01"`. |
| `currency` | string | yes | The currency of the credit. Format ISO 4217, for example 'USD'. Governs every line amount and vatAmount, which are decimals. Example: `"EUR"`. |
| `origin` | string | no | The source system this record came from, as free-form text, for example 'Ramp'. Omit it and it stays unset. The server does not set a value. |
| `lines` | array<object> | yes | The line items of the credit, in the order they should appear. At least one is expected. A credit with no lines credits nothing. Example: `[{"amount":"300.00","description":"Returned goods","vatPercentage":"19.00"}]`. |
| `lines[].amount` | decimal | yes | The gross credit amount for the line, as a decimal in the credit currency. |
| `lines[].description` | string | no | A description of the credit line. |
| `lines[].accountId` | string | no | The general ledger account this line credits. See id on GET accounting/accounts/:id. |
| `lines[].departmentId` | string | no | The department this line is allocated to. See id on GET people/departments/:id. |
| `lines[].businessUnitId` | string | no | The business unit this line is allocated to. There is no endpoint for it. |
| `lines[].vatPercentage` | decimal | no | The VAT rate applied, as a percentage. 19 means 19%, not 0.19. |
| `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 reverse-charge VAT posts to. See id on GET accounting/accounts/:id. |
| `lines[].vatAmount` | decimal | no | The explicit VAT amount, as a decimal in the credit currency. Omit to derive it from vatPercentage. |
| `lines[].valueAllocationId` | string | no | The value-allocation rule distributing this line across dimensions. There is no endpoint for it. |
| `lines[].lineType` | string | no | The kind of line. Accepted values: 'expense' (a one-time credit) or 'prepaid' (a credit spread over several periods). Defaults to 'expense'. |
| `lines[].amortizationSchedules` | array<object> | no | The amortization schedules to defer this line over, one per accounting book. Only a line whose lineType is 'prepaid' may carry them. Each schedule starts out not started and begins recognizing once the credit posts. |
| `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 each installment recognizes the expense into. 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. A count, not an amount, so it carries no currency. It is required here, because a schedule without one cannot be turned into installments when the credit posts. |
| `lines[].amortizationSchedules[].description` | string | no | A note to record against the schedule. |
| `attachments` | array<object> | no | Files to attach to the credit. Each names an already-uploaded file by its id. |
| `attachments[].fileName` | string | yes | The display name of the attached file. |
| `attachments[].fileId` | string | yes | The identifier of the already-uploaded file. There is no endpoint for it. |

```json
{
  "vendorId": "3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45",
  "entityId": "8f2c1d40-5a6b-4c7d-9e80-1f2a3b4c5d6e",
  "referenceNumber": "CN-4471",
  "creditDate": "2026-08-01",
  "currency": "EUR",
  "origin": "<origin>",
  "lines": [
    {
      "amount": "300.00",
      "description": "Returned goods",
      "vatPercentage": "19.00"
    }
  ],
  "attachments": [
    {
      "fileName": "<fileName>",
      "fileId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ]
}
```

## Response

`200` Success

Under `data` (createVendorCreditOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The unique identifier for the created vendor credit. Example: `"d52e1c69-3fa8-4b17-9e24-8c6fa0315bd7"`. |

```json
{
  "data": {
    "id": "d52e1c69-3fa8-4b17-9e24-8c6fa0315bd7"
  },
  "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 |
| `REFERENCE_NUMBER_NOT_UNIQUE` | 400 |
| `TOO_MANY_LINES` | 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, REFERENCE_NUMBER_NOT_UNIQUE, TOO_MANY_LINES, 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