Retrieve Purchase Refund List: /purchase-refunds
Purpose
This API retrieves a paginated list of purchase refunds recorded in the system. A purchase refund represents the return of funds from a supplier credit note, which may occur when a credit note balance is refunded either fully or partially. The endpoint provides detailed information about each refund, including identifiers, status, refund date, payment method, credit note association, creator details, versioning, and any custom attributes. It ensures transparency in refund management and supports efficient handling of large datasets through pagination.
Use Case
This endpoint is used to monitor and reconcile supplier refund transactions against purchase records. It supports workflows such as displaying refund histories in accounting or ERP systems, validating refunds during reconciliation, and generating reports for auditing and financial analysis. The API also enables integration with payment reconciliation or expense management systems, ensuring that refunded amounts are accurately tracked and linked to their originating credit notes.
Path Parameters
This endpoint does not use path parameters.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| limit | int | Number of records to return per request (default: 20). |
| offset | int | Number of records to skip for pagination. |
Request Body
This endpoint does not require a request body.
Response
The response returns two main objects. The first is purchase_refunds, which is an array of refund objects containing detailed information about each purchase refund. Each refund includes metadata such as refund ID, status, refund date, alternate date (for time-zone or local adjustments), refunded amount, reference details, payment method, associated credit note ID, creator and updater information, system timestamps, version, and any custom attributes. The second is pagination, which provides metadata about the result set, including the total number of records, applied limit, current offset, and navigation links for previous and next pages. This structure ensures efficient navigation across large datasets and supports accurate financial reconciliation and reporting.
Response Body
{
"purchase_refund": {
"status": "STATUS",
"id": "PURCHASE_REFUND_ID",
"date": "DATE",
"alternate_date": "ALTERNATE_DATE",
"amount": "AMOUNT",
"reference": "REFERENCE",
"note": "NOTE",
"payment_method": "PAYMENT_METHOD",
"payment_processor": "PAYMENT_PROCESSOR",
"credit_note_id": "CREDIT_NOTE_ID",
"created_by": "CREATED_BY",
"created_on": "CREATED_ON",
"last_updated_by": "LAST_UPDATED_BY",
"last_updated_on": "LAST_UPDATED_ON",
"uuid": "UUID",
"version": "VERSION",
"custom_attributes": []
}
}| Attribute | Type | Description |
|---|---|---|
| status | string | Status of the refund (ACTIVE, INACTIVE). |
| id | string | Unique refund identifier (human-readable). |
| date | string (ISO 8601) | Date and time when the refund was issued. |
| alternate_date | string (ISO 8601) | Alternate localized date for the refund. |
| amount | string | Amount refunded, represented as a decimal string. |
| reference | string | Reference number or code related to the refund (if any). |
| note | string | Additional notes regarding the refund. |
| payment_method | string | Method of payment used for refund (example: Cash, Bank Transfer). |
| payment_processor | string | Processor through which refund was handled (example: Cash, PayPal). |
| credit_note_id | string | Associated credit note ID for the refund. |
| created_by | string | User who created the refund entry. |
| created_on | string (ISO 8601) | Timestamp when refund was created. |
| last_updated_by | string | User who last updated the refund record. |
| last_updated_on | string (ISO 8601) | Timestamp of the last update. |
| uuid | string (UUID) | System-generated unique identifier for the refund. |
| version | string | Version number of the refund record. |
| custom_attributes | array | List of custom attributes associated with the refund (empty if none). |
Retrieve Specific Purchase Refund Details: /purchase-refunds/{purchase_refund_id}
Purpose
This API retrieves detailed information about a single purchase refund using its unique identifier. A purchase refund represents the return of funds from a supplier credit note, which may be processed either as a full refund or a partial refund. The endpoint provides complete metadata related to the refund, including the refunded amount, payment details, associated credit note, timestamps, creator information, and any custom attributes. It ensures transparency and accuracy in refund tracking.
Use Case
This endpoint is used to review the details of a specific purchase refund. It supports workflows such as displaying refund details in dashboards or reports, verifying refund amounts during reconciliation, retrieving refund records for auditing or dispute resolution, and integrating refund data into third-party financial systems. By exposing transaction-level details, the API helps organizations maintain accurate financial records and streamline refund management.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| purchase_refund_id | string | Yes | Unique identifier of the purchase refund. |
Query Parameters
This endpoint does not accept query parameters.
Request Body
This endpoint does not require a request body.
Response
The response returns a single purchase_refund object containing detailed information about the refund. This includes identifiers such as refund ID and UUID, refund amount, reference and note fields, payment method and processor, and the associated credit note ID. Metadata such as status, creator details, timestamps, versioning, and any custom attributes are also included. This structure provides a clear audit trail of the refund transaction, ensuring that refunds are properly recorded and reconciled within the financial system.
Response Body
{
"purchase_refund": {
"status": "STATUS",
"id": "PURCHASE_REFUND_ID",
"date": "DATE",
"alternate_date": "ALTERNATE_DATE",
"amount": "AMOUNT",
"reference": "REFERENCE",
"note": "NOTE",
"payment_method": "PAYMENT_METHOD",
"payment_processor": "PAYMENT_PROCESSOR",
"credit_note_id": "CREDIT_NOTE_ID",
"created_by": "CREATED_BY",
"created_on": "CREATED_ON",
"last_updated_by": "LAST_UPDATED_BY",
"last_updated_on": "LAST_UPDATED_ON",
"uuid": "UUID",
"version": "VERSION",
"custom_attributes": []
}
}| Attribute | Type | Description |
|---|---|---|
| status | string | Status of the refund (ACTIVE, INACTIVE). |
| id | string | Human-readable refund identifier. |
| date | string (ISO 8601) | Date and time when the refund was issued. |
| alternate_date | string (ISO 8601) | Alternate localized date for the refund. |
| amount | string | Amount refunded, represented as a decimal string. |
| reference | string | Reference number or code associated with the refund. |
| note | string | Additional notes about the refund. |
| payment_method | string | Method of payment used (example: Cash, Bank Transfer). |
| payment_processor | string | Payment processor used (example: Cash, PayPal). |
| credit_note_id | string | Identifier of the associated credit note. |
| created_by | string | User who created the refund record. |
| created_on | string (ISO 8601) | Timestamp when refund was created. |
| last_updated_by | string | User who last updated the refund record. |
| last_updated_on | string (ISO 8601) | Timestamp of the last update. |
| uuid | string (UUID) | System-generated unique identifier for the refund. |
| version | string | Version number of the refund record. |
| custom_attributes | array | List of custom attributes related to the refund (empty if none). |
Retrieve Purchase Refund List for an Account: /accounts/{account_id}/purchase-refunds
Purpose
This API retrieves a paginated list of purchase refunds associated with a specific account. It provides refund details such as refund ID, amount, dates, payment details, linked credit note, and metadata like creator, timestamps, and custom attributes.
Use Case
- To fetch all purchase refunds belonging to a specific account.
- To display refunds in customer/account dashboards.
- To reconcile refunds during accounting or auditing processes.
- To integrate account-specific refund records into ERP or financial systems.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| account_id | string | Yes | Unique identifier of the account for which purchase refunds need to be retrieved. |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | int | No | Number of records to return per page (default: 20). |
| offset | int | No | Number of records to skip before starting to return results (default: 0). |
Request Body
This endpoint does not require a request body.
Response
The response returns an account object, which contains a purchase refunds array and pagination details. Each refund record includes its identifier, refund amount, timestamps, references, payment details, linked credit note ID, creator and updater metadata, version, and any associated custom attributes. Pagination ensures that large sets of refund records can be retrieved in multiple requests.
Response Body
{
"account": {
"purchase_refunds": [
{
"status": "STATUS",
"id": "PURCHASE_REFUND_ID",
"date": "DATE",
"alternate_date": "ALTERNATE_DATE",
"amount": "AMOUNT",
"reference": "REFERENCE",
"note": "NOTE",
"payment_method": "PAYMENT_METHOD",
"payment_processor": "PAYMENT_PROCESSOR",
"credit_note_id": "CREDIT_NOTE_ID",
"created_by": "CREATED_BY",
"created_on": "CREATED_ON",
"last_updated_by": "LAST_UPDATED_BY",
"last_updated_on": "LAST_UPDATED_ON",
"uuid": "UUID",
"version": "VERSION",
"custom_attributes": []
}
],
"pagination": {
"records": "RECORDS",
"limit": "LIMIT",
"offset": "OFFSET",
"previous_page": "PREVIOUS_PAGE",
"next_page": "NEXT_PAGE"
}
}
}| Attribute | Type | Description |
|---|---|---|
| status | string | Status of the refund (ACTIVE, INACTIVE). |
| id | string | Human-readable refund identifier. |
| date | string (ISO 8601) | Date and time when the refund was issued. |
| alternate_date | string (ISO 8601) | Alternate localized date for the refund. |
| amount | string | Refund amount, represented as a decimal string. |
| reference | string | Reference number or code associated with the refund. |
| note | string | Additional notes about the refund. |
| payment_method | string | Method of payment used (example: Cash, Bank Transfer). |
| payment_processor | string | Payment processor used (example: Cash, PayPal). |
| credit_note_id | string | Identifier of the associated credit note. |
| created_by | string | User who created the refund record. |
| created_on | string (ISO 8601) | Timestamp when refund was created. |
| last_updated_by | string | User who last updated the refund record. |
| last_updated_on | string (ISO 8601) | Timestamp of the last update. |
| uuid | string (UUID) | System-generated unique identifier for the refund. |
| version | string | Version number of the refund record. |
| custom_attributes | array | List of custom attributes related to the refund (empty if none). |