Gift Certificate POST API Documentation

Purpose

Create a new gift certificate with specified details such as status, amount, expiry date, custom attributes and allocations. This endpoint is used for issuing new gift certificates to customers or for promotional use.

Use Case

To issue a gift certificate for promotional purposes or as a customer reward, allowing tracking of balance, usage, and expiration.

Path Parameters

No path parameters required for this endpoint.

Query Parameters

No query parameters required for this endpoint.

Request Body

                JSON
              

                      {
    "gift_certificate": {
        "status": "ACTIVE",
        "accounting_code": "Gift Certificate",
        "code": {
            "length": "12",
            "prefix": "GC-FA",
            "suffix": "AUD"
        },
        "amount": "1090",
        "currency": "AUD",
        "expiry_date": "2031-09-24"
    }
}
                    

                JSON
              

                      {
    "gift_certificate": {
        "status": "ACTIVE",
        "accounting_code": "Gift Certificate",
        "code": "GC-FAXVJ7GCW",
        "amount": "1090.00",
        "remaining_balance": "1090.00",
        "used_amount": "0.00",
        "currency": "AUD",
        "expiry_date": "2031-09-24T10:00:00Z",
        "created_by": "saeed",
        "created_on": "2025-08-10T07:00:13Z",
        "last_updated_by": "",
        "last_updated_on": "",
        "uuid": "c5192d4f-9050-4a6b-bb67-77b9a96a1b7b",
        "custom_attributes": [],
        "allocations": [],
        "transactions": [
            {
                "date": "2025-08-10T07:00:14Z",
                "type": "Initial",
                "accounting_code": "Gift Certificate",
                "amount": "1090.00",
                "currency": "AUD",
                "reference": ""
            }
        ]
    }
}
                    

Attribute	Type	Description
status	String	Current status of the gift certificate.
accounting_code	String	Accounting category or code assigned to the gift certificate.
code	String	Unique code identifying the gift certificate.
amount	String	Original total value of the gift certificate.
remaining_balance	String	Current unused balance of the gift certificate.
used_amount	String	Amount already redeemed from the gift certificate.
currency	String	Currency code for the gift certificate amount.
expiry_date	String	Expiration date and time of the gift certificate in ISO 8601 format.
created_by	String	Name or identifier of the user who created the gift certificate.
created_on	String	Timestamp of when the gift certificate was created in ISO 8601 format.
last_updated_by	String	Name or identifier of the last user who updated the gift certificate.
last_updated_on	String	Timestamp of the last update to the gift certificate in ISO 8601 format.
uuid	String	Universally unique identifier for the gift certificate.
custom_attributes	Array	List of custom attributes assigned to the gift certificate.
allocations	Array	List of allocation records related to the gift certificate.
transactions	Array	List of transaction records associated with the gift certificate.

Purpose

This endpoint disables a specific gift certificate, which is identified by its UUID, and makes it inactive. Disabling prevents further usage, ensuring the certificate can no longer be applied to other transactions.

Use Case

Administrators can use this endpoint to deactivate a gift certificate that has been compromised, fully redeemed, or is no longer valid. For example, a business might disable a gift certificate issued for a limited-time promotion after its expiry.

Path Parameters

Parameter	Type	Description
gc_uuid	String	Unique identifier of the gift certificate to be disabled.

Query Parameters

No query parameters required for this endpoint.

Request Body

No request body is required for this endpoint.

Response

The response confirms the successful deactivation of the gift certificate by updating its status to INACTIVE. This ensures the certificate is no longer valid for any operations.

Response Body

                JSON
              

                      {
    "gift_certificate": {
        "status": "INACTIVE"
    }
}
                    

Purpose

This endpoint enables a specific gift certificate identified by its UUID, reactivating it for use. Enabling allows the certificate to be applied to transactions again.

Use Case

Businesses can use this endpoint to reactivate a gift certificate previously disabled for temporary reasons, such as administrative review or customer service adjustments. For example, a certificate can be reactivated after resolving a user dispute.

Path Parameters

Parameter	Type	Description
uuid	String	Unique identifier of the gift certificate to be enabled.

Query Parameters

No query parameters required for this endpoint.

Request Body

No request body is required for this endpoint.

Response

The response confirms the successful reactivation of the gift certificate by updating its status to ACTIVE. This ensures the certificate is valid for further use.

Response Body

                JSON
              

                      {
    "gift_certificate": {
        "status": "ACTIVE"
    }
}
                    

Purpose

This API endpoint allows removing or deallocating a specific gift certificate from a customer account. It is used to reverse or manage gift certificate assignments in the system, ensuring accurate tracking of allocations.

Use Case

Reverse a previous allocation of a gift certificate to an account.
Manage errors in gift certificate assignment or customer account changes.
Maintain accurate allocation history for auditing and reporting purposes.

Path Parameters

Parameter	Type	Description
GC_UUID	string	Unique identifier of the gift certificate to be deallocated

Query Parameters

No query parameter is required for this endpoint.

Request Body

                JSON
              

                      {
    "gift_certificate": {
        "account": "ACCOUNT_ID"
    }
}
                    

Attribute	Type	Description
gift_certificate	object	Parent object containing deallocation details
gift_certificate.account	string	Account ID from which the gift certificate will be removed

                JSON
              

                      {
    "gift_certificate": {
        "allocations": [
            {
                "date": "DATE",
                "type": "ALLOCATION_TYPE",
                "account": "ACCOUNT_ID"
            }
        ]
    }
}
                    

Attribute	Type	Description
date	string	Timestamp of the deallocation in ISO 8601 format
type	string	Type of allocation action (always `deallocate`)
account	string	Account ID from which the gift certificate was deallocated

Purpose

This endpoint allows you to amend the amount of an existing gift certificate identified by its UUID. It updates the certificate's total value while retaining its status and associated attributes.

Use Case

Use this endpoint to modify the value of a gift certificate, such as increasing its balance for promotions or correcting the amount after issuance. For instance, a business might amend a gift certificate to add extra credit for a loyal customer.

Path Parameters

Parameter	Type	Description
uuid	String	Unique identifier of the gift certificate to amend.

Query Parameters

No query parameter is required for this endpoint.

Request Body

The request body specifies the new amount for the gift certificate and includes the accounting code for categorization. This ensures the certificate is updated accurately for its intended purpose.

                JSON
              

                      {
    "gift_certificate": {
        "amount": "AMEND_AMOUNT",
        "accounting_code": "ACCOUNTING_CODE"
    }
}
                    

Attribute	Type	Description
amount	String (Decimal)	Gift certificate amount
accounting_code	String	Accounting code associated with the gift certificate

                JSON
              

                      {
    "gift_certificate": {
        "status": "STATUS",
        "accounting_code": "ACCOUNTING_CODE",
        "code": "CODE",
        "amount": "AMOUNT",
        "remaining_balance": "REMAINING_BALANCE",
        "used_amount": "USED_AMOUNT",
        "currency": "CURRENCY",
        "expiry_date": "YYYY-MM-DDTHH:MM:SSZ",
        "created_by": "CREATED_BY",
        "created_on": "YYYY-MM-DDTHH:MM:SSZ",
        "last_updated_by": "LAST_UPDATED_BY",
        "last_updated_on": "YYYY-MM-DDTHH:MM:SSZ",
        "uuid": "UUID",
        "custom_attributes": [
            {
                "attribute": {
                    "id": "ATTRIBUTE_ID",
                    "name": "ATTRIBUTE_NAME"
                },
                "value": "ATTRIBUTE_VALUE"
            },
            {
                "attribute": {
                    "id": "ATTRIBUTE_ID",
                    "name": "ATTRIBUTE_NAME"
                },
                "value": "ATTRIBUTE_VALUE"
            }
        ],
        "allocations": [
            {
                "date": "YYYY-MM-DDTHH:MM:SSZ",
                "type": "TYPE",
                "account": "ACCOUNT"
            }
        ],
        "transactions": [
            {
                "date": "YYYY-MM-DDTHH:MM:SSZ",
                "type": "TYPE",
                "accounting_code": "ACCOUNTING_CODE",
                "amount": "AMOUNT",
                "currency": "CURRENCY",
                "reference": "REFERENCE"
            },
            {
                "date": "YYYY-MM-DDTHH:MM:SSZ",
                "type": "TYPE",
                "accounting_code": "ACCOUNTING_CODE",
                "amount": "AMOUNT",
                "currency": "CURRENCY",
                "reference": "REFERENCE"
            }
        ]
    }
}

                    

Attribute	Type	Description
status	String	Status of the gift certificate (example: ACTIVE, INACTIVE)
accounting_code	String	Accounting code linked to the gift certificate
code	String	Unique code assigned to the gift certificate
amount	String (Decimal)	Original gift certificate amount
remaining_balance	String (Decimal)	Remaining balance available
used_amount	String (Decimal)	Amount already used
currency	String	Currency code (example: AUD)
expiry_date	String (DateTime)	Expiry date of the gift certificate
created_by	String	User who created the gift certificate
created_on	String (DateTime)	Timestamp when created
last_updated_by	String	User who last updated the record
last_updated_on	String (DateTime)	Timestamp of last update
uuid	String (UUID)	Unique identifier for the gift certificate
custom_attributes	Array	Custom attributes linked to the gift certificate
allocations	Array	Allocations made using this gift certificate
transactions	Array	Transaction history of the gift certificate

Purpose

This API endpoint allows assigning or allocating a specific gift certificate to a particular account. It is used to track and manage gift certificate usage and link certificates to customer accounts in the system.

Use Case

Allocate a purchased or issued gift certificate to a customer account.
Track gift certificate usage and history for accounting and reporting.
Ensure proper management of balances and allocations across accounts.

Path Parameters

Parameter	Type	Description
GC_UUID	string	Unique identifier of the gift certificate to be allocated

Query Parameters

No query parameters required for this endpoint.

Request Body

                JSON
              

                      {
    "gift_certificate": {
        "account": "EXAC-15P06132P447-10002"
    }
}
                    

Attribute	Type	Description
gift_certificate	object	Parent object containing allocation details
gift_certificate.account	string	Account ID to which the gift certificate will be allocated

                JSON
              

                      {
    "gift_certificate": {
        "allocations": [
            {
                "date": "2025-08-19T11:51:53Z",
                "type": "allocate",
                "account": "EXAC-15P06132P447-10002"
            }
        ]
    }
}
                    

Attribute	Type	Description
date	string	Timestamp of the allocation in ISO 8601 format
type	string	Type of allocation action
account	string	Account ID to which the gift certificate was allocated

Create New Gift Certificate: /gift_certificates

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response

Response Body

Disable a Gift Certificate: gift_certificates/{uuid}/disable

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response

Response Body

Enable a Gift Certificate: /gift_certificates/{uuid}/enable

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response

Response Body

Deallocate a Gift Certificate: /gift_certificates/{GC_UUID}/deallocate

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response

Response Body

Amend a Gift Certificate: /gift_certificates/{uuid}/amend

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response

Response Body

Allocate a Gift Certificate: /gift_certificates/{GC_UUID}/allocate

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response

Response Body