Retrieve Gift Certificate List: /gift_certificates

Purpose

This API retrieves a paginated list of all gift certificates issued in the system. A gift certificate represents a prepaid credit that can be applied toward outstanding invoices. Each certificate includes financial metadata such as total amount, remaining balance, usage history, and expiry date. The endpoint provides visibility into the lifecycle of gift certificates from issuance to application supporting financial tracking, promotional programs, and payment reconciliation.

Use Case

This endpoint is used to monitor available gift certificates and their balances. It supports workflows such as applying gift certificates as payment methods in the payment module, tracking promotional credits, managing customer or supplier rewards, and auditing transaction history. Developers can integrate this data into dashboards or financial systems to enable real-time visibility and ensure accurate reconciliation across invoices and payments.

Path Parameters

No path parameters for this endpoint.

Query Parameters

*Here, eq = equal, ne = not equal, gt = greater than, ge = greater or equal, lt = less than, le = less or equal.*

Request Body

No data is required for the request body.

Response

On success, the API returns an array containing multiple certificate records, each providing comprehensive details about the gift certificate. Every record includes its current status, such as whether it is active or inactive, along with a unique code that serves as its identifier and the associated accounting code. Financial information is provided through the total amount, the portion already used, and the remaining balance, all expressed in the relevant currency. Each certificate also specifies its expiry date, ensuring clarity on its validity period. Metadata such as the creator, creation timestamp, and any updates are included to maintain accountability and traceability. The structure supports extensibility through custom attributes, while allocations can be tracked if they exist. In addition, each certificate contains a transaction history that details events such as issuance or amendments, with information on transaction type, date, amount, currency, and references. Pagination metadata is also returned, providing the total number of records, the applied limit, the current offset, and navigation links for previous and next pages. This ensures efficient access to gift certificate data and supports full traceability across financial modules.

Response Body

Retrieve Gift Certificate Details: /gift_certificates/{gift_certificate_uuid}

Purpose

This API retrieves comprehensive details of a specific gift certificate using its unique identifier (UUID). A gift certificate represents a prepaid credit that can be applied toward outstanding invoices, and this endpoint provides all key information required to manage or review it. The details include the certificate’s current status, total amount, remaining balance, used amount, currency, expiry date, creator and update metadata, as well as any custom attributes or allocations. It also exposes the full transaction history, ensuring visibility into issuance, debits, and amendments. This makes the endpoint essential for maintaining accurate records and supporting reconciliation processes.

Use Case

This endpoint is used to track the lifecycle of a gift certificate, verify its validity, and confirm its remaining balance before processing a redemption. It is particularly useful for financial teams when reconciling payments, for customer support when validating certificate usage, and for auditing purposes to ensure that all transactions related to the certificate are properly recorded. By providing a complete view of the certificate’s details and history, the endpoint supports operational transparency and financial accuracy.

Path Parameters

Query Parameters

This endpoint does not have any query parameters.

Request Body

No data is required for the request body.

Response

The API returns a gift_certificate object containing a detailed representation of the certificate. This includes metadata such as its status, code, accounting code, currency, expiry date, and creator information with timestamps. Financial data is provided through the total amount, used amount, and remaining balance, while transaction records show the history of events including initial issuance, debits applied, and amendments, each with amounts, dates, and references. Custom attributes and allocations are also included for extensibility, even if empty. This structure ensures that all critical aspects of the gift certificate are accessible for review, reconciliation, and system updates, providing a complete audit trail of its lifecycle.

Response Body

Retrieve Gift Certificate Allocation List: /gift_certificates/{gift_certificate_uuid}/allocations

Purpose

This API retrieves the allocation history of a specific gift certificate identified by its UUID. Allocations represent the connection between a gift certificate and accounts, showing when the certificate was assigned or removed from an account. The endpoint provides details such as the accounts involved, the type of action performed (allocation or deallocation), and the associated timestamps. This ensures that the lifecycle of a gift certificate’s usage across accounts is fully traceable.

Use Case

This endpoint is used to track how a gift certificate has been allocated over time. It helps identify which accounts have been associated with the certificate, when allocations occurred, and when deallocations were made. This information is critical for managing gift certificates across multiple accounts, ensuring accountability, and supporting reconciliation processes. It also provides visibility into the operational flow of certificates, making it easier to audit and validate their usage.

Path Parameters

Query Parameters

This endpoint does not have any query parameters.

Request Body

No data is required for the request body.

Response

On success, the API returns a gift_certificate object containing an allocations array. Each allocation record includes the account identifier, the type of action performed (such as allocate or deallocate), and the date of the action. Pagination metadata is also included, providing the total number of records, applied limit, current offset, and navigation links for previous and next pages. This structure ensures efficient navigation through large datasets and provides a complete audit trail of how the gift certificate has been connected to accounts throughout its lifecycle.

Response Body

Retrieve Gift Certificate Transaction List: /gift_certificates/{gift_certificate_uuid}/transactions

Purpose

This API retrieves the transaction history of a specific gift certificate identified by its UUID. A transaction represents any financial operation performed on the certificate, such as its initial issuance, debits applied when the certificate is used for payments, or amendments that adjust its balance. By exposing these details, the endpoint provides a comprehensive overview of the certificate’s lifecycle and usage, ensuring transparency and accountability in financial management.

Use Case

This endpoint is used to monitor all financial activities associated with a gift certificate. It is particularly useful for tracking how much value has been credited or debited over time, verifying adjustments made through amendments, and ensuring that balances are reconciled accurately. Finance teams can rely on this data for auditing, reporting, and validating the correct application of gift certificates in payment workflows, while developers can integrate it into dashboards for real-time visibility.

Path Parameters

Query Parameters

This endpoint does not have any query parameters.

Request Body

No data is required for the request body.

Response

On success, the API returns a gift_certificate object containing a transactions array. Each transaction record includes the accounting code, transaction type (such as initial issuance, debit, or amend), the date of the transaction, the amount involved, the currency, and any reference details. Pagination metadata is also provided, including the total number of records, applied limit, current offset, and navigation links for previous and next pages. This structure ensures efficient navigation through large transaction histories and provides a complete audit trail of all financial operations performed on the gift certificate.

Response Body