# Returns the credit memos that match the given filters.

`POST /accounting/credit-memos/search`

Group: Accounting › Credit Memos · Operation ID: `searchCreditMemo`

[Open in the interactive reference](https://docs.api.lensing.ai/?op=searchCreditMemo)

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | `"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`. |

## Request body

Required, `application/json`: searchCreditMemoInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | no | The filters to apply. A credit memo must match every filter you send. Omit to return all credit memos. |
| `filters.id` | string | no | Limits results to the credit memo with this id. |
| `filters.creditMemoNumber` | string | no | Limits results to the credit memo with this number, for example 'CM-1'. The match is exact. |
| `filters.customerId` | string | no | Limits results to credit memos issued to this customer. See id on GET accounting/customers/:id. |
| `filters.customerName` | string | no | Limits results to credit memos whose customer name contains this text. The match is case-insensitive. |
| `filters.customerNumber` | string | no | Limits results to credit memos with this customer number. The match is exact. |
| `filters.entityId` | string | no | Limits results to credit memos issued by this legal entity. See id on GET base/entities. |
| `filters.entityName` | string | no | Limits results to credit memos whose entity name contains this text. The match is case-insensitive. |
| `filters.creditMemoStatus` | array of string | no | Limits results to credit memos in any of these application statuses. Possible values: 'unapplied', 'partiallyApplied', 'appliedInFull'. Any other value matches no credit memo. An empty array does not constrain. |
| `filters.creditMemoType` | array of string | no | Limits results to credit memos of any of these types. Possible values: 'manual', 'creditRebill', 'earlyRenewal', 'lateFees', 'cancellation', 'inventoryReturn'. Any other value matches no credit memo. An empty array does not constrain. |
| `filters.description` | string | no | Limits results to credit memos whose description contains this text. The match is case-insensitive. |
| `filters.externalCreditMemoId` | string | no | Limits results to the credit memo with this external source system identifier. The match is exact. |
| `filters.invoiceNumber` | string | no | Limits results to credit memos created from the invoice with this number. The match is exact. |
| `filters.creditMemoDate` | object | no | Limits results to credit memos issued between the given bounds. Omit either bound to leave that side open. |
| `filters.creditMemoDate.start` | string (date) | no | The inclusive lower bound. Format YYYY-MM-DD. |
| `filters.creditMemoDate.end` | string (date) | no | The inclusive upper bound. Format YYYY-MM-DD. |
| `filters.lastModifiedDate` | object | no | Limits results by when the credit memo last changed, the window to poll for an incremental sync. Omit either bound to leave that side open. |
| `filters.lastModifiedDate.start` | string | no | The inclusive lower bound, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `filters.lastModifiedDate.end` | string | no | The inclusive upper bound, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `filters.externalIdentifier` | object | no | Limits results to credit memos with this external identifier. Both fieldName and value are required. Several credit memos may share a value, so this returns the items array, not a single record. |
| `filters.externalIdentifier.fieldName` | string | yes | The configured field name of the identifier, for example 'netsuiteCreditMemoId'. It must be the fieldName of an existing credit-memo external-identifier configuration, or the call fails with UNKNOWN_EXTERNAL_IDENTIFIER. |
| `filters.externalIdentifier.value` | string | yes | The identifier value to match, exactly as the other system stores it. |
| `page` | object | no | The pagination controls. Omit on the first request. |
| `page.cursor` | string | no | The cursor from the previous response's pagination.nextCursor. Omit on the first request. |
| `page.size` | number | no | The number of credit memos per page. Defaults to 50. A value above 200 is treated as 200, not rejected. |

Example:

```json
{
  "filters": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "creditMemoNumber": "<creditMemoNumber>",
    "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "customerName": "<customerName>",
    "customerNumber": "<customerNumber>",
    "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "entityName": "<entityName>",
    "creditMemoStatus": [
      "<creditMemoStatus>"
    ],
    "creditMemoType": [
      "<creditMemoType>"
    ],
    "description": "<description>",
    "externalCreditMemoId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "invoiceNumber": "<invoiceNumber>",
    "creditMemoDate": {
      "start": "2026-01-15",
      "end": "2026-01-15"
    },
    "lastModifiedDate": {
      "start": "<start>",
      "end": "<end>"
    },
    "externalIdentifier": {
      "fieldName": "<fieldName>",
      "value": "<value>"
    }
  },
  "page": {
    "cursor": "<cursor>",
    "size": 0
  }
}
```

## Response

`200` Success

Under `data` (searchCreditMemoOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object | yes | The matching credit memos for this page, most recently created first. An empty array when nothing matches. |
| `items[].id` | string | yes | The unique identifier for the credit memo. |
| `items[].creditMemoNumber` | string | no | The credit memo number, for example 'CM-1'. Absent while none has been assigned. |
| `items[].creditMemoDate` | string (date) | yes | The date the credit memo was issued. Format YYYY-MM-DD. |
| `items[].creditMemoStatus` | string | no | The application status of the credit memo. Possible values: 'unapplied', 'partiallyApplied', 'appliedInFull'. |
| `items[].creditMemoType` | string | no | How the credit memo was created. Possible values: 'manual', 'creditRebill', 'earlyRenewal', 'lateFees', 'cancellation', 'inventoryReturn'. Only 'manual' credit memos are created through this API. The rest come from internal workflows. |
| `items[].manualCreditMemoType` | string | no | The reason for a manual credit memo, as a tenant-configured key, for example 'writeOff' or 'customerSatisfaction'. Absent when creditMemoType is not 'manual'. |
| `items[].currency` | string | yes | The currency of the credit memo. Every amount on the record, its lines and its application rows is in this currency. Format ISO 4217, for example 'USD'. |
| `items[].description` | string | no | A free-form description of the credit memo. |
| `items[].externalCreditMemoId` | string | no | The identifier of this credit memo in an external source system. For identifiers owned by your other systems, use externalIdentifiers below. |
| `items[].customerId` | string | yes | The customer the credit memo is issued to. See id on GET accounting/customers/:id. |
| `items[].customerName` | string | no | The name of the customer the credit memo is issued to. |
| `items[].customerNumber` | string | no | The customer number of the customer the credit memo is issued to. |
| `items[].entityId` | string | yes | The legal entity that issued the credit memo. See id on GET base/entities. |
| `items[].entityName` | string | no | The name of the legal entity that issued the credit memo. |
| `items[].invoiceId` | string | no | The invoice the credit memo was created from. Absent when it was not created from an invoice. See id on GET accounting/invoices/:id. |
| `items[].invoiceNumber` | string | no | The number of the invoice the credit memo was created from. Present whenever invoiceId is. |
| `items[].subtotal` | string (decimal) | no | The subtotal before tax and duties, in the credit memo currency. Absent when no subtotal has been computed. |
| `items[].totalTax` | string (decimal) | no | The total tax across all lines, in the credit memo currency. |
| `items[].totalDutiesAndCustoms` | string (decimal) | no | The total duties and customs across all lines, in the credit memo currency. |
| `items[].totalAmountCredited` | string (decimal) | no | The total credited, including tax and duties, in the credit memo currency. |
| `items[].appliedAmount` | string (decimal) | no | The amount applied to invoices and debit memos so far, in the credit memo currency. This is the net of the application rows below. |
| `items[].unappliedAmount` | string (decimal) | no | The amount still available to apply, in the credit memo currency. |
| `items[].lastModifiedDate` | string (date-time) | yes | The date and time the credit memo last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].lines` | array of object | no | The lines of the credit memo, each crediting one product or free-text item. An empty array when the credit memo has no lines. Every amount is in the credit memo currency. |
| `items[].lines[].id` | string | yes | The unique identifier for the credit memo line. |
| `items[].lines[].creditMemoLineNumber` | string | no | The line number within the credit memo. |
| `items[].lines[].description` | string | no | The line description, as shown to the customer. |
| `items[].lines[].productId` | string | no | The product credited by the line. Absent on free-text lines. See id on GET accounting/products/:id. |
| `items[].lines[].productCode` | string | no | The product code as it stood when the line was created. It does not follow later changes to the product. |
| `items[].lines[].productDescription` | string | no | The product description as it stood when the line was created. It does not follow later changes to the product. |
| `items[].lines[].quantity` | string (decimal) | no | The quantity credited. |
| `items[].lines[].unitPrice` | string (decimal) | no | The price per unit, in the credit memo currency. |
| `items[].lines[].totalPrice` | string (decimal) | no | The line total before tax and duties, in the credit memo currency. |
| `items[].lines[].taxAmount` | string (decimal) | no | The tax on the line, in the credit memo currency. |
| `items[].lines[].dutiesAndCustomsAmount` | string (decimal) | no | The duties and customs on the line, in the credit memo currency. |
| `items[].lines[].amountCredited` | string (decimal) | no | The total credited for the line, in the credit memo currency: totalPrice + taxAmount + dutiesAndCustomsAmount. |
| `items[].lines[].taxCode` | string | no | The tax code applied to the line. |
| `items[].lines[].taxDate` | string (date) | no | The date the line's tax was determined. Format YYYY-MM-DD. |
| `items[].lines[].serviceStartDate` | string (date) | no | The first day of the service period the line covers. Format YYYY-MM-DD. |
| `items[].lines[].serviceEndDate` | string (date) | no | The last day of the service period the line covers, inclusive. Format YYYY-MM-DD. |
| `items[].applications` | array of object | no | The application rows, each recording one allocation of the credit memo against an invoice or debit memo. Applying and unapplying both add a row, told apart by actionType and the sign of appliedAmount, so this is an append-only history rather than the current allocation. An empty array when the credit memo has never been applied. |
| `items[].applications[].id` | string | yes | The unique identifier for the application row. |
| `items[].applications[].appliedAmount` | string (decimal) | no | The signed amount moved by this row, in the row's currency: positive when applying, negative when unapplying. Sum the rows to reconcile against the header appliedAmount. |
| `items[].applications[].appliedDate` | string (date) | yes | The date the allocation was recorded. Format YYYY-MM-DD. |
| `items[].applications[].actionType` | string | no | What this row did. Possible values: 'applied', 'unapplied'. |
| `items[].applications[].type` | string | no | The kind of document the credit memo was allocated against. Possible values: 'invoice', 'debitMemo'. Absent when the stored target kind is not one this version recognizes. |
| `items[].applications[].targetId` | string | no | The target document: an invoice when type is 'invoice', a debit memo when type is 'debitMemo'. Absent when the target no longer exists or its kind is unrecognized. See id on GET accounting/invoices/:id and GET accounting/debit-memos/:id. |
| `items[].applications[].targetNumber` | string | no | The number of the target document. |
| `items[].applications[].currency` | string | yes | The currency of this row's appliedAmount. Matches the credit memo currency. Format ISO 4217, for example 'USD'. |
| `items[].externalIdentifiers` | array of object | no | The credit memo's identifiers in other systems, one per configured field name. An empty array or absent when the credit memo has none. |
| `items[].externalIdentifiers[].fieldName` | string | yes | The configured field name of the identifier, for example 'netsuiteCreditMemoId'. |
| `items[].externalIdentifiers[].value` | string | yes | The identifier in the other system. |
| `items[].externalIdentifiers[].externalUrl` | string | no | A link to the record in the other system. Absent when none is stored. |
| `pagination` | object | yes | The pagination cursor for this page. |
| `pagination.nextCursor` | string | no | The cursor for the next page. Pass it as page.cursor. Absent on the last page. |
| `pagination.hasMore` | boolean | yes | True when more matches remain beyond this page. |

## Errors

| Code | Status |
| --- | --- |
| `UNKNOWN_EXTERNAL_IDENTIFIER` | 400 |
| `INVALID_TIMESTAMP` | 400 |

## Statuses

- `400` — Invalid request or business failure. Codes: UNKNOWN_EXTERNAL_IDENTIFIER, INVALID_TIMESTAMP
- `401` — Missing or invalid access token
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests
- `500` — Internal server error