Gift Certificate POST API Documentation

Endpoint: POST /api/v3/gift_certificates/

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

None.

Request

Contains details of the gift certificate to be created, including status, accounting code, amount, currency, expiry date, and custom attributes.

                JSON
              

                      {
    "gift_certificate": {
        "status": "GIFT_CERTIFICATE_STATUS",
        "accounting_code": "ACCOUNTING_CODE",
        "code": {
            "length": "CODE_LENGTH",
            "prefix": "CODE_PREFIX"
        },
        "amount": "GIFT_CERTIFICATE_AMOUNT",
        "currency": "CURRENCY_CODE",
        "expiry_date": "YYYY-MM-DD",
        "custom_attributes": [
            {
                "name": "ATTRIBUTE_NAME",
                "value": "ATTRIBUTE_VALUE"
            }
        ]
    }
}

                    

                JSON
              

                      {
    "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": "LAST_UPDATED_ON",
        "uuid": "UUID-PLACEHOLDER",
        "custom_attributes": [
            {
                "attribute": {
                    "id": "ATTRIBUTE_ID",
                    "name": "ATTRIBUTE_NAME"
                },
                "value": "ATTRIBUTE_VALUE"
            }
        ],
        "allocations": [],
        "transactions": [
            {
                "date": "YYYY-MM-DDTHH:MM:SSZ",
                "type": "TRANSACTION_TYPE",
                "accounting_code": "ACCOUNTING_CODE",
                "amount": "TRANSACTION_AMOUNT",
                "currency": "CURRENCY_CODE",
                "reference": "REFERENCE_PLACEHOLDER"
            }
        ]
    }
}

                    

Endpoint: POST /api/v3/gift_certificates/{uuid}/disable

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
uuid	String	Unique identifier of the gift certificate to be disabled.

Request

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.

                JSON
              

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

Endpoint: POST /api/v3/gift_certificates/{uuid}/enable

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.

Request

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.

                JSON
              

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

Endpoint: POST /api/v3/gift_certificates/{uuid}/allocate

Purpose

Allocate a specific gift certificate to a designated account by its UUID. This endpoint enables businesses to assign the certificate for use by specified accounts, linking it to their profile for redemption or tracking.

Use Case

Administrators can allocate gift certificates to customer accounts for promotions or rewards. For instance, they can assign a certificate to an account as part of a loyalty program or a special discount offer.

Path Parameters

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

Request

The request body specifies the account to which the gift certificate should be allocated. It requires the account's unique identifier, ensuring the certificate is assigned correctly for redemption or tracking purposes.

                JSON
              

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

                JSON
              

                      {
    "gift_certificate": {
        "allocations": [
            {
                "date": "YYYY-MM-DDTHH:MM:SSZ",
                "type": "TYPE_PLACEHOLDER",
                "account": "ACCOUNT_ID"
            }
        ]
    }
}

                    

Endpoint: POST /api/v3/gift_certificates/{uuid}/deallocate

Purpose

This endpoint deallocates a gift certificate from a specified account, removing its association with the account. Deallocation ensures the certificate is no longer available for use by the specified account.

Use Case

Businesses can use this endpoint to manage gift certificate associations by deallocating them from accounts that no longer need access. For example, if a gift certificate was allocated in error, it can be deallocated and reassigned appropriately.

Path Parameters

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

Request

The request body specifies the account from which the gift certificate should be deallocated. It includes the unique account identifier, ensuring precise removal of the certificate's association with the specified account. This helps maintain accurate allocation records.

                JSON
              

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

                JSON
              

                      {
    "gift_certificate": {
        "allocations": [
            {
                "date": "YYYY-MM-DDTHH:MM:SSZ",
                "type": "TYPE_PLACEHOLDER",
                "account": "ACCOUNT_ID"
            }
        ]
    }
}

                    

Endpoint: POST /api/v3/gift_certificates/{uuid}/amend

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.

Request

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"
    }
}
                    

                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"
            }
        ]
    }
}

                    