> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage credit notes (accounts payable)

> Learn how to manage your credit notes.

<Info>
  This guide covers credit notes in accounts payable. Tesouro also supports [credit notes for
  accounts receivable](/finops/guides/accounts-receivable/credit-notes).
</Info>

## Overview

There are two ways to create a credit note:

* [Create a credit note via API](#create-a-credit-note-from-data) by providing the amount, currency, and other details.
* [Upload a credit note](#upload-files-via-api) in PDF, PNG, or JPEG formats via API.

When a credit note is created from a PDF, PNG, or JPEG file, [Tesouro’s OCR](/finops/guides/accounts-payable/payables/collect#about-tesouro-ocr) service automatically extracts the credit note information from the file and a new credit note is created with the extracted data fields accordingly. The file property of the credit note contains the file metadata and the link to access the original source file.

### Automatically link credit notes with payables

You can configure Tesouro to automatically link credit notes which have a payable reference to the appropriate payable during the credit note creation based on the following criteria:

* The field `based_on_document_id` of the credit note must be equal to the `document_id` of the payable.
* The payable needs to be under `waiting_to_be_paid`, `partially_paid`, or `paid` statuses.
* The payable must **not** be linked to any other credit note.
* Both credit note and payable must have the same value for the `counterpart_id` field.

If the credit note field `based_on_document_id` corresponds to multiple payables with the same `document_id` and `counterpart_id`, the credit note is created but **not** auto-linked to any payable.

To enable this feature, send a `PATCH` request to the `/settings` endpoint, setting the `payable.allow_credit_note_autolinking` field to `true`:

```sh lines theme={null}
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/settings' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     -d '{
        "payable": {
          "allow_credit_note_autolinking": true
        }
      }'
```

## Roles and permissions

To create and manage credit notes using an [organization user token](/finops/guides/organizations/users#get-organization-user-token), this organization user must have a role with the `payables` [permission](/finops/api/concepts/permissions).

If a [partner-level token](/finops/guides/authentication/client-credentials) is used, no special permissions are needed.

## Create a credit note from data

To create a new credit note, call `POST /payable-credit-notes`:

```sh expandable lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/payable-credit-notes' \
  -H 'accept: application/json' \
  -H 'X-Finops-Version: 2025-06-23' \
  -H 'X-Organization-Id: ORGANIZATION_ID' \
  -d '{
    "based_on": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "based_on_document_id": "DE12312",
    "counterpart": {
      "address": {
        "city": "New York",
        "country": "US",
        "line1": "Fifth Avenue",
        "line2": "string",
        "postal_code": "07001",
        "state": "NY"
      },
      "bank_account": {
        "account_holder_name": "Cayla Lloyd",
        "account_number": "12345678",
        "routing_number": "00000000"
      },
      "email": "acme@example.com",
      "name": "Acme Inc.",
      "phone": "5551231234",
      "tax_id": "12345678"
    },
    "counterpart_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "counterpart_address_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "counterpart_bank_account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "counterpart_vat_id_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "counterpart_raw": {...},
    "base64_encoded_file": "string",
    "file_name": "invoice.pdf",
    "document_id": "DE2287",
    "description": "string",
    "due_date": "2024-10-29",
    "issued_at": "2024-10-29",
    "currency": "USD",
    "subtotal": 1250,
    "tax": 2000,
    "tax_amount": 250,
    "total_amount": 15000,
    "discount": 500,
    "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "tag_ids": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ]
  }'
```

<Info>
  **Requirements and considerations**

  * The fields `document_id`, `issued_at`, and `total_amount` are mandatory.
  * The `issued_at` field cannot be a future date.
  * All the amount fields in the credit notes and line items must be greater than 0, except the `total_amount` field, which is **optional**.
  * A credit note cannot be linked to a canceled payable.
</Info>

## Upload files via API

You can upload credit notes in the PDF, PNG, or JPG format to Tesouro by calling `POST /payable-credit-notes/upload-from-file`. The maximum file size is 10 MB:

```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/payable-credit-notes/upload-from-file' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: multipart/form-data' \
     -F 'file=@pdf-invoice.pdf;type=application/pdf'
```

The successful response contains the credit note ID and other fields:

```json expandable lines theme={null}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-01-15T14:30:00Z",
  "updated_at": "2024-01-15T14:30:00Z",
  "based_on": "123e4567-e89b-12d3-a456-426614174000",
  "based_on_document_id": "INV-2287",
  "counterpart": {
    "address": {
        "city": "New York",
        "country": "US",
        "line1": "Fifth Avenue",
        "line2": "string",
        "postal_code": "07001",
        "state": "NY"
    },
    "bank_account": {
      "account_holder_name": "Cayla Lloyd",
      "account_number": "12345678",
      "routing_number": "00000000"
    },
    "email": "acme@example.com",
    "name": "Acme Inc.",
    "phone": "5551231234",
    "tax_id": "12345678",
  },
  "counterpart_address_id": "123e4567-e89b-12d3-a456-426614174000",
  "counterpart_bank_account_id": "123e4567-e89b-12d3-a456-426614174000",
  "counterpart_id": "123e4567-e89b-12d3-a456-426614174000",
  "counterpart_vat_id_id": "123e4567-e89b-12d3-a456-426614174000",
  "counterpart_raw": {...},
  "created_by_external_user_id": "ext_user_123",
  "created_by_external_user_name": "John Doe",
  "created_by_user_id": "123e4567-e89b-12d3-a456-426614174000",
  "currency": "USD",
  "currency_exchange": {
    "default_currency_code": "string",
    "rate": 0,
    "total": 0
  },
  "description": "Credit note for returned items from invoice INV-2287",
  "document_id": "CN-2287",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "file_id": "123e4567-e89b-12d3-a456-426614174000",
  "file_url": "string",
  "issued_at": "2024-01-15",
  "ocr_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "ocr_status": "processing",
  "origin": "SAP",
  "project_id": "123e4567-e89b-12d3-a456-426614174000",
  "sender": "supplier@example.com",
  "source_of_data": "user_specified",
  "status": "submitted_for_approval",
  "subtotal": 1000,
  "tags": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Department A",
      "category": "department"
    }
  ],
  "tax": 20,
  "tax_amount": 200,
  "total_amount": 1200
}
```

You will also receive a [webhook](/finops/guides/getting-started/webhooks/index) indicating that this credit note resource has been created:

```json lines theme={null}
{
  "id": "aa314fdd-a763-4920-a8c8-6285fc1745c0",
  "created_at": "2024-03-04T20:06:48.593225+00:00",
  "action": "credit_note.created_from_file_upload",
  "api_version": "2025-06-23",
  "entity_id": "en-your0000-enti-ty00-1D3799b65bcf",
  "description": "Action has been performed on the credit note: created_from_file_upload.",
  "object": {
    "id": "aa314fdd-a763-4920-a8c8-6285fc1745c0"
  },
  "object_type": "credit_note",
  "webhook_subscription_id": "c7f37127-44e5-494a-833a-21e60585f187"
}
```

Note that at this stage the credit note resource is incomplete and waiting for the results of the OCR service, which automatically scans the details from the uploaded credit note and maps the information from the credit note to the corresponding data field in the system. Its status is set as `processing`.

To cancel the OCR process, call `POST /payable-credit-notes/{id}/cancel-ocr`. The credit note status will be changed to `canceled`.

When the OCR scanning is finished (this might take up to 5-7 minutes), you will receive the `credit_note.ocr_finished` webhook event.

## Change credit note status

You can manually change the status of the credit notes and move them through the lifecycle until their application. See the [credit notes lifecycle](/finops/guides/accounts-payable/credit-notes/lifecycle) for more information.

Alternatively, we recommend that you implement approval policies to manage the credit notes transitions.

## List all credit notes

To list all credit notes, call [`GET /payable-credit-notes`](/finops/reference/openapi/payables/get-payables). You can sort and filter the results by the amount, status, and other fields. For the full list of available sort and filter parameters, see the [`GET /payable-credit-notes`](/finops/reference/openapi/payables/get-payables) endpoint:

```sh lines theme={null}
curl -X GET 'https://api.sandbox.tesouro.com/v1/payable-credit-notes' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'
```

The `data` array in the response contains a list of related credit notes, if any:

```json lines theme={null}
{
  "data": [
    {
      "type": "credit_note",
      "id": "9c9f4b57-009e-43ef-a784-d0d8ceab2bf2",
      ...
    }
  ],
  "prev_pagination_token": null,
  "next_pagination_token": null
}
```

### Find all credit notes of a payable

To check if there are credit notes linked to a specific payable, call [`GET /payable-credit-notes?based_on={payable_id}`](/finops/reference/openapi/payables/get-payables):

```sh lines theme={null}
curl -X GET 'https://api.sandbox.tesouro.com/v1/payable-credit-notes?based_on={payable_id}' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'
```

## Update a credit note

Credit notes in the `draft` and `new` statuses can be updated, for example, to provide additional details or fix the information extracted by OCR. To update a credit note, call `PATCH /payable-credit-notes/{payable_credit_notes_id}` with the request body containing the new field values. For example, to update the `description` field:

```sh lines theme={null}
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/payable-credit-notes/{payable_credit_notes_id}' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "description": "New description of the payable"
     }'
```

## Delete a credit note

Credit notes in any status can be deleted by calling the [`DELETE /payable-credit-notes/{payable_credit_notes_id}`](/finops/reference/openapi/payables/delete-payables-id) endpoint:

```sh lines theme={null}
curl -X DELETE 'https://api.sandbox.tesouro.com/v1/payable-credit-notes/{payable_credit_notes_id}' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'
```

<Danger>
  This action is irreversible, and once deleted, credit notes can no longer be accessed.
</Danger>