Purchase Refund Module SDK Documentation

Getting Purchase Refund List

Function: purchase_refund_list()

Purpose

This SDK function retrieves a list of all 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. By calling this function, businesses gain access to comprehensive refund data, enabling them to track reimbursement activities, reconcile financial transactions, and ensure accuracy in refund workflows.

Parameters

No input parameters are required for this function.

Use Case

This function is used to overview of all purchase refunds within the system. It supports workflows such as financial audits, refund trend analysis, and validation that refunds have been correctly recorded after supplier credits are issued. By exposing refund-level details, the function helps ensure consistency and completeness of refund records, aiding in financial management, reconciliation, and customer support operations.

                PYTHON
              

                PHP
              

                      def purchase_refund_list():
    SDKConfig.PRINT_REQUEST_DATA = False
    SDKConfig.PRINT_RAW_RESPONSE = False

    exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(request_token_dto=CommonData.get_request_token_dto())

    try:
        response = exsited_sdk.purchase_refunds.list()
        print("Response:", response)
    except ABException as ab:
        print("Error:", ab)
        print("Error Details:", ab.get_errors())
        print("Raw Response:", ab.raw_response)

                    

                      public function purchaseRefundList()
{
    try {
        $response = $this->purchaseRefundService->readAll('v3');
        echo '<pre>' . json_encode($response, JSON_PRETTY_PRINT) . '</pre>';
    } catch (Exception $e) {
        echo 'Error: ' . $e->getMessage();
    }
}
                    

Response

The response returns a PurchaseRefundsListDTO object containing an array of PurchaseRefundDTO entries. 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, payment processor, associated credit note ID, creator information, timestamps, UUID, version, and any custom attributes. Pagination metadata is also included, providing details about 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.

                Python
              

                PHP
              

                      PurchaseRefundsListDTO(
    purchaseRefunds=[
        PurchaseRefundDTO(
            status="PURCHASE_REFUND_STATUS",
            id="PURCHASE_REFUND_ID",
            date="PURCHASE_REFUND_DATE",
            alternateDate="ALT_PURCHASE_REFUND_DATE",
            amount="PURCHASE_REFUND_AMOUNT",
            reference="PURCHASE_REFUND_REFERENCE",
            note="PURCHASE_REFUND_NOTE",
            paymentMethod="PAYMENT_METHOD",
            paymentProcessor="PAYMENT_PROCESSOR",
            creditNoteId="CREDIT_NOTE_ID",
            createdBy="CREATED_BY",
            createdOn="CREATED_TIMESTAMP",
            lastUpdatedBy="LAST_UPDATED_BY",
            lastUpdatedOn="LAST_UPDATED_TIMESTAMP",
            uuid="PURCHASE_REFUND_UUID",
            version="PURCHASE_REFUND_VERSION",
            customAttributes="CUSTOM_ATTRIBUTES"
        )
    ],
    pagination=PaginationDTO(
        records="TOTAL_RECORDS",
        limit="PAGE_LIMIT",
        offset="PAGE_OFFSET",
        previousPage="PREVIOUS_PAGE_URL",
        nextPage="NEXT_PAGE_URL"
    )
)

                    

                      {
    "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": [
                {
                    "name": "CUSTOM_ATTRIBUTE_NAME_1",
                    "value": "CUSTOM_ATTRIBUTE_VALUE_1"
                }
            ]
        },
        {
            "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": [
                {
                    "name": "CUSTOM_ATTRIBUTE_NAME_1",
                    "value": "CUSTOM_ATTRIBUTE_VALUE_1"
                }
            ]
        }
    ],
    "pagination": {
        "records": "PAGINATION_RECORDS",
        "limit": "PAGINATION_LIMIT",
        "offset": "PAGINATION_OFFSET",
        "previous_page": "PREVIOUS_PAGE",
        "next_page": "NEXT_PAGE"
    }
}

                    

Getting Specific Purchase Refund Details

Function: purchase_refund_details()

Purpose

This SDK function retrieves detailed information about a specific 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 function provides complete metadata about the refund, including its status, refunded amount, payment details, associated credit note, timestamps, creator information, and any custom attributes. It ensures accuracy and transparency in refund tracking.

Parameters

Parameter	Type	Description
purchase_refund_id	String	The unique identifier of the purchase refund.

Use Case

This function is used to review the details of a particular purchase refund. It supports workflows such as confirming the refund amount, verifying its current status 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 function ensures traceability and supports accurate financial management.

                PYTHON
              

                PHP
              

                      def purchase_refund_details():
    SDKConfig.PRINT_REQUEST_DATA = False
    SDKConfig.PRINT_RAW_RESPONSE = False

    exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(request_token_dto=CommonData.get_request_token_dto())

    try:
        response = exsited_sdk.purchase_refunds.details(id="REFUND_ID")
        print("Response:", response)
        return response
    except ABException as ab:
        print("Error:", ab)
        print("Error Details:", ab.get_errors())
        print("Raw Response:", ab.raw_response)

                    

                      public function purchaseRefundDetails()
{
    $id = "REFUND_ID";
    try {
        $response = $this->purchaseRefundService->readDetails($id, 'v3');
        echo '<pre>' . json_encode($response, JSON_PRETTY_PRINT) . '</pre>';
    } catch (Exception $e) {
        echo 'Error: ' . $e->getMessage();
    }
}

                    

Response

The response returns a PurchaseRefundsDetailsDTO object containing a single PurchaseRefundDTO. This object 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.

                PYTHON
              

                PHP
              

                      PurchaseRefundsDetailsDTO(
    purchaseRefund=PurchaseRefundDTO(
        status='STATUS',
        id='PURCHASE_REFUND_ID',
        date='DATE',
        alternateDate='ALTERNATE_DATE',
        amount='AMOUNT',
        reference='REFERENCE',
        note='NOTE',
        paymentMethod='PAYMENT_METHOD',
        paymentProcessor='PAYMENT_PROCESSOR',
        creditNoteId='CREDIT_NOTE_ID',
        createdBy='CREATED_BY',
        createdOn='CREATED_ON',
        lastUpdatedBy='LAST_UPDATED_BY',
        lastUpdatedOn='LAST_UPDATED_ON',
        uuid='UUID',
        version='VERSION',
        customAttributes=[
            {
                'name': 'CUSTOM_ATTRIBUTE_NAME_1',
                'value': 'CUSTOM_ATTRIBUTE_VALUE_1'
            },
            {
                'name': 'CUSTOM_ATTRIBUTE_NAME_2',
                'value': 'CUSTOM_ATTRIBUTE_VALUE_2'
            },
            {
                'name': 'CUSTOM_ATTRIBUTE_NAME_3',
                'value': 'CUSTOM_ATTRIBUTE_VALUE_3'
            },
            {
                'name': 'CUSTOM_ATTRIBUTE_NAME_4',
                'value': 'CUSTOM_ATTRIBUTE_VALUE_4'
            },
            {
                'name': 'CUSTOM_ATTRIBUTE_NAME_5',
                'value': 'CUSTOM_ATTRIBUTE_VALUE_5'
            },
            {
                'name': 'CUSTOM_ATTRIBUTE_NAME_6',
                'value': 'CUSTOM_ATTRIBUTE_VALUE_6'
            },
            {
                'name': 'CUSTOM_ATTRIBUTE_NAME_7',
                'value': 'CUSTOM_ATTRIBUTE_VALUE_7'
            },
            {
                'name': 'CUSTOM_ATTRIBUTE_NAME_8',
                'value': 'CUSTOM_ATTRIBUTE_VALUE_8'
            },
            {
                'name': 'CUSTOM_ATTRIBUTE_NAME_9',
                'value': 'CUSTOM_ATTRIBUTE_VALUE_9'
            },
            {
                'name': 'CUSTOM_ATTRIBUTE_NAME_10',
                'value': 'CUSTOM_ATTRIBUTE_VALUE_10'
            },
            {
                'name': 'CUSTOM_ATTRIBUTE_NAME_11',
                'value': 'CUSTOM_ATTRIBUTE_VALUE_11'
            },
            {
                'name': 'CUSTOM_ATTRIBUTE_NAME_12',
                'value': 'CUSTOM_ATTRIBUTE_VALUE_12'
            },
            {
                'name': 'CUSTOM_ATTRIBUTE_NAME_13',
                'value': 'CUSTOM_ATTRIBUTE_VALUE_13'
            }
        ]
    )
)

                    

                      {
    "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": [
            {
                "name": "CUSTOM_ATTRIBUTE_NAME_1",
                "value": "CUSTOM_ATTRIBUTE_VALUE_1"
            }
        ]
    }

                    

Getting Purchase Refund List for an Specific Account

Function: purchase_refund_list_account()

Purpose

This function retrieves the purchase refund details associated with a specific account using the account's unique identifier (ID). It provides insights into the refunds tied to an account, including refund amounts, statuses, and related purchase information, enabling accurate financial tracking and account management.

Parameters

Parameter	Type	Description
account_id	String	The unique identifier of the account for which purchase refunds need to be retrieved.

Use Case

Use this function when you need to fetch all refund details linked to a specific account. This is particularly useful for account audits, tracking refunds issued to customers, or reconciling account-level refund transactions with financial records.

                PYTHON
              

                PHP
              

                      def purchase_refund_list_account():
    SDKConfig.PRINT_REQUEST_DATA = False
    SDKConfig.PRINT_RAW_RESPONSE = False

    exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(request_token_dto=CommonData.get_request_token_dto())

    try:
        response = exsited_sdk.purchase_refunds.account_details(id="ACCOUNT_ID")
        print("Response:", response)
        return response
    except ABException as ab:
        print("Error:", ab)
        print("Error Details:", ab.get_errors())
        print("Raw Response:", ab.raw_response)

                    

                      public function purchaseRefundListAccount()
{
    $accountId = "ACCOUNT_ID";
    try {
        $response = $this->purchaseRefundService->readAccountPurchaseRefunds($accountId, 'v3');
        echo '<pre>' . json_encode($response, JSON_PRETTY_PRINT) . '</pre>';
    } catch (Exception $e) {
        echo 'Error: ' . $e->getMessage();
    }
}

                    

                PYTHON
              

                PHP
              

                      PurchaseRefundsAccountDetailsDTO(
    account=PurchaseRefundsListDTO(
        purchaseRefunds=[
            PurchaseRefundDTO(
                status='STATUS',
                id='PURCHASE_REFUND_ID',
                date='DATE',
                alternateDate='ALTERNATE_DATE',
                amount='AMOUNT',
                reference='REFERENCE',
                note='NOTE',
                paymentMethod='PAYMENT_METHOD',
                paymentProcessor='PAYMENT_PROCESSOR',
                creditNoteId='CREDIT_NOTE_ID',
                createdBy='CREATED_BY',
                createdOn='CREATED_ON',
                lastUpdatedBy='LAST_UPDATED_BY',
                lastUpdatedOn='LAST_UPDATED_ON',
                uuid='UUID',
                version='VERSION',
                customAttributes=[
                    {
                        'name': 'ATTRIBUTE_NAME_1',
                        'value': 'ATTRIBUTE_VALUE_1'
                    },
                    {
                        'name': 'ATTRIBUTE_NAME_2',
                        'value': 'ATTRIBUTE_VALUE_2'
                    },
                    {
                        'name': 'ATTRIBUTE_NAME_3',
                        'value': 'ATTRIBUTE_VALUE_3'
                    },
                    {
                        'name': 'ATTRIBUTE_NAME_4',
                        'value': 'ATTRIBUTE_VALUE_4'
                    },
                    {
                        'name': 'ATTRIBUTE_NAME_5',
                        'value': 'ATTRIBUTE_VALUE_5'
                    },
                    {
                        'name': 'ATTRIBUTE_NAME_6',
                        'value': 'ATTRIBUTE_VALUE_6'
                    },
                    {
                        'name': 'ATTRIBUTE_NAME_7',
                        'value': 'ATTRIBUTE_VALUE_7'
                    },
                    {
                        'name': 'ATTRIBUTE_NAME_8',
                        'value': 'ATTRIBUTE_VALUE_8'
                    },
                    {
                        'name': 'ATTRIBUTE_NAME_9',
                        'value': 'ATTRIBUTE_VALUE_9'
                    },
                    {
                        'name': 'ATTRIBUTE_NAME_10',
                        'value': 'ATTRIBUTE_VALUE_10'
                    },
                    {
                        'name': 'ATTRIBUTE_NAME_11',
                        'value': 'ATTRIBUTE_VALUE_11'
                    },
                    {
                        'name': 'ATTRIBUTE_NAME_12',
                        'value': 'ATTRIBUTE_VALUE_12'
                    },
                    {
                        'name': 'ATTRIBUTE_NAME_13',
                        'value': 'ATTRIBUTE_VALUE_13'
                    },
                    {
                        'name': 'ATTRIBUTE_NAME_14',
                        'value': 'ATTRIBUTE_VALUE_14'
                    }
                ]
            )
        ],
        pagination=PaginationDTO(
            records='TOTAL_RECORDS',
            limit='LIMIT',
            offset='OFFSET',
            previousPage='PREVIOUS_PAGE',
            nextPage='NEXT_PAGE'
        )
    )
)


                    

                      {
    "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": [
                    {
                        "name": "CUSTOM_ATTRIBUTE_NAME",
                        "value": "CUSTOM_ATTRIBUTE_VALUE"
                    }
                ]
            }
        ],
        "pagination": {
            "records": "RECORDS",
            "limit": "LIMIT",
            "offset": "OFFSET",
            "previous_page": "PREVIOUS_PAGE",
            "next_page": "NEXT_PAGE"
        }
    },
    
                    

Deleting Purchase Refund

Function: purchase_refund_delete()

Purpose

This API deletes an existing purchase refund record from the system. A purchase refund represents a transaction where funds are returned to the buyer for previously purchased goods or services. Using this endpoint, users can permanently remove a refund record that is no longer required or was created in error. Once deleted, the purchase refund will no longer appear in listings or reports, ensuring that only valid refund transactions remain in the system. This helps maintain accurate financial data and reduces clutter in refund records.

Parameters

parameter	type	description
purchase_refund_id	string	Unique identifier of the purchase refund record to be deleted.

Use Case

This API is typically used when a purchase refund was created incorrectly, duplicated, or needs to be removed from the system after a reconciliation or audit process. For example, a finance manager may identify an erroneous refund entry during an accounting review and use this API to delete it. The API ensures that no refund data remains once deleted, providing a clean and accurate view of financial transactions. The following code snippets demonstrate how to delete a purchase refund record using both Python and PHP SDKs.

                PYTHON
              

                PHP
              

                      def purchase_refund_delete():
    SDKConfig.PRINT_REQUEST_DATA = True
    SDKConfig.PRINT_RAW_RESPONSE = False

    token_file_path = "shared_token.json"
    file_token_mgr = FileTokenManager(token_file_path)

    exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(
        request_token_dto=CommonData.get_request_token_dto(),
        file_token_mgr=file_token_mgr
    )

    try:
        response = exsited_sdk.purchase_refunds.delete(id='{{purchase_refund_id_placeholder}}')
        print(response)
        return response
    except ABException as ab:
        print(ab)
        print(ab.get_errors())
        print(ab.raw_response)

                    

                      public function deletePurchaseRefund()
{
    $id = "{{purchase_refund_id}}";
    try {
        $response = $this->purchaseRefundService->delete($id, 'v3');
        echo '<pre>' . json_encode($response, JSON_PRETTY_PRINT) . '</pre>';
    } catch (Exception $e) {
        echo 'Error: ' . $e->getMessage();
    }
}

                    

                PYTHON
              
                PHP
              
                      {
    "success": true,
    "status_code": 204
}

                      {
    "success": true,
    "status_code": 204
}