> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gameball.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Hold Points
> Place points on hold before redemption to reserve them for a specific transaction.
**Channel Merging Available**
If your system uses different customer IDs across multiple channels (e.g., online and offline), Gameball's channel merging feature helps unify customer profiles. By including the customer's mobile number or email (based on your merging configuration) with each request, Gameball will combine activities into a single profile.
Security: Provide both `apikey` and `secretkey` headers.
## OpenAPI
````yaml POST /api/v4.0/integrations/transactions/hold
openapi: 3.1.0
info:
title: Gameball API
description: >-
Gameball REST API v4.0 - Complete API reference for integrating loyalty,
gamification, and customer engagement features
version: 4.0.0
servers:
- url: https://api.gameball.co
security:
- bearerAuth: []
paths:
/api/v4.0/integrations/transactions/hold:
post:
description: >-
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.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- customerId
- transactionTime
properties:
customerId:
type: string
description: >-
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.
example: cust_abc12345xyz67890
email:
type: string
description: >-
Customer's email address. This is required if your account
uses email-based channel merging.
example: john.doe@example.com
mobile:
type: string
description: >-
Customer's mobile number. This is required if your account
uses mobile-based channel merging.
example: '+1234567890'
transactionTime:
type: string
format: date-time
description: >-
The time of the transaction in your system (e.g., order
datetime, invoice datetime).
example: '2024-10-11T16:15:15.071Z'
otp:
type: string
description: >-
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.
example: '654321'
ignoreOTP:
type: boolean
description: >-
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.
example: false
amountToHold:
type: number
description: >-
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.
example: null
pointsToHold:
type: integer
description: >-
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.
example: 50
ruleId:
type: string
description: >-
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.
example: null
hash:
type: string
description: >-
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: '123456'
responses:
'200':
description: Points placed on hold successfully
content:
application/json:
schema:
type: object
properties:
customerId:
type: string
description: >-
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.
example: cust_abc12345xyz67890
holdAmount:
type: number
description: >-
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.
example: '5'
holdEquivalentPoints:
type: number
description: >-
The number of points that have been held from the
customer's points balance. These points are reserved for
future use or specific transactions.
example: 50
holdReference:
type: string
description: >-
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: a2a199ad-86f3-45c4-8253-7aaee50e4798
security:
- apiKey: []
secretKey: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
apiKey:
type: apiKey
in: header
name: apikey
secretKey:
type: apiKey
in: header
name: secretkey
````