Sign in

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

Changed in 4 of the 38 revisions of this API.2316

  • 262228c134293See the full diff
    • ○

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

      api-security-added

    • ○

      the endpoint scheme security apiKey was removed from the API

      api-security-removed

    • ○

      the endpoint scheme security secretKey was removed from the API

      api-security-removed

  • 7887186517671312See the full diff
    • ▲

      added the new required request property transactionTime

      new-required-request-property

    • ●

      removed the request property holdReference

      request-property-removed

    • ●

      removed the request property points

      request-property-removed

    • ●

      removed the optional property success from the response with the 200 status

      response-optional-property-removed

    • ○

      added the new optional request property amountToHold

      new-optional-request-property

    • ○

      added the new optional request property email

      new-optional-request-property

    • ○

      added the new optional request property hash

      new-optional-request-property

    • ○

      added the new optional request property ignoreOTP

      new-optional-request-property

    • ○

      added the new optional request property mobile

      new-optional-request-property

    • ○

      added the new optional request property otp

      new-optional-request-property

    • ○

      added the new optional request property pointsToHold

      new-optional-request-property

    • ○

      added the new optional request property ruleId

      new-optional-request-property

    • ○

      removed the non-success response with the status 400

      response-non-success-status-removed

    • ○

      added the optional property customerId to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property holdAmount to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property holdEquivalentPoints to the response with the 200 status

      response-optional-property-added

  • 95e7f65e5afd1See the full diff
    • ○

      endpoint added

      endpoint-added

  • 919eb7a392aa1See the full diff
    • ▲

      api path removed without deprecation

      api-path-removed-without-deprecation

    This revision also has 38 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog