Endpoint: GET /api/v3/gift_certificates
Purpose
Retrieve a list of gift certificates, including their details, status, balance, allocations, and transaction history. This endpoint is useful for tracking issued gift certificates and their usage.
Use Case
To view available gift certificates and their balances for managing customer rewards, promotional activities, or internal tracking.
Path Parameters
No path parameters for this endpoint.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| limit | Integer | Specifies the maximum number of payment records to return in the response. |
| order_by | String | Determines the sort order; use asc for ascending or desc for descending. |
| offset | Integer | Defines the starting point for retrieving records, used for pagination. |
Request
No data is required for the request body.
Response
Provides detailed information about each gift certificate, including its status, amount, remaining balance, transactions, and associated allocations.
{
"gift_certificates": [
{
"status": "GIFT_CERTIFICATE_STATUS",
"accounting_code": "ACCOUNTING_CODE",
"code": "GIFT_CERTIFICATE_CODE",
"amount": "TOTAL_AMOUNT",
"remaining_balance": "REMAINING_BALANCE",
"used_amount": "USED_AMOUNT",
"currency": "CURRENCY_CODE",
"expiry_date": "YYYY-MM-DDTHH:MM:SSZ",
"created_by": "CREATED_BY",
"created_on": "YYYY-MM-DDTHH:MM:SSZ",
"last_updated_by": "UPDATED_BY",
"last_updated_on": "YYYY-MM-DDTHH:MM:SSZ",
"uuid": "GIFT_CERTIFICATE_UUID",
"custom_attributes": [
{
"name": "ATTRIBUTE_NAME",
"value": "ATTRIBUTE_VALUE"
}
],
"allocations": [
{
"account": "ACCOUNT_ID",
"type": "ALLOCATION_TYPE",
"date": "YYYY-MM-DDTHH:MM:SSZ"
}
],
"transactions": [
{
"accounting_code": "TRANSACTION_ACCOUNTING_CODE",
"type": "TRANSACTION_TYPE",
"date": "YYYY-MM-DDTHH:MM:SSZ",
"amount": TRANSACTION_AMOUNT,
"currency": "TRANSACTION_CURRENCY",
"reference": "TRANSACTION_REFERENCE"
}
]
}
],
"pagination": {
"records": TOTAL_RECORDS,
"limit": LIMIT,
"offset": OFFSET,
"previous_page": "PREVIOUS_PAGE_URL",
"next_page": "NEXT_PAGE_URL"
}
}
Endpoint: GET /api/v3/gift_certificates/{uuid}
Purpose
Retrieve comprehensive details of a specific gift certificate using its unique identifier (UUID). The endpoint provides key information such as the status, balance, expiry date, custom attributes, allocations, and transaction history. This ensures that the details are readily available for managing or reviewing gift certificates.
Use Case
Businesses can use this endpoint to track the lifecycle of a gift certificate, verify its validity, or check its remaining balance before processing a redemption.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| uuid | String | Unique identifier of the gift certificate. |
Request
No data is required for the request body.
Response
The response returns a detailed representation of the gift certificate, including metadata (status, creation details), financial data (amount, balance, and transactions), and associated custom attributes. This structure ensures all critical aspects of the certificate are accessible for review or system updates.
{
"gift_certificate": {
"status": "GIFT_CERTIFICATE_STATUS",
"accounting_code": "ACCOUNTING_CODE",
"code": "GIFT_CERTIFICATE_CODE",
"amount": "GIFT_CERTIFICATE_AMOUNT",
"remaining_balance": "REMAINING_BALANCE",
"used_amount": "USED_AMOUNT",
"currency": "CURRENCY_CODE",
"expiry_date": "YYYY-MM-DDTHH:MM:SSZ",
"created_by": "CREATOR_NAME",
"created_on": "YYYY-MM-DDTHH:MM:SSZ",
"last_updated_by": "LAST_UPDATED_BY",
"last_updated_on": "YYYY-MM-DDTHH:MM:SSZ",
"uuid": "UUID-PLACEHOLDER",
"custom_attributes": [
{
"name": "ATTRIBUTE_NAME",
"value": "ATTRIBUTE_VALUE"
}
],
"allocations": [
{
"account": "ACCOUNT_ID",
"type": "ALLOCATION_TYPE",
"date": "YYYY-MM-DDTHH:MM:SSZ"
}
],
"transactions": [
{
"accounting_code": "ACCOUNTING_CODE",
"type": "TRANSACTION_TYPE",
"date": "YYYY-MM-DDTHH:MM:SSZ",
"amount": "TRANSACTION_AMOUNT",
"currency": "CURRENCY_CODE",
"reference": "REFERENCE_PLACEHOLDER"
}
]
}
}
Endpoint: GET /api/v3/gift_certificates/{uuid}/allocations
Purpose
Retrieve the allocation history of a specific gift certificate identified by its UUID. This includes details on accounts to which the certificate was allocated or deallocated, along with the associated dates.
Use Case
Businesses can use this endpoint to track the allocation lifecycle of a gift certificate, such as identifying which accounts have been associated with it and when deallocations occurred for better management and accountability.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| uuid | String | Unique identifier of the gift certificate. |
Request
No data is required for the request body.
Response
Returns a detailed list of allocation actions performed on the gift certificate, including account identifiers, action types (e.g., allocate or deallocate), and the associated timestamps. Pagination details are included to navigate through large datasets.
{
"gift_certificate": {
"allocations": [
{
"account": "ACCOUNT_ID",
"type": "ALLOCATE_OR_DEALLOCATE",
"date": "YYYY-MM-DDTHH:MM:SSZ"
}
],
"pagination": {
"records": "NUMBER_OF_RECORDS",
"limit": "LIMIT",
"offset": "OFFSET",
"previous_page": "PREVIOUS_PAGE",
"next_page": "NEXT_PAGE"
}
}
}
Endpoint: GET /api/v3/gift_certificates/{uuid}/transactions
Purpose
Retrieve the transaction history of a specific gift certificate identified by its UUID. This includes all financial operations such as initial issuance, debits, and amendments, providing a comprehensive overview of the certificate's usage.
Use Case
Use this endpoint to monitor all financial activities associated with a gift certificate. For example, businesses can track how much has been credited or debited, ensuring accurate accounting and transparency.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| uuid | String | Unique identifier of the gift certificate. |
Request
No data is required for the request body.
Response
Returns the complete transaction history of the gift certificate, including transaction types (e.g., initial, debit, amend), amounts, currencies, and timestamps. Pagination metadata is included for managing large transaction histories.
{
"gift_certificate": {
"transactions": [
{
"accounting_code": "ACCOUNTING_CODE",
"type": "TRANSACTION_TYPE",
"date": "YYYY-MM-DDTHH:MM:SSZ",
"amount": "TRANSACTION_AMOUNT",
"currency": "CURRENCY_CODE",
"reference": "REFERENCE"
}
],
"pagination": {
"records": "NUMBER_OF_RECORDS",
"limit": "LIMIT",
"offset": "OFFSET",
"previous_page": "PREVIOUS_PAGE",
"next_page": "NEXT_PAGE"
}
}
}