Retrieve Gift Certificate List: /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
| Category | Parameter / Field | Type | Operators | Description | Example |
|---|---|---|---|---|---|
| Sorting | order_by | string | – | Field name to sort results. | order_by=code |
| direction | string | – | Sorting direction. Accepts asc or desc. | direction=desc | |
| Pagination | limit | integer | – | Number of records per page. | limit=25 |
| offset | integer | – | Records to skip from the start. | offset=0 | |
| Filtering | status | constant | eq, ne | Filter by gift certificate status. | gift_certificates/status eq 'ACTIVE' |
| accounting_code | string | eq, ne, contain, not_contain | Filter by accounting code. | gift_certificates/accounting_code eq 'ACCT-5001' | |
| code | string | eq, ne, contain, not_contain | Filter by certificate code. | gift_certificates/code eq 'GFT-2025-001' | |
| currency | string | eq, ne, contain, not_contain | Filter by currency type. | gift_certificates/currency eq 'USD' | |
| created_by | string | eq, ne | Filter by creator of the certificate. | gift_certificates/created_by eq 'system_admin' | |
| created_on | date | eq, ne, gt, ge, lt, le | Filter by creation date. Date format: 'yyyy-mm-dd' |
gift_certificates/created_on gt '2025-01-01' | |
| last_updated_by | string | eq, ne | Filter by user who last updated. | gift_certificates/last_updated_by eq 'finance_manager' | |
| last_updated_on | date | eq, ne, gt, ge, lt, le | Filter by last update date. Date format: 'yyyy-mm-dd' |
gift_certificates/last_updated_on le '2025-09-01' | |
| uuid | string | eq, ne, contain, not_contain | Filter by certificate UUID. | gift_certificates/uuid eq 'ab12cd34-5678-90ef-gh12-3456ijkl7890' |
Request Body
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.
Response Body
{
"gift_certificates": [
{
"status": "ACTIVE",
"accounting_code": "Gift Certificate",
"code": "GC-0001",
"amount": "200.00000",
"remaining_balance": "200.00000",
"used_amount": "0.00000",
"currency": "AUD",
"expiry_date": "2025-08-10T10:00:00Z",
"created_by": "",
"created_on": "2025-08-07T08:04:49Z",
"last_updated_by": "",
"last_updated_on": "2025-08-07T08:04:49Z",
"uuid": "f6ff3efc-80b9-4a6a-9ea7-d10132af84e6",
"custom_attributes": [],
"allocations": [],
"transactions": [
{
"accounting_code": "Gift Certificate",
"type": "INITIAL",
"date": "2025-08-07 08:04:50.000000",
"amount": 200.00000,
"currency": "AUD",
"reference": ""
}
]
},
{
"status": "ACTIVE",
"accounting_code": "Gift Certificate",
"code": "GC-0002",
"amount": "500.00000",
"remaining_balance": "500.00000",
"used_amount": "0.00000",
"currency": "AUD",
"expiry_date": "2025-08-12T10:00:00Z",
"created_by": "",
"created_on": "2025-08-07T08:05:38Z",
"last_updated_by": "",
"last_updated_on": "2025-08-07T08:05:38Z",
"uuid": "e4a02977-d4a2-4ce4-991c-07adaa677de5",
"custom_attributes": [],
"allocations": [],
"transactions": [
{
"accounting_code": "Gift Certificate",
"type": "INITIAL",
"date": "2025-08-07 08:05:38.000000",
"amount": 500.00000,
"currency": "AUD",
"reference": ""
}
]
}
],
"pagination": {
"records": 2,
"limit": 20,
"offset": 0,
"previous_page": "",
"next_page": "NULL"
}
}| Attribute | Type | Description |
|---|---|---|
status |
String | Status of the gift certificate (e.g., ACTIVE, EXPIRED). |
accounting_code |
String | Accounting code used for the gift certificate. |
code |
String | Unique code assigned to the gift certificate. |
amount |
String | Original issued amount of the gift certificate. |
remaining_balance |
String | Unused balance remaining. |
used_amount |
String | Amount already used. |
currency |
String | Currency of the gift certificate (e.g., AUD). |
expiry_date |
String | Expiration date in ISO format. |
created_by |
String | User or system who created the gift certificate. |
created_on |
String | Timestamp of when the gift certificate was created. |
last_updated_by |
String | User or system who last updated the record. |
last_updated_on |
String | Timestamp of the last update. |
uuid |
String | Unique identifier of the gift certificate. |
custom_attributes |
Array | Custom fields added to the gift certificate (empty in this response). |
allocations |
Array | Allocation records associated with the gift certificate (empty here). |
transactions |
Array of Objects | Financial transactions associated with the gift certificate. |
Retrieve Gift Certificate Details: /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. |
Query Parameters
This endpoint does not have any query parameters.
Request Body
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.
Response Body
{
"gift_certificate": {
"status": "ACTIVE",
"accounting_code": "Gift Certificate",
"code": "GC-0001",
"amount": "200.00000",
"remaining_balance": "200.00000",
"used_amount": "0.00000",
"currency": "AUD",
"expiry_date": "2025-08-10T10:00:00Z",
"created_by": "",
"created_on": "2025-08-07T08:04:49Z",
"last_updated_by": "",
"last_updated_on": "2025-08-07T08:04:49Z",
"uuid": "f6ff3efc-80b9-4a6a-9ea7-d10132af84e6",
"custom_attributes": [],
"allocations": [],
"transactions": [
{
"accounting_code": "Gift Certificate",
"type": "INITIAL",
"date": "2025-08-07 08:04:50.000000",
"amount": 200.00000,
"currency": "AUD",
"reference": ""
}
]
}
}| Attribute | Type | Description |
|---|---|---|
status |
String | Status of the gift certificate (example: ACTIVE, EXPIRED). |
accounting_code |
String | The accounting code related to the gift certificate. |
code |
String | Unique gift certificate code (example: GC-0001). |
amount |
String | Original value of the gift certificate. |
remaining_balance |
String | Amount still available for use. |
used_amount |
String | Portion of the gift certificate that has been used. |
currency |
String | Currency code (example: AUD). |
expiry_date |
String | ISO date string representing when the certificate will expire. |
created_by |
String | User who created the gift certificate. |
created_on |
String | Timestamp when it was created (ISO 8601 format). |
last_updated_by |
String | User who last modified the gift certificate. |
last_updated_on |
String | Timestamp of the most recent update. |
uuid |
String | Unique identifier for the gift certificate. |
custom_attributes |
Array | Custom fields defined for this certificate (empty array if none). |
allocations |
Array | Allocation records related to the gift certificate (empty array). |
transactions |
Array | List of related financial transactions. |
Retrieve Gift Certificate Allocation List: /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. |
Query Parameters
This endpoint does not have any query parameters.
Request Body
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.
Response Body
{
"gift_certificate": {
"allocations": [
{
"account": "7O8DW7",
"type": "ALLOCATE",
"date": "2025-08-07T11:02:41Z"
}
],
"pagination": {
"records": 1,
"limit": 20,
"offset": 0,
"previous_page": "",
"next_page": "NULL"
}
}
}| Attribute | Type | Description |
|---|---|---|
account |
String | The account UUID to which the gift certificate was allocated. |
type |
String | The type of allocation (e.g., ALLOCATE, DEALLOCATE). |
date |
String | ISO timestamp of when the allocation occurred. |
Retrieve Gift Certificate Transaction List: /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. |
Query Parameters
This endpoint does not have any query parameters.
Request Body
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.
Response Body
{
"gift_certificate": {
"transactions": [
{
"accounting_code": "Gift Certificate",
"type": "INITIAL",
"date": "2025-08-07T08:04:50Z",
"amount": "200.00000",
"currency": "AUD",
"reference": ""
}
],
"pagination": {
"records": 1,
"limit": 20,
"offset": 0,
"previous_page": "",
"next_page": "NULL"
}
}
}| Attribute | Type | Description |
|---|---|---|
accounting_code |
String | The accounting code associated with the transaction. |
type |
String | The type of transaction (e.g., INITIAL, REDEEM, etc.). |
date |
String | ISO timestamp when the transaction was recorded. |
amount |
String | The monetary amount involved in the transaction. |
currency |
String | Currency code (e.g., AUD, USD). |
reference |
String | Optional reference note related to the transaction. |