Overview
The Gift Certificate Module provides a comprehensive set of functionalities for managing digital gift certificates within the system. It allows administrators and users to create, allocate, modify, disable, and delete gift certificates, as well as manage their transactions and custom attributes. These capabilities support seamless integration with e-commerce platforms, enabling businesses to offer gift certificates as a flexible payment or gifting option.
Getting Gift Certificates List
Function: getGiftCertificatesList()
Purpose
The function retrieves all available gift certificates associated with the system or user. It is primarily used to access gift card details for display, management, or further processing, such as redemption or tracking.
Parameters
This function does not require any input parameters.
Use Case
This function can be used when administrators or users need to view or manage gift certificates. It helps streamline gift card operations, allowing businesses to display active certificates, check their status, and track them effectively.
def get_gift_certificates_list():
SDKConfig.PRINT_REQUEST_DATA = True
SDKConfig.PRINT_RAW_RESPONSE = True
exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(request_token_dto=CommonData.get_request_token_dto())
try:
response = exsited_sdk.gift_certificates.list()
print(response)
except ABException as ab:
print(ab)
print(ab.get_errors())
print(ab.raw_response)
public function getGiftCertificatesList()
{
try {
$response = $this->giftService->readAll();
echo '<pre>' . json_encode($response, JSON_PRETTY_PRINT) . '</pre>';
} catch (Exception $e) {
echo 'Error: ' . $e->getMessage();
}
}
Response
A JSON object containing a list of gift certificates, each with details such as certificate IDs, values, expiry dates, and statuses. In case of errors, it provides error messages and raw responses for debugging.
GiftCertificatesListDTO(
giftCertificates=[
GiftCertificateDTO(
status="STATUS_PLACEHOLDER",
account=None,
accountingCode="ACCOUNTING_CODE_PLACEHOLDER",
code="CODE_PLACEHOLDER",
amount="AMOUNT_PLACEHOLDER",
remainingBalance="REMAINING_BALANCE_PLACEHOLDER",
usedAmount="USED_AMOUNT_PLACEHOLDER",
currency="CURRENCY_PLACEHOLDER",
expiryDate="EXPIRY_DATE_PLACEHOLDER",
createdBy="CREATED_BY_PLACEHOLDER",
createdOn="CREATED_ON_PLACEHOLDER",
lastUpdatedBy="LAST_UPDATED_BY_PLACEHOLDER",
lastUpdatedOn="LAST_UPDATED_ON_PLACEHOLDER",
uuid="UUID_PLACEHOLDER",
customAttributes=[
CustomAttributesDataDTO(name="ATTRIBUTE_NAME_PLACEHOLDER", value="ATTRIBUTE_VALUE_PLACEHOLDER")
],
allocations=[],
transactions=[
TransactionDTO(
accountingCode="ACCOUNTING_CODE_PLACEHOLDER",
type="TYPE_PLACEHOLDER",
date="DATE_PLACEHOLDER",
amount="AMOUNT_PLACEHOLDER",
currency="CURRENCY_PLACEHOLDER",
reference="REFERENCE_PLACEHOLDER"
)
]
),
GiftCertificateDTO(
status="STATUS_PLACEHOLDER",
account=None,
accountingCode="ACCOUNTING_CODE_PLACEHOLDER",
code="CODE_PLACEHOLDER",
amount="AMOUNT_PLACEHOLDER",
remainingBalance="REMAINING_BALANCE_PLACEHOLDER",
usedAmount="USED_AMOUNT_PLACEHOLDER",
currency="CURRENCY_PLACEHOLDER",
expiryDate="EXPIRY_DATE_PLACEHOLDER",
createdBy="CREATED_BY_PLACEHOLDER",
createdOn="CREATED_ON_PLACEHOLDER",
lastUpdatedBy="LAST_UPDATED_BY_PLACEHOLDER",
lastUpdatedOn="LAST_UPDATED_ON_PLACEHOLDER",
uuid="UUID_PLACEHOLDER",
customAttributes=[
CustomAttributesDataDTO(name="ATTRIBUTE_NAME_PLACEHOLDER", value="ATTRIBUTE_VALUE_PLACEHOLDER")
],
allocations=[],
transactions=[
TransactionDTO(
accountingCode="ACCOUNTING_CODE_PLACEHOLDER",
type="TYPE_PLACEHOLDER",
date="DATE_PLACEHOLDER",
amount="AMOUNT_PLACEHOLDER",
currency="CURRENCY_PLACEHOLDER",
reference="REFERENCE_PLACEHOLDER"
)
]
)
],
pagination=PaginationDTO(
records="RECORD_PLACEHOLDER",
limit="LIMIT_PLACEHOLDER",
offset="OFFSET_PLACEHOLDER",
previousPage="PREVIOUS_PAGE_PLACEHOLDER",
nextPage="NEXT_PAGE_PLACEHOLDER"
)
)
{
"gift_certificates": [
{
"status": "STATUS_PLACEHOLDER",
"accounting_code": "ACCOUNTING_CODE_PLACEHOLDER",
"code": "CODE_PLACEHOLDER",
"amount": "AMOUNT_PLACEHOLDER",
"remaining_balance": "REMAINING_BALANCE_PLACEHOLDER",
"used_amount": "USED_AMOUNT_PLACEHOLDER",
"currency": "CURRENCY_PLACEHOLDER",
"expiry_date": "EXPIRY_DATE_PLACEHOLDER",
"created_by": "CREATED_BY_PLACEHOLDER",
"created_on": "CREATED_ON_PLACEHOLDER",
"last_updated_by": "LAST_UPDATED_BY_PLACEHOLDER",
"last_updated_on": "LAST_UPDATED_ON_PLACEHOLDER",
"uuid": "UUID_PLACEHOLDER",
"custom_attributes": [
{
"name": "ATTRIBUTE_NAME_PLACEHOLDER",
"value": "ATTRIBUTE_VALUE_PLACEHOLDER"
}
],
"allocations": [],
"transactions": [
{
"accounting_code": "ACCOUNTING_CODE_PLACEHOLDER",
"type": "TYPE_PLACEHOLDER",
"date": "DATE_PLACEHOLDER",
"amount": "AMOUNT_PLACEHOLDER",
"currency": "CURRENCY_PLACEHOLDER",
"reference": "REFERENCE_PLACEHOLDER"
}
]
},
{
"status": "STATUS_PLACEHOLDER",
"accounting_code": "ACCOUNTING_CODE_PLACEHOLDER",
"code": "CODE_PLACEHOLDER",
"amount": "AMOUNT_PLACEHOLDER",
"remaining_balance": "REMAINING_BALANCE_PLACEHOLDER",
"used_amount": "USED_AMOUNT_PLACEHOLDER",
"currency": "CURRENCY_PLACEHOLDER",
"expiry_date": "EXPIRY_DATE_PLACEHOLDER",
"created_by": "CREATED_BY_PLACEHOLDER",
"created_on": "CREATED_ON_PLACEHOLDER",
"last_updated_by": "LAST_UPDATED_BY_PLACEHOLDER",
"last_updated_on": "LAST_UPDATED_ON_PLACEHOLDER",
"uuid": "UUID_PLACEHOLDER",
"custom_attributes": [
{
"name": "ATTRIBUTE_NAME_PLACEHOLDER",
"value": "ATTRIBUTE_VALUE_PLACEHOLDER"
}
],
"allocations": [],
"transactions": [
{
"accounting_code": "ACCOUNTING_CODE_PLACEHOLDER",
"type": "TYPE_PLACEHOLDER",
"date": "DATE_PLACEHOLDER",
"amount": "AMOUNT_PLACEHOLDER",
"currency": "CURRENCY_PLACEHOLDER",
"reference": "REFERENCE_PLACEHOLDER"
}
]
}
],
"pagination": {
"records": "RECORDS_PLACEHOLDER",
"limit": "LIMIT_PLACEHOLDER",
"offset": "OFFSET_PLACEHOLDER",
"previous_page": "PREVIOUS_PAGE_PLACEHOLDER",
"next_page": "NEXT_PAGE_PLACEHOLDER"
}
}
Getting Specific Gift Certificate Details
Function: getGiftCertificateDetails()
Purpose
The function retrieves detailed information about a specific gift certificate identified by its UUID. It is mainly used to fetch the balance, expiry date, status, and any associated metadata of an individual gift certificate. This function is crucial for managing and tracking gift certificates, especially for customer service or accounting purposes.
Parameters
Parameter | Type | Description |
---|---|---|
GIFT_UUID | String | The unique identifier (UUID) of the gift certificate whose details are being requested. |
Use Case
This function can be used when businesses or customers need to retrieve detailed information about a specific gift certificate, such as its balance or expiry date. It can be used in various scenarios, including e-commerce platforms, where users or administrators track gift certificate details for validation, redemption, or reporting purposes.
def get_gift_certificate_details():
SDKConfig.PRINT_REQUEST_DATA = True
SDKConfig.PRINT_RAW_RESPONSE = True
exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(request_token_dto=CommonData.get_request_token_dto())
try:
response = exsited_sdk.gift_certificates.details(id="GIFT_UUID")
print(response)
except ABException as ab:
print(ab)
print(ab.get_errors())
print(ab.raw_response)
public function getGiftCertificateDetails()
{
$uuId="GIFT_UUID";
try {
$response = $this->giftService->readDetails($uuId);
echo '<pre>' . json_encode($response, JSON_PRETTY_PRINT) . '</pre>';
} catch (Exception $e) {
echo 'Error: ' . $e->getMessage();
}
}
Response
A JSON object containing the details of the specified gift certificate. This may include attributes such as balance, expiry date, status, and other relevant data. In case of an error, it provides error messages and the raw response for easier debugging.
GiftCertificateDetailsDTO(
giftCertificate=GiftCertificateDTO(
status="STATUS_PLACEHOLDER",
account=None,
accountingCode="ACCOUNTING_CODE_PLACEHOLDER",
code="CODE_PLACEHOLDER",
amount="AMOUNT_PLACEHOLDER",
remainingBalance="REMAINING_BALANCE_PLACEHOLDER",
usedAmount="USED_AMOUNT_PLACEHOLDER",
currency="CURRENCY_PLACEHOLDER",
expiryDate="EXPIRY_DATE_PLACEHOLDER",
createdBy="CREATED_BY_PLACEHOLDER",
createdOn="CREATED_ON_PLACEHOLDER",
lastUpdatedBy="LAST_UPDATED_BY_PLACEHOLDER",
lastUpdatedOn="LAST_UPDATED_ON_PLACEHOLDER",
uuid="UUID_PLACEHOLDER",
customAttributes=[
CustomAttributesDataDTO(name="ATTRIBUTE_NAME_PLACEHOLDER", value="ATTRIBUTE_VALUE_PLACEHOLDER")
],
allocations=[
AllocationDTO(account="ACCOUNT_PLACEHOLDER", type="TYPE_PLACEHOLDER", date="DATE_PLACEHOLDER")
],
transactions=[
TransactionDTO(
accountingCode="ACCOUNTING_CODE_PLACEHOLDER",
type="TYPE_PLACEHOLDER",
date="DATE_PLACEHOLDER",
amount="AMOUNT_PLACEHOLDER",
currency="CURRENCY_PLACEHOLDER",
reference="REFERENCE_PLACEHOLDER"
)
]
)
)
{
"gift_certificate": {
"status": "STATUS_PLACEHOLDER",
"accounting_code": "ACCOUNTING_CODE_PLACEHOLDER",
"code": "CODE_PLACEHOLDER",
"amount": "AMOUNT_PLACEHOLDER",
"remaining_balance": "REMAINING_BALANCE_PLACEHOLDER",
"used_amount": "USED_AMOUNT_PLACEHOLDER",
"currency": "CURRENCY_PLACEHOLDER",
"expiry_date": "EXPIRY_DATE_PLACEHOLDER",
"created_by": "CREATED_BY_PLACEHOLDER",
"created_on": "CREATED_ON_PLACEHOLDER",
"last_updated_by": "LAST_UPDATED_BY_PLACEHOLDER",
"last_updated_on": "LAST_UPDATED_ON_PLACEHOLDER",
"uuid": "UUID_PLACEHOLDER",
"custom_attributes": [
{
"name": "ATTRIBUTE_NAME_PLACEHOLDER",
"value": "ATTRIBUTE_VALUE_PLACEHOLDER"
}
],
"allocations": [
{
"account": "ACCOUNT_PLACEHOLDER",
"type": "TYPE_PLACEHOLDER",
"date": "DATE_PLACEHOLDER"
}
],
"transactions": [
{
"accounting_code": "ACCOUNTING_CODE_PLACEHOLDER",
"type": "TYPE_PLACEHOLDER",
"date": "DATE_PLACEHOLDER",
"amount": "AMOUNT_PLACEHOLDER",
"currency": "CURRENCY_PLACEHOLDER",
"reference": "REFERENCE_PLACEHOLDER"
}
]
}
}
Getting Allocations List of a Specific Gift Certificates
Function: getGiftCertificateAllocationsList()
Purpose
The function retrieves a detailed list of allocations or usages associated with a specific gift certificate identified by its UUID. It helps track where and how a gift certificate has been used, providing transparency for audits, customer inquiries, or internal reporting.
Parameters
Parameter | Type | Description |
---|---|---|
GIFT_UUID | String | The unique identifier (UUID) of the gift certificate whose details are being requested |
Use Case
This function can be used in scenarios where businesses or customers need to track the usage of a gift certificate. For instance, an administrator may use this to audit how the gift card balance has been distributed across different transactions or for customer support inquiries about gift certificate usage history.
def list_gift_certificate_allocations():
SDKConfig.PRINT_REQUEST_DATA = True
SDKConfig.PRINT_RAW_RESPONSE = True
exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(request_token_dto=CommonData.get_request_token_dto())
try:
response = exsited_sdk.gift_certificates.allocation_list(id="GIFT_UUID")
print(response)
except ABException as ab:
print(ab)
print(ab.get_errors())
print(ab.raw_response)
public function listGiftCertificateAllocations()
{
$uuId="GIFT_UUID";
try {
$response = $this->giftService->readAllocations($uuId);
echo '<pre>' . json_encode($response, JSON_PRETTY_PRINT) . '</pre>';
} catch (Exception $e) {
echo 'Error: ' . $e->getMessage();
}
}
Response
A JSON object containing a list of allocations for the specified gift certificate. Each allocation may include details such as the allocation date, account ID and type. In case of an error, the function returns error messages and raw responses to aid debugging.
GiftCertificateAllocationListDTO(
giftCertificate=AllocationListDataDTO(
allocations=[
AllocationDTO(
account="ACCOUNT_PLACEHOLDER_1",
type="TYPE_PLACEHOLDER",
date="DATE_PLACEHOLDER"
),
AllocationDTO(
account="ACCOUNT_PLACEHOLDER_2",
type="TYPE_PLACEHOLDER",
date="DATE_PLACEHOLDER"
)
],
pagination=PaginationDTO(
records=RECORDS_PLACEHOLDER,
limit=LIMIT_PLACEHOLDER,
offset=OFFSET_PLACEHOLDER,
previousPage="PREVIOUS_PAGE_PLACEHOLDER",
nextPage="NEXT_PAGE_PLACEHOLDER"
)
)
)
{
"gift_certificate": {
"allocations": [
{
"account": "ACCOUNT_PLACEHOLDER_1",
"type": "TYPE_PLACEHOLDER",
"date": "DATE_PLACEHOLDER"
},
{
"account": "ACCOUNT_PLACEHOLDER_2",
"type": "TYPE_PLACEHOLDER",
"date": "DATE_PLACEHOLDER"
}
],
"pagination": {
"records": "RECORDS_PLACEHOLDER",
"limit": "LIMIT_PLACEHOLDER",
"offset": "OFFSET_PLACEHOLDER",
"previous_page": "PREVIOUS_PAGE_PLACEHOLDER",
"next_page": "NEXT_PAGE_PLACEHOLDER"
}
}
}
Getting Transections List of a Specific Gift Certificates
Function: getGiftCertificateTransactionsList()
Purpose
The function retrieves a comprehensive list of transactions associated with a specific gift certificate. This allows tracking usage, adjustments, and any activity linked to the gift certificate.
Parameters
Parameter | Type | Description |
---|---|---|
GIFT_UUID | String | The unique identifier (UUID) of the gift certificate whose transactions are to be retrieved. |
Use Case
This function can be used to monitor the history and activity of a gift certificate, such as viewing its redemption history, reversals, or adjustments. It is particularly useful for auditing purposes or providing detailed transaction records to customers or administrators.
def get_gift_certificate_transactions_list():
SDKConfig.PRINT_REQUEST_DATA = True
SDKConfig.PRINT_RAW_RESPONSE = True
exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(request_token_dto=CommonData.get_request_token_dto())
try:
response = exsited_sdk.gift_certificates.transaction_list(id="GIFT_UUID")
print(response)
except ABException as ab:
print(ab)
print(ab.get_errors())
print(ab.raw_response)
public function getGiftCertificateTransactionsList()
{
$uuId="GIFT_UUID";
try {
$response = $this->giftService->readTransactions($uuId);
echo '<pre>' . json_encode($response, JSON_PRETTY_PRINT) . '</pre>';
} catch (Exception $e) {
echo 'Error: ' . $e->getMessage();
}
}
Response
The response contains the transaction history of the specified gift certificate. Each transaction entry includes details such as transaction date, type (e.g., initial, debit, credit or amend),currency, reference and amounts. Errors provide messages and raw responses for debugging.
GiftCertificateTransactionsListDTO(
giftCertificate=TransactionListDataDTO(
transactions=[
TransactionDTO(
accountingCode="ACCOUNTING_CODE_PLACEHOLDER",
type="INITIAL",
date="DATE_PLACEHOLDER",
amount="AMOUNT_PLACEHOLDER",
currency="CURRENCY_PLACEHOLDER",
reference="REFERENCE_PLACEHOLDER"
),
TransactionDTO(
accountingCode="ACCOUNTING_CODE_PLACEHOLDER",
type="DEBIT",
date="DATE_PLACEHOLDER",
amount="AMOUNT_PLACEHOLDER",
currency="CURRENCY_PLACEHOLDER",
reference="REFERENCE_PLACEHOLDER"
),
TransactionDTO(
accountingCode="ACCOUNTING_CODE_PLACEHOLDER",
type="CREDIT",
date="DATE_PLACEHOLDER",
amount="AMOUNT_PLACEHOLDER",
currency="CURRENCY_PLACEHOLDER",
reference="REFERENCE_PLACEHOLDER"
),
TransactionDTO(
accountingCode="ACCOUNTING_CODE_PLACEHOLDER",
type="AMEND",
date="DATE_PLACEHOLDER",
amount="AMOUNT_PLACEHOLDER",
currency="CURRENCY_PLACEHOLDER",
reference="REFERENCE_PLACEHOLDER"
)
],
pagination=PaginationDTO(
records="RECORDS_PLACEHOLDER",
limit="LIMIT_PLACEHOLDER",
offset="OFFSET_PLACEHOLDER",
previousPage="PREVIOUS_PAGE_PLACEHOLDER",
nextPage="NEXT_PAGE_PLACEHOLDER"
)
)
)
{
"gift_certificate": {
"transactions": [
{
"accounting_code": "ACCOUNTING_CODE_PLACEHOLDER",
"type": "INITIAL",
"date": "DATE_PLACEHOLDER",
"amount": "AMOUNT_PLACEHOLDER",
"currency": "CURRENCY_PLACEHOLDER",
"reference": "REFERENCE_PLACEHOLDER"
},
{
"accounting_code": "ACCOUNTING_CODE_PLACEHOLDER",
"type": "DEBIT",
"date": "DATE_PLACEHOLDER",
"amount": "AMOUNT_PLACEHOLDER",
"currency": "CURRENCY_PLACEHOLDER",
"reference": "REFERENCE_PLACEHOLDER"
},
{
"accounting_code": "ACCOUNTING_CODE_PLACEHOLDER",
"type": "CREDIT",
"date": "DATE_PLACEHOLDER",
"amount": "AMOUNT_PLACEHOLDER",
"currency": "CURRENCY_PLACEHOLDER",
"reference": "REFERENCE_PLACEHOLDER"
},
{
"accounting_code": "ACCOUNTING_CODE_PLACEHOLDER",
"type": "AMEND",
"date": "DATE_PLACEHOLDER",
"amount": "AMOUNT_PLACEHOLDER",
"currency": "CURRENCY_PLACEHOLDER",
"reference": "REFERENCE_PLACEHOLDER"
}
],
"pagination": {
"records": "RECORDS_PLACEHOLDER",
"limit": "LIMIT_PLACEHOLDER",
"offset": "OFFSET_PLACEHOLDER",
"previous_page": "PREVIOUS_PAGE_PLACEHOLDER",
"next_page": "NEXT_PAGE_PLACEHOLDER"
}
}
}
Creating a Gift Certificate
Function: createGiftCertificate()
Purpose
The function enables the creation of new gift certificates in the system. It facilitates the generation of custom certificates with defined attributes like code, status, amount, currency, expiry date, and additional custom parameters, streamlining the issuance of gift certificates for various use cases.
Parameters
Parameter | Type | Description |
---|---|---|
STATUS | String | The status of the certificate |
CODE_LENGTH | String | The length of the generated code. |
CODE_PREFIX | String | An optional prefix to prepend to the code. |
ACCOUNTING_CODE | String | Accounting reference for categorization. |
AMOUNT | String | Monetary value of the certificate. |
CURRENCY | String | The currency type. |
EXPIRATION_DATE | String | Expiration date of certificate |
CUSTOM_ATTRIBUTE_NAME | String | The name of the custom attribute. |
CUSTOM_ATTRIBUTE_VALUE | String | The value associated with the custom attribute. |
Use Case
This function can be used by businesses or administrators to issue new gift certificates, either for internal use or distribution to customers. It simplifies the management of gift certificates by allowing detailed customization and automation, ensuring accuracy and efficiency in gift card operations.
def create_gift_certificate():
SDKConfig.PRINT_REQUEST_DATA = True
SDKConfig.PRINT_RAW_RESPONSE = True
exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(request_token_dto=CommonData.get_request_token_dto())
try:
request_obj = GiftCertificateDetailsDTO(giftCertificate=GiftCertificateDTO(
status="STATUS",
code=(CodeDTO(length="CODE_LENGTH", prefix="CODE_PREFIX")),
accountingCode="ACCOUNTING_CODE",
amount="AMOUNT",
currency="CURRENCY",
expiryDate="EXPIRATION_DATE",
customAttributes=[CustomAttributesDataDTO(name="CUSTOM_ATTRIBUTE_NAME", value="CUSTOM_ATTRIBUTE_VALUE")]
))
response = exsited_sdk.gift_certificates.create(request_data=request_obj)
print(response)
except ABException as ab:
print(ab)
print(ab.get_errors())
print(ab.raw_response)
public function createGiftCertificate()
{
$params = [
"gift_certificate" => [
"status" => "STATUS",
"code" => [
"length" => "CODE_LENGTH",
"prefix" => "CODE_PREFIX"
],
"accounting_code" => "ACCOUNTING_CODE",
"amount" => "AMOUNT",
"currency" => "CURRENCY",
"expiry_date" => "EXPIRATION_DATE",
"custom_attributes" => [
[
"name" => "CUSTOM_ATTRIBUTE_NAME",
"value" => "CUSTOM_ATTRIBUTE_VALUE"
]
]
]
];
try {
$response = $this->giftService->create($params);
echo '<pre>' . json_encode($response, JSON_PRETTY_PRINT) . '</pre>';
} catch (Exception $e) {
echo 'Error: ' . $e->getMessage();
}
}
Response
The response provides comprehensive details about the created gift certificate, including its status, unique code, monetary value, currency, and expiration date. Metadata such as the creator's information, timestamps for creation and updates, and any custom attributes are also included. Additionally, the response contains an empty allocations list and a transactions array detailing the initial allocation of the certificate, capturing the date, type, and accounting code for tracking purposes. This ensures a complete record of the gift certificate's creation and associated metadata.
GiftCertificateDetailsDTO(
giftCertificate=GiftCertificateDTO(
status="ACTIVE",
account=None,
accountingCode="ACCOUNTING_CODE",
amount="AMOUNT",
remainingBalance="REMAINING_BALANCE",
usedAmount="USED_AMOUNT",
currency="CURRENCY",
expiryDate="EXPIRY_DATE",
createdBy="CREATED_BY",
createdOn="CREATED_ON",
lastUpdatedBy="LAST_UPDATED_BY",
lastUpdatedOn="LAST_UPDATED_ON",
uuid="UUID",
allocations=[],
transactions=[
TransactionDTO(
accountingCode="ACCOUNTING_CODE",
type="TYPE",
date="DATE",
amount="TRANSACTION_AMOUNT",
currency="CURRENCY",
reference="REFERENCE"
)
],
code="CODE",
customAttributes=[
CustomAttributeResponseDataDTO(
attribute={"id": "ID", "name": "ATTRIBUTE_NAME"},
value="VALUE"
)
]
)
)
{
"gift_certificate": {
"status": "STATUS",
"accounting_code": "ACCOUNTING_CODE",
"code": "CODE",
"amount": "AMOUNT",
"remaining_balance": "REMAINING_BALANCE",
"used_amount": "USED_AMOUNT",
"currency": "CURRENCY",
"expiry_date": "EXPIRY_DATE",
"created_by": "CREATED_BY",
"created_on": "CREATED_ON",
"last_updated_by": "LAST_UPDATED_BY",
"last_updated_on": "LAST_UPDATED_ON",
"uuid": "UUID",
"custom_attributes": [
{
"attribute": {
"id": "ID",
"name": "ATTRIBUTE_NAME"
},
"value": "VALUE"
}
],
"allocations": [],
"transactions": [
{
"date": "DATE",
"type": "TYPE",
"accounting_code": "ACCOUNTING_CODE",
"amount": "TRANSACTION_AMOUNT",
"currency": "CURRENCY",
"reference": "REFERENCE"
}
]
}
}
Disabling a Gift Certificate
Function: disableGiftCertificate()
Purpose
The function deactivates a specific gift certificate, preventing its further use. It is primarily used to invalidate certificates that are no longer valid or were issued in error.
Parameters
Parameter | Type | Description |
---|---|---|
GIFT_UUID | String | The unique identifier (UUID) of the gift certificate to be disabled. |
Use Case
This function can be used when an administrator or system needs to deactivate a gift certificate, such as when the certificate is reported lost, issued by mistake, or invalidated for policy reasons. For example, in an e-commerce system, admins can disable expired or misused certificates to ensure proper account management and prevent fraud.
def disable_gift_certificate():
SDKConfig.PRINT_REQUEST_DATA = True
SDKConfig.PRINT_RAW_RESPONSE = True
exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(request_token_dto=CommonData.get_request_token_dto())
try:
response = exsited_sdk.gift_certificates.disable(id="GIFT_UUID")
print(response)
except ABException as ab:
print(ab)
print(ab.get_errors())
print(ab.raw_response)
public function disableGiftCertificate()
{
$uuId="GIFT_UUID";
try {
$response = $this->giftService->disable($uuId);
echo '<pre>' . json_encode($response, JSON_PRETTY_PRINT) . '</pre>';
} catch (Exception $e) {
echo 'Error: ' . $e->getMessage();
}
}
Response
A JSON object confirming the successful activation of the gift certificate. This response will include the updated status. In case of errors, the response will include error details for troubleshooting.
GiftCertificateDetailsDTO(
giftCertificate=GiftCertificateDTO(
status="INACTIVE",
account=None,
accountingCode="ACCOUNTING_CODE_PLACEHOLDER",
code="CODE_PLACEHOLDER",
amount="AMOUNT_PLACEHOLDER",
remainingBalance="REMAINING_BALANCE_PLACEHOLDER",
usedAmount="USED_AMOUNT_PLACEHOLDER",
currency="CURRENCY_PLACEHOLDER",
expiryDate="EXPIRY_DATE_PLACEHOLDER",
createdBy="CREATED_BY_PLACEHOLDER",
createdOn="CREATED_ON_PLACEHOLDER",
lastUpdatedBy="LAST_UPDATED_BY_PLACEHOLDER",
lastUpdatedOn="LAST_UPDATED_ON_PLACEHOLDER",
uuid="UUID_PLACEHOLDER",
customAttributes=[],
allocations=[],
transactions=[]
)
)
{
"gift_certificate": {
"status": "INACTIVE"
}
}
Enabling a Gift Certificate
Function: enableGiftCertificate()
Purpose
The function activates a specific gift certificate, making it valid for use. This is commonly used to reinstate certificates that were previously disabled or to activate newly issued certificates.
Parameters
Parameter | Type | Description |
---|---|---|
GIFT_UUID | String | The unique identifier (UUID) of the gift certificate to be enabled. |
Use Case
This function can be used when an administrator or system needs to activate a gift certificate, such as when a previously disabled certificate is reinstated or when a new certificate is issued and made available for use. For example, in a retail system, administrators can enable promotional gift cards to be used during a specific sales event.
def enable_gift_certificate():
SDKConfig.PRINT_REQUEST_DATA = True
SDKConfig.PRINT_RAW_RESPONSE = True
exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(request_token_dto=CommonData.get_request_token_dto())
try:
response = exsited_sdk.gift_certificates.enable(id="GIFT_UUID")
print(response)
except ABException as ab:
print(ab)
print(ab.get_errors())
print(ab.raw_response)
public function enableGiftCertificate()
{
$uuId="GIFT_UUID";
try {
$response = $this->giftService->enable($uuId);
echo '<pre>' . json_encode($response, JSON_PRETTY_PRINT) . '</pre>';
} catch (Exception $e) {
echo 'Error: ' . $e->getMessage();
}
}
Response
A JSON object confirming the successful activation of the gift certificate. This response will include the updated status. In case of errors, the response will include error details for troubleshooting.
GiftCertificateDetailsDTO(
giftCertificate=GiftCertificateDTO(
status="ACTIVE",
account=None,
accountingCode="ACCOUNTING_CODE_PLACEHOLDER",
code="CODE_PLACEHOLDER",
amount="AMOUNT_PLACEHOLDER",
remainingBalance="REMAINING_BALANCE_PLACEHOLDER",
usedAmount="USED_AMOUNT_PLACEHOLDER",
currency="CURRENCY_PLACEHOLDER",
expiryDate="EXPIRY_DATE_PLACEHOLDER",
createdBy="CREATED_BY_PLACEHOLDER",
createdOn="CREATED_ON_PLACEHOLDER",
lastUpdatedBy="LAST_UPDATED_BY_PLACEHOLDER",
lastUpdatedOn="LAST_UPDATED_ON_PLACEHOLDER",
uuid="UUID_PLACEHOLDER",
customAttributes=[],
allocations=[],
transactions=[]
)
)
{
"gift_certificate": {
"status": "ACTIVE"
}
}
Allocating a Specific Gift Certificate to an Account
Function: allocateGiftCertificate()
Purpose
The function assigns a specific gift certificate to an account, effectively linking the certificate for use or tracking. This is useful for allocating certificates to customers or internal accounts for various purposes like rewards or promotions.
Parameters
Parameter | Type | Description |
---|---|---|
GIFT_UUID | String | The unique identifier (UUID) of the gift certificate to be allocated. |
ACCOUNT_ID | String | The account ID to which the gift certificate is allocated. |
Use Case
This function can be used when a gift certificate needs to be tied to a particular account, such as allocating promotional vouchers to customer accounts during a campaign. It helps in tracking and managing the use of the certificate effectively, ensuring that only authorized accounts can redeem it.
def allocate_gift_certificate():
SDKConfig.PRINT_REQUEST_DATA = True
SDKConfig.PRINT_RAW_RESPONSE = True
exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(request_token_dto=CommonData.get_request_token_dto())
try:
request_obj = GiftCertificateDetailsDTO(giftCertificate=GiftCertificateDTO(account="ACCOUNT_ID"))
response = exsited_sdk.gift_certificates.allocate(id="GIFT_UUID",
request_data=request_obj)
print(response)
except ABException as ab:
print(ab)
print(ab.get_errors())
print(ab.raw_response)
public function allocateGiftCertificate()
{
$params = [
"gift_certificate" => [
"account" => "ACCOUNT_ID"
]
];
$uuId="GIFT_UUID";
try {
$response = $this->giftService->allocate($params,$uuId);
echo '<pre>' . json_encode($response, JSON_PRETTY_PRINT) . '</pre>';
} catch (Exception $e) {
echo 'Error: ' . $e->getMessage();
}
}
Response
A response confirming the allocation of the gift certificate to the specified account. It will include details of gift allocation date, type and account ID. Errors will return detailed messages for debugging.
GiftCertificateAllocationListDTO(
giftCertificate=AllocationListDataDTO(
allocations=[
AllocationDTO(
account="ACCOUNT_PLACEHOLDER",
type="allocate",
date="DATE_PLACEHOLDER"
)
],
pagination=None
)
)
{
"gift_certificate": {
"allocations": [
{
"date": "DATE_PLACEHOLDER",
"type": "allocate",
"account": "ACCOUNT_PLACEHOLDER"
}
]
}
}
Deallocating a Specific Gift Certificate From an Account
Function: deallocateGiftCertificate()
Purpose
The function removes the assignment of a gift certificate from an account. This is useful when a certificate is no longer needed for the specified account or needs to be reassigned elsewhere.
Parameters
Parameter | Type | Description |
---|---|---|
GIFT_UUID | String | The unique identifier (UUID) of the gift certificate to be deallocated. |
ACCOUNT_ID | String | The account ID from which the gift certificate is being deallocated. |
Use Case
This function can be used when a gift certificate needs to be unlinked from an account, such as revoking an allocated promotional voucher or clearing an invalid assignment. It ensures that the certificate is available for future use or reallocation.
def deallocate_gift_certificate():
SDKConfig.PRINT_REQUEST_DATA = True
SDKConfig.PRINT_RAW_RESPONSE = True
exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(request_token_dto=CommonData.get_request_token_dto())
try:
request_obj = GiftCertificateDetailsDTO(giftCertificate=GiftCertificateDTO(account="ACCOUNT_ID"))
response = exsited_sdk.gift_certificates.deallocate(id="GIFT_UUID",
request_data=request_obj)
print(response)
except ABException as ab:
print(ab)
print(ab.get_errors())
print(ab.raw_response)
public function deallocateGiftCertificate()
{
$params = [
"gift_certificate" => [
"account" => "ACCOUNT_ID"
]
];
$uuId="GIFT_UUID";
try {
$response = $this->giftService->deallocate($params,$uuId);
echo '<pre>' . json_encode($response, JSON_PRETTY_PRINT) . '</pre>';
} catch (Exception $e) {
echo 'Error: ' . $e->getMessage();
}
}
Response
A response will confirm the removal of the gift certificate from the specified account. It will include details of gift deallocation date, type and account ID. Errors provide messages and raw responses for debugging.
GiftCertificateAllocationListDTO(
giftCertificate=AllocationListDataDTO(
allocations=[
AllocationDTO(
account="ACCOUNT_PLACEHOLDER",
type="deallocate",
date="DATE_PLACEHOLDER"
)
],
pagination=None
)
)
{
"gift_certificate": {
"allocations": [
{
"date": "DATE_PLACEHOLDER",
"type": "deallocate",
"account": "ACCOUNT_PLACEHOLDER"
}
]
}
}
Amending a Gift Certificate
Function: amendGiftCertificate()
Purpose
The function modifies specific details of an existing gift certificate. Common amendments include updating the amount. This function ensures gift certificates remain accurate and aligned with business operations.
Parameters
Parameter | Type | Description |
---|---|---|
GIFT_UUID | String | The unique identifier (UUID) of the gift certificate to be amended. |
AMOUNT | String | The new amount for the gift certificate |
ACCOUNTING_CODE | String | The updated accounting code for tracking purposes. |
Use Case
This function can be used to adjust the properties of a gift certificate, such as increasing its value or updating its categorization for accounting purposes. It is particularly useful for managing customer requests or correcting data discrepancies.
def amend_gift_certificate():
SDKConfig.PRINT_REQUEST_DATA = True
SDKConfig.PRINT_RAW_RESPONSE = True
exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(request_token_dto=CommonData.get_request_token_dto())
try:
request_obj = GiftCertificateDetailsDTO(giftCertificate=GiftCertificateDTO(
accountingCode="ACCOUNTING_CODE",
amount="AMOUNT",
))
response = exsited_sdk.gift_certificates.amend(id="GIFT_UUID",
request_data=request_obj)
print(response)
except ABException as ab:
print(ab)
print(ab.get_errors())
print(ab.raw_response)
public function amendGiftCertificate()
{
$params = [
"gift_certificate" => [
"amount" => "AMOUNT",
"accounting_code" => "ACCOUNTING_CODE"
]
];
$uuId="GIFT_UUID";
try {
$response = $this->giftService->amend($params,$uuId);
echo '<pre>' . json_encode($response, JSON_PRETTY_PRINT) . '</pre>';
} catch (Exception $e) {
echo 'Error: ' . $e->getMessage();
}
}
Response
The response from the amend function indicates that the gift certificate transaction details have been successfully updated. It includes a record of the initial transaction and an amended transaction reflecting the updated amount. The updated details, including the remaining balance, timestamps, and any associated attributes or allocations, confirm the successful execution of the amendment. Errors return relevant error messages and raw response data for debugging.
GiftCertificateDetailsDTO(
giftCertificate=GiftCertificateDTO(
status="STATUS",
account=None,
accountingCode="ACCOUNTING_CODE",
code="CODE",
amount="AMOUNT",
remainingBalance="REMAINING_BALANCE",
usedAmount="USED_AMOUNT",
currency="CURRENCY",
expiryDate="EXPIRY_DATE",
createdBy="CREATED_BY",
createdOn="CREATED_ON",
lastUpdatedBy="LAST_UPDATED_BY",
lastUpdatedOn="LAST_UPDATED_ON",
uuid="UUID",
customAttributes=[
CustomAttributesDataDTO(name="CUSTOM_NAME", value="CUSTOM_VALUE")
],
allocations=[],
transactions=[
TransactionDTO(
accountingCode="ACCOUNTING_CODE",
type="INITIAL",
date="TRANSACTION_DATE",
amount="INITIAL_AMOUNT",
currency="TRANSACTION_CURRENCY",
reference="TRANSACTION_REFERENCE"
),
TransactionDTO(
accountingCode="ACCOUNTING_CODE",
type="AMEND",
date="TRANSACTION_DATE",
amount="AMENDED_AMOUNT",
currency="TRANSACTION_CURRENCY",
reference="TRANSACTION_REFERENCE"
)
]
)
)
{
"gift_certificate": {
"status": "STATUS",
"accounting_code": "ACCOUNTING_CODE",
"code": "CODE",
"amount": "AMOUNT",
"remaining_balance": "REMAINING_BALANCE",
"used_amount": "USED_AMOUNT",
"currency": "CURRENCY",
"expiry_date": "EXPIRY_DATE",
"created_by": "CREATED_BY",
"created_on": "CREATED_ON",
"last_updated_by": "LAST_UPDATED_BY",
"last_updated_on": "LAST_UPDATED_ON",
"uuid": "UUID",
"custom_attributes": [
{
"attribute": {
"id": "ATTRIBUTE_ID",
"name": "ATTRIBUTE_NAME"
},
"value": "ATTRIBUTE_VALUE"
}
],
"allocations": [],
"transactions": [
{
"date": "TRANSACTION_DATE",
"type": "INITIAL",
"accounting_code": "ACCOUNTING_CODE",
"amount": "INITIAL_AMOUNT",
"currency": "TRANSACTION_CURRENCY",
"reference": "TRANSACTION_REFERENCE"
},
{
"date": "TRANSACTION_DATE",
"type": "AMEND",
"accounting_code": "ACCOUNTING_CODE",
"amount": "AMENDED_AMOUNT",
"currency": "TRANSACTION_CURRENCY",
"reference": "TRANSACTION_REFERENCE"
}
]
}
}
Updating a Gift Certificate
Function: updateGiftCertificate()
Purpose
The function allows modifications to specific properties of an existing gift certificate, such as updating its expiry date or adding custom attributes. It provides flexibility to manage and personalize gift certificates effectively.
Parameters
Parameter | Type | Description |
---|---|---|
GIFT_UUID | String | The unique identifier (UUID) of the gift certificate to update. |
EXPIRY_DATE | String | New expiry date for the gift certificate. |
ATTRIBUTE_NAME | String | A set of key-value pairs to define or update custom attributes, such as name or amount |
ATTRIBUTE_VALUE | String | The value associated with the custom attribute. |
Use Case
This function can be used to make updates to gift certificates, such as extending their expiry date or adding additional metadata for personalization or tracking. It is particularly useful in scenarios where businesses need to revise certificates based on customer preferences or operational requirements.
def update_gift_certificate():
SDKConfig.PRINT_REQUEST_DATA = True
SDKConfig.PRINT_RAW_RESPONSE = True
exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(request_token_dto=CommonData.get_request_token_dto())
try:
request_obj = GiftCertificateDetailsDTO(giftCertificate=GiftCertificateDTO(
expiryDate="EXPIRY_DATE",
customAttributes=[CustomAttributesDataDTO(name="ATTRIBUTE_NAME", value="ATTRIBUTE_VALUE")]
))
response = exsited_sdk.gift_certificates.update(id="GIFT_UUID",
request_data=request_obj)
print(response)
except ABException as ab:
print(ab)
print(ab.get_errors())
print(ab.raw_response)
public function updateGiftCertificate()
{
$params = [
"gift_certificate" => [
"expiry_date" => "EXPIRY_DATE",
"custom_attributes" => [
[
"name" => "ATTRIBUTE_NAME",
"value" => "ATTRIBUTE_VALUE"
]
]
]
];
$uuId="GIFT_UUID";
try {
$response = $this->giftService->change($params,$uuId);
echo '<pre>' . json_encode($response, JSON_PRETTY_PRINT) . '</pre>';
} catch (Exception $e) {
echo 'Error: ' . $e->getMessage();
}
}
Response
The function returns a response with updated gift certificate details containing updated code, expiration date, and updated custom attributes confirming the changes. Errors return relevant messages and raw response data for debugging.
GiftCertificateDetailsDTO(
giftCertificate=GiftCertificateDTO(
status="ACTIVE",
account=None,
accountingCode="ACCOUNTING_CODE",
code="CODE",
amount="AMOUNT",
remainingBalance="REMAINING_BALANCE",
usedAmount="USED_AMOUNT",
currency="CURRENCY",
expiryDate="EXPIRY_DATE",
createdBy="CREATED_BY",
createdOn="CREATED_ON",
lastUpdatedBy="LAST_UPDATED_BY",
lastUpdatedOn="LAST_UPDATED_ON",
uuid="UUID",
customAttributes=[
CustomAttributesDataDTO(
name="CUSTOM_ATTRIBUTE_NAME",
value="CUSTOM_ATTRIBUTE_VALUE"
)
],
allocations=[
AllocationDTO(
account="ACCOUNT",
type="TYPE",
date="DATE"
)
],
transactions=[
TransactionDTO(
accountingCode="ACCOUNTING_CODE",
type="TYPE",
date="DATE",
amount="TRANSACTION_AMOUNT",
currency="CURRENCY",
reference="REFERENCE"
)
]
)
)
{
"gift_certificate": {
"status": "ACTIVE",
"accounting_code": "ACCOUNTING_CODE",
"code": "CODE",
"amount": "AMOUNT",
"remaining_balance": "REMAINING_BALANCE",
"used_amount": "USED_AMOUNT",
"currency": "CURRENCY",
"expiry_date": "EXPIRY_DATE",
"created_by": "CREATED_BY",
"created_on": "CREATED_ON",
"last_updated_by": "LAST_UPDATED_BY",
"last_updated_on": "LAST_UPDATED_ON",
"uuid": "UUID",
"custom_attributes": [
{
"attribute": {
"id": "ID",
"name": "CUSTOM_ATTRIBUTE_NAME"
},
"value": "CUSTOM_ATTRIBUTE_VALUE"
}
],
"allocations": [
{
"date": "DATE",
"type": "TYPE",
"account": "ACCOUNT"
}
],
"transactions": [
{
"date": "DATE",
"type": "TYPE",
"accounting_code": "ACCOUNTING_CODE",
"amount": "TRANSACTION_AMOUNT",
"currency": "CURRENCY",
"reference": "REFERENCE"
}
]
}
}
Deleting a Gift Certificate
Function: deleteGiftCertificate()
Purpose
The function removes an existing gift certificate from the system. This action is typically used to revoke a gift certificate permanently if it is no longer needed or was created in error.
Parameters
Parameter | Type | Description |
---|---|---|
GIFT_UUID | String | The gift certificate's unique identifier (UUID) is to be deleted. |
Use Case
This function can be used when an administrator or system requires the removal of a specific gift certificate, such as during account cleanup or the cancellation of unredeemed gift certificates. It ensures the system stays up-to-date and free of redundant or invalid entries.
def delete_gift_certificate():
SDKConfig.PRINT_REQUEST_DATA = True
SDKConfig.PRINT_RAW_RESPONSE = True
exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(request_token_dto=CommonData.get_request_token_dto())
try:
response = exsited_sdk.gift_certificates.delete(id="GIFT_UUID")
print(response)
except ABException as ab:
print(ab)
print(ab.get_errors())
print(ab.raw_response)
public function deleteGiftCertificate()
{
$uuId="GIFT_UUID";
try {
$response = $this->giftService->delete($uuId);
echo '<pre>' . json_encode($response, JSON_PRETTY_PRINT) . '</pre>';
} catch (Exception $e) {
echo 'Error: ' . $e->getMessage();
}
}
Response
A confirmation response indicating the successful deletion of the gift certificate. In case of errors, it provides appropriate error messages and raw response data for troubleshooting.
{
"success": True,
"status_code": 204
}
null
Configuration
Before using any of these functions, ensure that your API credentials are properly configured.
- Python: The request token is retrieved from CommonData.get_request_token_dto().
- PHP: Configuration is managed via ConfigManager and $this->giftService.
Language-Specific Features
Feature | Python Implementation | PHP Implementation |
---|---|---|
SDK Initialization | ExsitedSDK().init_sdk() | $this->giftService |
Exception Handling | ABException handles errors and raw response | try-catch block for exceptions |
Response Format | Prints response using print() | Outputs response using json_encode() |
Configuration | Managed through SDKConfig | Managed via ConfigManager |
Authentication Method | OAuth token via CommonData.get_request_token_dto() | API credentials via $this->giftService |
Error Logging | Captures errors with ABException and prints raw response | Captures exceptions and prints error message |
Data Parsing | JSON response parsed natively in Python | JSON encoded and displayed using PHP |
Error Output | print(ab.get_errors()) and ab.raw_response | echo 'Error: ' . $e->getMessage() |