Credit Note GET API Documentation

Purpose

This endpoint retrieve credit note information associated with a specific account or order, identified by its unique ID. Credit note in the system are generated when excess payment is made through any payment processor for an order, and the extra payment is recorded as a credit note for future adjustments or refunds.

Use Case

The endpoint is used to retrieve detailed information about credit note for financial reconciliation, reporting, or refund processing. If a customer has overpaid on an order, these extra funds appear as credit notes, and this API can be used by finance teams or administrators to view the status, amount, balance, and related transactions of these credits.

Path Parameters

Parameter	Type	Description
credit_note_id	String	The unique identifier used to fetch related credit notes.

Query Parameters

This endpoint does not have any query parameters.

Request Body

No request body is required for this endpoint.

Response

The API returns credit note details such as status, credit note ID, date, amount, associated invoice and payment IDs, remaining balance, refund eligibility, custom attributes, and audit metadata.

Response Body

                JSON
              

                      {
    "credit_note": {
        "status": "STATUS",
        "id": "CREDIT_NOTE_ID",
        "date": "TIMESTAMP",
        "amount": "NUMBER",
        "invoice_id": "INVOICE_ID",
        "remaining_balance": "NUMBER",
        "refundable": "BOOLEAN",
        "payment_id": "PAYMENT_ID",
        "custom_attributes": [
            {
                "name": "ATTRIBUTE_NAME",
                "value": "EMPTY"
            }
        ],
        "custom_objects": [],
        "version": "VERSION",
        "created_by": "CREATED_BY",
        "created_on": "TIMESTAMP",
        "updated_by": "EMPTY",
        "updated_on": "EMPTY",
        "uuid": "UUID",
        "account_id": "ACCOUNT_ID"
    }
}
                    

Attribute	Type	Description
status	String	Current status of the credit note (example: ACTIVE).
id	String	The unique credit note identifier.
date	String	Date of credit note creation (ISO 8601 format).
amount	String	Total amount of the credit note.
invoice_id	String	The ID of the invoice linked to the credit note.
remaining_balance	String	The unused portion of the credit note amount.
refundable	String	Indicates if the credit note is eligible for refund.
payment_id	String	ID of the payment related to this credit note.
custom_attributes	Array	List of custom attribute name-value pairs.
custom_objects	Array	Custom object data related to the credit note.
version	String	Version number of the credit note record.
created_by	String	Name or identifier of the user who created the credit note.
created_on	String	Timestamp of when the credit note was created (ISO 8601).
updated_by	String	Name or identifier of the user who last updated the credit note.
updated_on	String	Timestamp of the last update (ISO 8601).
uuid	String	Universally unique identifier of the credit note.
account_id	String	The account associated with the credit note.

Purpose

The endpoint retrieves a list of credit note application details, showing how credit notes have been applied to payments or refunds. Each record provides the date of application, the amount applied, the related credit note and payment IDs, any remaining balance, and creation metadata. This allows tracking of how credit notes are utilized over time for financial reconciliation.

Use Case

This endpoint is used to monitor the usage of credit notes in transactions. For example, when a customer makes a new order and chooses to pay using an existing credit note, the application of that credit note is recorded here. This helps finance teams understand how credit balances are reduced and track any remaining amounts available.

Path Parameters

No request body is required for this endpoint.

Query Parameters

Parameter	Type	Description
limit	Integer	Maximum number of records to return per page.
offset	Integer	Number of records to skip before starting to return results.

Request Body

No request body is required for this endpoint.

Response

The endpoint returns a list of credit note application records, each containing details about the applied amount, associated credit note and payment, remaining balance, and metadata such as creation date and user. The response also includes pagination data for navigating large datasets.

Response Body

                JSON
              

                      {
    "credit_note_applications": [
        {
            "date": "TIMESTAMP",
            "amount": "NUMBER",
            "credit_note_id": "CREDIT_NOTE_ID",
            "payment_id": "PAYMENT_ID",
            "refund_id": "EMPTY",
            "remaining_balance": "NUMBER",
            "created_by": "CREATED_BY",
            "created_on": "TIMESTAMP",
            "uuid": "UUID",
            "version": "VERSION"
        },
        {
            "date": "TIMESTAMP",
            "amount": "NUMBER",
            "credit_note_id": "CREDIT_NOTE_ID",
            "payment_id": "PAYMENT_ID",
            "refund_id": "EMPTY",
            "remaining_balance": "NUMBER",
            "created_by": "CREATED_BY",
            "created_on": "TIMESTAMP",
            "uuid": "UUID",
            "version": "VERSION"
        }
    ],
    "pagination": {
        "records": "NUMBER",
        "limit": "NUMBER",
        "offset": "NUMBER",
        "previous_page": "URL",
        "next_page": "URL"
    }
}
                    

Attribute	Type	Description
credit_note_applications	Array	List of credit note application records.
date	String (ISO 8601)	Date when the credit note was applied.
amount	String	Amount of credit applied.
credit_note_id	String	Unique ID of the credit note.
payment_id	String	Payment ID to which the credit note was applied.
refund_id	String	Refund ID if the credit was applied to a refund.
remaining_balance	String	Remaining balance on the credit note after application.
created_by	String	User who created the application record.
created_on	String (ISO 8601)	Date and time when the record was created.
uuid	String (UUID)	Unique identifier for the credit note application record.
version	String	Record version number.
pagination	Object	Contains pagination information.
records	Integer	Total number of records available.
.limit	Integer	Number of records per page.
offset	Integer	Number of records skipped.
previous_page	String (URL)	URL for the previous page of results.
next_page	String (URL)	URL for the next page of results.

Purpose

The endpoint retrieves detailed information for a specific credit note application, including applied amount, remaining balance, and associated payment or refund details.

Use Case

This endpoint is used to fetch complete details of a specific credit note application for auditing, reporting, or financial reconciliation purposes. For example, finance teams can use this information to verify how much of a credit note has been applied to a payment, what remains unused, and who created the application record.

Path Parameters

Parameter	Type	Description
credit_note_application_uuid	String	Unique identifier of the credit note application to retrieve.

Query Parameters

This endpoint does not have any query parameters.

Request Body

No request body is required for this endpoint.

Response

The function returns detailed information about a specific credit note application. The response includes the application date, amount applied, credit note ID, associated payment or refund IDs, remaining balance, creator details, creation date, unique identifier, and version number.

Response Body

                JSON
              

                      {
    "credit_note_application": {
        "date": "TIMESTAMP",
        "amount": "NUMBER",
        "credit_note_id": "CREDIT_NOTE_ID",
        "payment_id": "PAYMENT_ID",
        "refund_id": "EMPTY",
        "remaining_balance": "NUMBER",
        "created_by": "CREATED_BY",
        "created_on": "TIMESTAMP",
        "uuid": "UUID",
        "version": "VERSION"
    }
}
                    

Attribute	Type	Description
date	String	Date the credit note was applied (ISO 8601 format).
amount	String	Amount of the credit note applied in this record.
credit_note_id	String	Unique identifier of the credit note.
payment_id	String	Associated payment ID if applied to a payment.
refund_id	String	Associated refund ID if applied to a refund. Empty if not applicable.
remaining_balance	String	Remaining unused balance of the credit note.
created_by	String	Name of the user who created the credit note application.
created_on	String	Date and time when the record was created (ISO 8601 format).
uuid	String	Unique identifier of the credit note application record.
version	String	Version number of the record.

Purpose

This endpoint retrieves a list of credit note applications applied to a specific invoice. It provides detailed records of applied credit notes, including amount, payment linkage, remaining balance, and audit information, along with pagination details for navigation.

Use Case

This API is used to track how credit notes have been applied against a given invoice. It helps finance teams, billing systems, or auditors verify invoice settlements, monitor applied credit amounts, and maintain an accurate balance of outstanding invoices.

Path Parameters

Parameter	Type	Description
invoice_id	String	Unique identifier of the invoice for which credit note applications are being retrieved.

Query Parameters

Parameter	Type	Description
limit	Integer	Maximum number of records to return per page.
offset	Integer	Number of records to skip before starting to return results.

Request Body

No request body is required for this endpoint.

Response

The API endpoint response contains the invoice object, which includes an array of applied credit notes and pagination information. Each credit note application record provides details such as applied amount, credit note ID, linked payment ID, refund reference (if any), remaining balance, and audit fields like created by, created on, and version.

Response Body

                JSON
              

                      {
    "invoice": {
        "credit_note_applications": [
            {
                "date": "TIMESTAMP",
                "amount": "NUMBER",
                "credit_note_id": "CREDIT_NOTE_ID",
                "payment_id": "PAYMENT_ID",
                "refund_id": "EMPTY",
                "remaining_balance": "NUMBER",
                "created_by": "CREATED_BY",
                "created_on": "TIMESTAMP",
                "uuid": "UUID",
                "version": "VERSION"
            },
            {
                "date": "TIMESTAMP",
                "amount": "NUMBER",
                "credit_note_id": "CREDIT_NOTE_ID",
                "payment_id": "PAYMENT_ID",
                "refund_id": "EMPTY",
                "remaining_balance": "NUMBER",
                "created_by": "CREATED_BY",
                "created_on": "TIMESTAMP",
                "uuid": "UUID",
                "version": "VERSION"
            },
            {
                "date": "TIMESTAMP",
                "amount": "NUMBER",
                "credit_note_id": "CREDIT_NOTE_ID",
                "payment_id": "PAYMENT_ID",
                "refund_id": "EMPTY",
                "remaining_balance": "NUMBER",
                "created_by": "CREATED_BY",
                "created_on": "TIMESTAMP",
                "uuid": "UUID",
                "version": "VERSION"
            }
        ],
        "pagination": {
            "records": "NUMBER",
            "limit": "NUMBER",
            "offset": "NUMBER",
            "previous_page": "EMPTY",
            "next_page": "NULL"
        }
    }
}
                    

Attribute	Type	Description
date	String	Date when the credit note was applied.
amount	String	Amount of the credit note applied.
credit_note_id	String	Identifier of the credit note used.
payment_id	String	Identifier of the payment linked with the credit note application.
refund_id	String	Identifier of the refund if applicable.
remaining_balance	String	Remaining balance of the invoice after applying the credit note.
created_by	String	Name of the user who created the credit note application.
created_on	String	Timestamp when the credit note application was created.
uuid	String	Unique identifier of the credit note application record.
version	String	Version of the credit note application record.
records	Integer	Total number of credit note applications.
limit	Integer	Maximum number of records returned per page.
offset	Integer	Number of records skipped before starting to return results.
previous_page	String	Link to the previous page of results, if available.
next_page	String	Link to the next page of results, if available.

Purpose

This API retrieves a paginated list of credit notes associated with various customer accounts within the Exsited platform. Each credit note represents a financial adjustment or refund linked to an invoice and payment. It provides a comprehensive overview of credit notes, including their current status, issued date, amounts, remaining balances, and account-level ownership details. This endpoint supports pagination and can be filtered using query parameters for efficient retrieval in large datasets.

Use Case

Retrieve all existing credit notes across multiple customer accounts.
Display credit note records in account dashboards or financial summaries.
Reconcile invoices, payments, and refunds by linking credit note data.
Generate accounting or reporting views for active and refundable credit notes.
Support automation workflows that process pending balances or issue adjustments based on credit note information.

Path Parameters

No path parameters required for this endpoint.

Query Parameters

Parameter	Type	Description
limit	integer	The maximum number of records to return per page. Default is 20.
offset	integer	The number of records to skip before starting to return results (used for pagination).
sort	string	Field name by which results should be sorted (optional).
order	string	Sorting order, either asc or desc (optional).
status	string	Filter by credit note status.

Request Body

This endpoint does not require a request body.

Response

On success, the API returns a paginated list of credit notes along with their financial and audit metadata. Each credit note contains details such as the unique ID, status, issued date, amount, remaining balance, linked invoice and payment identifiers, refund eligibility, and creator information. Pagination details are included to help navigate through large datasets. If no records match the provided query filters, an empty list will be returned with pagination metadata intact.

Response Body

                JSON
              

                      {
  "credit_notes": [
    {
      "status": "{{status}}",
      "id": "{{credit_note_id}}",
      "date": "{{date}}",
      "amount": "{{amount}}",
      "invoice_id": "{{invoice_id}}",
      "remaining_balance": "{{remaining_balance}}",
      "refundable": "{{refundable_flag}}",
      "payment_id": "{{payment_id}}",
      "custom_attributes": [],
      "custom_objects": [],
      "version": "{{version}}",
      "created_by": "{{created_by}}",
      "created_on": "{{created_on}}",
      "updated_by": "{{updated_by}}",
      "updated_on": "{{updated_on}}",
      "uuid": "{{uuid}}",
      "account_id": "{{account_id}}"
    }
  ],
  "pagination": {
    "records": "{{total_records}}",
    "limit": "{{page_limit}}",
    "offset": "{{page_offset}}",
    "previous_page": "{{previous_page_url}}",
    "next_page": "{{next_page_url}}"
  }
}

                    

Attribute	Type	Description
status	string	Current state of the credit note (example: ACTIVE, INACTIVE).
id	string	The unique identifier of the credit note, usually following a formatted sequence.
date	string	The date the credit note was issued (in ISO 8601 format).
amount	string	The total amount of the credit note.
invoice_id	string	The ID of the invoice associated with this credit note.
remaining_balance	string	The remaining refundable balance amount on this credit note.
refundable	string	Indicates whether the credit note is eligible for refund (true or false).
payment_id	string	The ID of the payment transaction linked to this credit note.
custom_attributes	array	List of user-defined custom attributes applied to the credit note.
custom_objects	array	List of user-defined custom objects linked to the credit note.
version	string	The current version number of the credit note record.
created_by	string	Name of the user who created the credit note.
created_on	string	Timestamp when the credit note was created (ISO 8601 format).
updated_by	string	Name of the user who last updated the credit note, if any.
updated_on	string	Timestamp when the credit note was last updated (ISO 8601 format).
uuid	string	The system-generated unique identifier (UUID) for the credit note record.
account_id	string	The unique account identifier to which this credit note belongs.

Retrieve Specific Credit Note: /credit-notes/{credit_note_id}

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response

Response Body

Retrieve Credit Note Applications : /credit-note-applications

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response

Response Body

Retrieve Specific Credit Note Application: /credit-note-applications/{credit_note_application_uuid}

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response

Response Body

Retrieve Credit Note Applications for an Invoice: /invoices/{invoice_id}/credit-note-applications

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response

Response Body

Retrieve Credit Notes: /credit-notes

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response

Response Body