Changed on

This API holds loyalty points for a specified duration, reserving them until a redemption request is made through Order or Redeem. If no redemption occurs within the hold period, the points are released. The default hold time is 10 minutes, adjustable in the Gameball dashboard, with a maximum of 15 days and a minimum of 1 minute.

post/api/v4.0/integrations/transactions/hold

Request

  • Base URL: https://api.gameball.co
  • URL: https://api.gameball.co/api/v4.0/integrations/transactions/hold
  • Auth: API key in header apikey and API key in header secretkey

Request body

customerIdstring required

Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer.

emailstring

Customer's email address. This is required if your account uses email-based channel merging.

mobilestring

Customer's mobile number. This is required if your account uses mobile-based channel merging.

transactionTimestring date-time required

The time of the transaction in your system (e.g., order datetime, invoice datetime). Must be in UTC (ISO 8601 format).

otpstring

A one-time password (OTP) sent to the customer for authentication purposes. This is used only if your account has OTP configuration enabled. For more details on how the OTP is generated and validated, refer to the OTP Generation and Validation section.

ignoreOTPboolean

This attribute allows you to skip OTP verification when set to true. If not provided or set to false, OTP verification will be required for accounts configured to use OTP.

amountToHoldnumber

The monetary value (in the system's currency) that will be held from the customer's points balance. This allows you to reserve a specific monetary amount using the customer's points. Note: Only one of ruleId, amountToHold, or pointsToHold must be provided for the hold request to proceed.

pointsToHoldinteger

The number of points to be held from the customer's points balance. This allows you to reserve a certain number of points for later use. Note: Only one of ruleId, amountToHold, or pointsToHold must be provided for the hold request to proceed.

ruleIdstring

The ID of a redemption rule configured within Gameball's system. Clients can create custom redemption rules through the Gameball dashboard to specify different redemption options. For example, a redemption rule may allow points to be redeemed for a free product, free shipping, percentage-based discounts, or fixed-amount discounts. You can retrieve your configured redemption rules and their associated IDs by using the Redemption Configuration API. Note: Only one of ruleId, amountToHold, or pointsToHold must be provided for the hold request to proceed.

hashstring

A unique, rotating number generated for each customer, used as an additional layer of verification during redemptions. This number changes with each transaction to ensure secure validation. For more details on how the hash is generated and validated, refer to the Customer's Hash section.

Example request

{
  "customerId": "cust_abc12345xyz67890",
  "email": "john.doe@example.com",
  "mobile": "+1234567890",
  "transactionTime": "2024-10-11T16:15:15.071Z",
  "otp": "654321",
  "pointsToHold": 50,
  "hash": "123456"
}

Response

Points placed on hold successfully

customerIdstring

Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer.

holdAmountnumber

The monetary value that has been held from the customer's points balance. This value represents the amount reserved based on the customer's available points.

holdEquivalentPointsnumber

The number of points that have been held from the customer's points balance. These points are reserved for future use or specific transactions.

holdReferencestring

A unique identifier for the hold transaction. This reference is used to track and manage the held points for future actions, such as redeeming the held points or canceling the hold. This hold reference can also be used in Order API to redeem the held points.

Example response

{
  "customerId": "cust_abc12345xyz67890",
  "holdEquivalentPoints": 50,
  "holdReference": "a2a199ad-86f3-45c4-8253-7aaee50e4798"
}

Changes

  • 262228c13429Revision changes
    • info

      the endpoint scheme security apiKey AND secretKey was added to the API

    • info

      the endpoint scheme security apiKey was removed from the API

    • info

      the endpoint scheme security secretKey was removed from the API

  • 788718651767Revision changes
    • breaking

      added the new required request property

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the optional property from the response with the status

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      removed the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status