Skip to main content

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.

This guide covers credit notes in accounts receivable. Tesouro also supports credit notes for accounts payable.

​
Overview

A credit note, also known as a credit memo, is a legal document used to reduce the amount owed on an invoice after it’s been issued. Organizations typically use credit notes in the following cases:
  • An issued invoice contains a mistake (for example, wrong product or quantity).
  • The order needs to change after the invoice has been issued.
  • The organization or the customer (counterpart) canceled the order.
Credit notes can be used to partially reduce the invoice amount as well as fully cancel an invoice. Multiple credit notes can be issued for the same invoice. However, the total amount credited can’t exceed the invoice amount.
A credit note
You can also configure PDF invoices to include information about credit notes applied. To do this, enable the organization setting generate_paid_invoice_pdf.
An invoice with a list of credits applied

​
Roles and permissions

To create and manage credit notes using an organization user token, this organization user must have a role with the receivables permission. If a partner-level token is used, no special permissions are needed.

​
Use cases

Tesouro API supports the following use cases for credit notes:
  • Reduce quantities of line items.
    Example: the organization issued an invoice for 10 laptops, but only eight were actually delivered. A credit note can “cancel” the remaining two laptops that weren’t delivered.
  • Reduce the price of some or all units within a line item. (Essentially applying a discount.)
    Example: The invoice mistakenly billed a product at $210 instead of $200. A credit note corrects the price back to $200.
  • Credit the full remaining amount of an invoice. This cancels an unpaid invoice, or marks a partially paid invoice as paid.
Credit notes can’t add new line items or increase the unit quantity and price in line items. Instead, the organization should issue a new invoice for the additional amount.

​
Considerations and limitations

  • Credit notes can only be created for invoices in the issued, partially_paid, and overdue statuses. Crediting paid invoices isn’t supported.
  • Credit notes for overdue and partially paid invoices can be used to reduce only the quantity of line items, but not the unit prices.
  • If a credit note cancels the full remaining amount of an invoice:
    • issued and unpaid overdue invoices are automatically moved to the canceled status,
    • partially_paid and partially paid overdue invoices are automatically moved to the paid status.
  • Changing line item tax rates via credit notes isn’t supported.
  • If the original invoice contained any form of discounts or special deductions, you can only issue a credit note once. Partial adjustments of discounted invoices via credit notes aren’t supported.
  • If an invoice includes several line items for the same product, credit notes can’t update those specific line items. However, other line items on the invoice can be updated.
  • If a counterpart’s address or contact information changed after an invoice was issued, you can provide the updated details via a credit note. However, the updated information only appears in the credit note — the original invoice isn’t changed.

​
Credit note lifecycle

Credit notes can have one of two statuses, draft or issued. Draft credit notes can be deleted. Deleted documents can no longer be accessed via the API.
Credit note lifecycle

​
Draft

This is the initial status for all new credit notes. A draft credit note isn’t issued yet and can still be edited. Draft credit notes can be either issued or deleted.
Only one draft credit note can exist per invoice. Before you can create the second draft credit note for the same invoice, you need to issue (or delete) the previous draft credit note.

​
Issued

The credit note is finalized and issued to a counterpart.

​
Ways to create a credit note

There are two ways to create credit notes:
  • Create a credit note directly. Use this to manually adjust the credited amount (for example, to credit a partial amount).
  • Cancel an invoice. If the organization setting receivable_edit_flow is “compliant”, a new credit note will be automatically created and issued for the remaining invoice amount.
Credit notes aren’t automatically sent to counterparts. Use POST /receivables/{credit_note_id} /send to send credit notes via email.

​
Create a credit note manually

​
For the full remaining invoice amount

To create a credit note, call POST /receivables and specify the invoice ID in the based_on field in the request body: 
curl -X POST 'https://api.sandbox.tesouro.com/v1/receivables' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "type": "credit_note",
       "based_on": "c50265da-fddc-4d04-8318-6a449ad84726"
     }'
This creates a draft credit note with a copy of invoice data. The response contains the id assigned to the credit note. The based_on and based_on_document_id properties of the credit note point to the original invoice: 
{
  "id": "ad69dcf0-6fcf-47eb-9628-e7430683bb52",
  ...
  "based_on": "c50265da-fddc-4d04-8318-6a449ad84726",
  "based_on_document_id": "INV-0004",
  ...
  "status": "draft",
  ...
}

{
  "id": "ad69dcf0-6fcf-47eb-9628-e7430683bb52",
  "created_at": "2023-04-17T12:58:51.608547+00:00",
  "updated_at": "2023-04-17T12:58:51.608562+00:00",
  "document_id": null,
  "currency": "USD",
  "subtotal": 150,
  "line_items": [
    {
      "quantity": 1.0,
      "product": {
        "name": "potato",
        "type": "product",
        "description": "Orange potato",
        "price": {
          "currency": "USD",
          "value": 150
        },
        "smallest_amount": 1.0,
        "ledger_account_id": null,
        "id": "26c0f554-5d53-40b7-bd46-bb88f0a8a36b",
        "tax_rate": {
          "id": "8d4c2c10-f7d7-4d7c-a1f5-5f3a9d56371e",
          "created_at": "2023-03-24T05:32:17.923094+00:00",
          "updated_at": "2023-04-06T17:45:16.773977+00:00",
          "value": 0,
          "country": "US",
          "valid_until": null,
          "valid_from": null,
          "status": "active"
        },
        "measure_unit": {
          "name": "kg",
          "description": "kilogram",
          "id": "8054a1d1-8bdc-4eaa-8ec4-7de290a72c97"
        }
      },
      "discount": null,
      "total_before_tax": 150
    }
  ],
  "entity_address": {
    "country": "US",
    "city": "New York",
    "postal_code": "10001",
    "state": "NY",
    "line1": "5th Avenue",
    "line2": null
  },
  "entity": {
    "phone": null,
    "logo": null,
    "email": "Ara_Botsford@gmail.com",
    "name": "NailIt Renovations",
    "tax_id": "000000000",
    "type": "organization"
  },
  "entity_user_id": null,
  "counterpart_id": "155f6af7-ce95-441c-8032-a66145044833",
  "counterpart_tax_id": "123456789",
  "counterpart_type": "organization",
  "counterpart_address": {
    "country": "US",
    "city": "New York",
    "postal_code": "10001",
    "state": "NY",
    "line1": "6th Avenue",
    "line2": ""
  },
  "counterpart_contact": {
    "first_name": "Frank",
    "last_name": "Jones",
    "email": "frank_jones@gmail.com",
    "phone": "1234567890",
    "title": null,
    "address": {
      "country": "US",
      "city": "New York",
      "postal_code": "10001",
      "state": "",
      "line1": "6th Avenue",
      "line2": ""
    }
  },
  "counterpart_name": "Frank Jones",
  "file_url": "https://example.com/bb0259fd-71ad-4c71-b2d8-9df80c12298a/18e41e5b-81f0-44e6-b52a-fbd2679e4e95.pdf",
  "commercial_condition_description": "",
  "total_amount": 150,
  "total_tax_amount": 0,
  "entity_bank_account": {
    "account_number": "2571714302",
    "routing_number": "061000227",
    "bank_name": "Zenith Bank",
    "display_name": "Zenith Bank",
    "is_default": false
  },
  "tax_exempt": false,
  "tax_exemption_rationale": "",
  "based_on": "7e79dba5-4769-4a9c-9596-93af4859b53e",
  "based_on_document_id": "invoice-00002",
  "memo": null,
  "issue_date": null,
  "counterpart_shipping_address": null,
  "counterpart_billing_address": null,
  "counterpart_business_type": null,
  "discount": null,
  "discounted_subtotal": 150,
  "total_tax_amounts": [
    {
      "id": "8d4c2c10-f7d7-4d7c-a1f5-5f3a9d56371e",
      "value": 0,
      "amount": 0
    }
  ],
  "type": "credit_note",
  "status": "draft",
  "purchase_order": null
}
By default, a newly created credit note cancels the full remaining amount of an invoice. If this is what you need, you can proceed to issue the credit note.

​
For a partial amount

The first step is the same as when creating a full amount credit note - call POST /receivables and specify the invoice ID in the based_on field in the request body: 
curl -X POST 'https://api.sandbox.tesouro.com/v1/receivables' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "type": "credit_note",
       "based_on": "c50265da-fddc-4d04-8318-6a449ad84726"
     }'
This returns the id assigned to the created draft credit note: 
{
  "id": "ad69dcf0-6fcf-47eb-9628-e7430683bb52",
  ...
  "based_on": "c50265da-fddc-4d04-8318-6a449ad84726",
  "based_on_document_id": "INV-0004",
  ...
  "status": "draft",
  ...
}
The next step is to adjust the line item quantities and prices as needed. To do this, call PATCH /receivables/{credit_note_id} and provide the updated values. The general PATCH request format for credit notes is as follows. 
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/receivables/CREDIT_NOTE_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 '{
       "credit_note": {
         "line_items": {
           "PRODUCT_ID_1": {
             "quantity": 5,
             "price_diff": 100
           },
           "PRODUCT_ID_2": {
             "quantity": 3,
             "price_diff": 200
           },
           ...
         }
         "memo": "Optional message to display on the credit note"
       }
     }'
Notes:
  • The structure of the line_items field in credit note PATCH requests differs from that in invoice objects.
  • The quantity field represents the number of products you want to remove or apply a discount via the credit note. This number must always be less than or equal to the current total on the invoice object.
  • The price_diff field defines the discount on the product. It represents the amount to be deducted from the current price on the invoice.
  • The old_price field defines the price of a previously discounted product. This field should only be used when applying a further discount on a product item.

​
Example 1: Reduce line item quantity

Consider an invoice line item object with product ID 9ccaf14e-c14d-48eb-8801-4217d52b6114, the price is $5 (500 in minor units), and the quantity is 10. To reduce the product quantity from 10 to 8 (in other words, to remove 2 items), update the credit note data as follows: 
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/receivables/CREDIT_NOTE_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 '{
       "credit_note": {
         "line_items": {
           "9ccaf14e-c14d-48eb-8801-4217d52b6114": {
             "quantity": 2
           }
         }
       }
     }'

​
Example 2: Reduce the unit price of a line item

Consider an invoice line item object with product ID 9ccaf14e-c14d-48eb-8801-4217d52b6114, the price is $5 (500 in minor units), and the quantity is 10. To reduce the unit price from 5 to $4, update the credit note data as follows: 
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/receivables/CREDIT_NOTE_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 '{
       "credit_note": {
         "line_items": {
           "9ccaf14e-c14d-48eb-8801-4217d52b6114": {
             "quantity": 10,
             "price_diff": 100
           }
         }
       }
     }'
A successful request applies a discount of $1 (100 in minor units) to all 10 products on the invoice line item.

​
Example 3: Reduce the price of some units within a line item

Consider an invoice line item object with product ID 9ccaf14e-c14d-48eb-8801-4217d52b6114, the price is $5 (500 in minor units), and the quantity is 10. Suppose you want to reduce the price of 2 units from 5 to $4. The other 8 units should keep the original price. To achieve this, update the credit note data as follows: 
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/receivables/CREDIT_NOTE_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 '{
       "credit_note": {
         "line_items": {
           "9ccaf14e-c14d-48eb-8801-4217d52b6114": {
             "quantity": 2,
             "price_diff": 100
           }
         }
       }
     }'
A successful request applies a discount of $1 (100 in minor units) to 2 of the 10 products on the invoice line item. No change applies to the remaining 8 products on the invoice line item.

​
Example 4: Apply a further discount to an already discounted item

Consider an invoice line item object with product ID 9ccaf14e-c14d-48eb-8801-4217d52b6114, the price is $5 (500 in minor units), and the quantity is 10. Suppose you had already reduced the price of 2 items from 5to5 to 4 (400 in minor units). Now, you want to further reduce the price of 2 units from 4to4 to 2. To achieve this, update the credit note data as follows: 
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/receivables/CREDIT_NOTE_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 '{
       "credit_note": {
         "line_items": {
           "9ccaf14e-c14d-48eb-8801-4217d52b6114": {
             "quantity": 2,
             "price_diff": 200,
             "old_price": 400
           }
         }
       }
     }'

​
Issue a credit note

Once you’ve finalized the credit note, mark it as issued by calling POST /receivables/{credit_note_id}/issue: 
curl -X POST 'https://api.sandbox.tesouro.com/v1/receivables/ad69dc...b52/issue' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'
When a credit note is issued, the following happens:
  • The credit note status changes to "issued".
  • A document number in the format CN-<number> is assigned to the document_id field.
  • The issue_date is set to the current date.
  • The credit note becomes read-only.
Issuing a credit note also updates the reconciliation amounts on an invoice and may trigger a status change on the invoice. If needed, additional credit notes can be created for the same invoice if it still has a remaining amount due.
Issuing a credit note doesn’t automatically send it to the counterpart. See Send a credit note via email below.

​
Download a credit note as PDF

Tesouro automatically generates the PDF version of credit notes in the counterpart language and the organization language, and returns links to these files in the file_url and original_file_url fields of credit note responses: 
{
  "type": "credit_note",
  ...
  // Counterpart's version of a PDF credit note
  "file_language": "en",
  "file_url": "https://bucketname.s3.amazonaws.com/<random_UUID_1>/<random_UUID_2>.pdf",
  ...
  // Organization's version of a PDF credit note
  "original_file_language": "en",
  "original_file_url": "https://bucketname.s3.amazonaws.com/<random_UUID_3>/<random_UUID_4>.pdf",
  ...
}
If file_url or original_file_url is null, repeat the request to GET /receivables/ {credit_note_id} after some time.
If you need just the PDF file link without the full credit note details, call GET /receivables/{credit_note_id}/pdf-link: 
curl -X GET 'https://api.sandbox.tesouro.com/v1/receivables/ad69dc...b52/pdf-link' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'
It returns the following response: 
{
  "file_url": "https://bucketname.s3.amazonaws.com/<random_UUID_1>/<random_UUID_2>.pdf",
  "original_file_url": "https://bucketname.s3.amazonaws.com/<random_UUID_3>/<random_UUID_4>.pdf"
}
The PDF file is updated automatically if the credit note data is changed.

​
Customize the PDF file

Tesouro provides several built-in PDF templates for receivables. Organizations can change their default template or customize their chosen templates at any time. For more information, see PDF templates.

​
Send a credit note via email

Both draft and issued credit notes can be sent via email. Sending a draft credit note also automatically issues it. To send a credit note to a counterpart via email, call POST /receivables/{credit_note_id}/send and provide the email subject and body text. The language of the email template used is determined by the counterpart’s language. You can also specify additional recipients, CC, and BCC addresses: 
curl -X POST 'https://api.sandbox.tesouro.com/v1/receivables/ad69dc...b52/send' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "subject_text": "Credit note {credit_note_number} from {entity_name}",
       "body_text": "Dear {contact_name},\n\nThank you for your business!\nAs discussed, we are sending you the credit note {credit_note_number} to reduce the amount due on the invoice {based_on_document_id} ({based_on_amount_due}) by {amount_due}.\n For any questions or concerns, please do not hesitate to contact us at {entity_email}. We look forward to serving you again and wish you all the best!",
       "recipients": {
         "to": ["dana@example.com"],
         "cc": ["support@example.com", "sales@example.com"],
         "bcc": ["exec@example.com"]
       }
     }'
The subject_text and body_text fields are email template variables that represent the email subject and body. For more information, see Create and manage email templates.
The To email address is taken from the Counterpart object associated with the credit note. This address is also returned in the counterpart_contact.email field of the Receivable object that represents the credit note. All credit note emails are sent from the noreply@tesouro.com email address by default. You can customize the email domain name—@exampleCompany.com— by configuring a mailbox for the organization. You can also customize the email sender name and username by updating your Tesouro partner settings. A 200 OK response from POST /receivables/{credit_note_id}/send means the email was successfully sent from the Tesouro email server.

​
Resend a credit note

To resend a credit note, you can call POST /receivables/{credit_note_id}/send again, optionally with different subject_text and body_text templates.
Resending a credit note does not change its issued_date.

​
Miscellaneous

​
List all credit notes

To list all credit notes, call GET /receivables?type=credit_note. You can optionally filter the returned results by the credit note status or other parameters.

​
Find all credit notes for an invoice

To get a list of credit notes created for an invoice, call GET /receivables?type=credit_note&based_on=INVOICE_ID: 
curl -X GET 'https://api.sandbox.tesouro.com/v1/receivables?type=credit_note&based_on=INVOICE_ID' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'
The results include both draft and issued credit notes (if any) created for that invoice: 
{
  "data": [
    {
      "type": "credit_note",
      "id": "9c9f4b57-009e-43ef-a784-d0d8ceab2bf2",
      ...
    }
  ],
  "prev_pagination_token": null,
  "next_pagination_token": null
}
Alternatively, if you need just the credit note IDs without other data, examine the related_documents.credit_note_ids field in an invoice:
GET /receivables/{receivable_id}
{
  "type": "invoice",
  ...
  "related_documents": {
    "credit_note_ids": [
      "9c9f4b57-009e-43ef-a784-d0d8ceab2bf2",
      "618e588b-3786-4c09-b251-71b4d49fab66"
    ],
    "proforma_invoice_id": null
  }
}