Redemption Configurations

This API retrieves the configurations and rules associated with how customers can redeem points for discounts, coupons, or other rewards.

Security: Requires apikey header.

Authorizations

apikey

string

header

required

Query Parameters

customerId

string

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. If provided, the API will return redemption configurations that match the customer based on various criteria, such as RFM, tiers, segments and specific customer attributes. This approach ensures that the redemption options are personalized and relevant to each customer's unique profile and engagement history.

Response

200 - application/json

Redemption configurations retrieved successfully

redemptionFactor

number

This factor indicates the value of each loyalty point in terms of currency, defining how many currency units can be obtained by redeeming points. Example: If the redemptionFactor is set to 0.1, this means that a customer can redeem 10 points for 1 USD.

Example:

0.1

redemptionRules

object[]

A list of redemption rules that define how points can be redeemed for discounts and coupons. Defines the rules for redeeming points, including points required, value of points, applicable coupons, and eligibility criteria. Example: a redemption rule may allow points to be redeemed for a free product, free shipping, percentage-based discounts, or fixed-amount discounts.

Show child attributes

redemptionRules.id

number

The unique identifier for the redemption rule.

Example:

2138

redemptionRules.pointsToRedeem

number

The specific number of points needed for redemption. If null, the rule applies to all points.

Example:

100

redemptionRules.valueOfPoint

number

The value of a single point in terms of monetary value for redemption.

Example:

25

redemptionRules.ruleType

string

The type of rule governing the redemption. Possible values include: free_shipping_settings, percentage_discount_settings, free_product_settings, fixed_rate_settings.

Example:

"percentage_discount_settings"

redemptionRules.coupon

object

Defines the coupon associated with the redemption rule, if applicable.

Show child attributes

redemptionRules.coupon.couponType

string

The type of coupon applied. Possible values include: free_shipping, percentage_discount, fixed_discount, fixed_rate_discount, free_product, custom.

Example:

"percentage_discount"

redemptionRules.coupon.discountValue

number

The value of the discount provided by the coupon in case the coupon type is fixed_discount, percentage_discount or fixed_rate_discount.

Example:

25

redemptionRules.coupon.product

object

Product information for free product coupons.

Show child attributes

redemptionRules.coupon.product.productId

string

The unique identifier for the product.

redemptionRules.coupon.product.productName

string

The name of the product.

redemptionRules.coupon.product.variantId

string

The unique identifier for the product variant.

redemptionRules.coupon.product.variantName

string

The name of the product variant.

redemptionRules.coupon.product.productDisplayName

string

The display name associated with the product that configured on the dashboard based on required language.

redemptionRules.coupon.collections

object[]

A list of collection IDs that the coupon can be applied to.

Show child attributes

redemptionRules.coupon.collections.collectionId

string

The unique identifier for the collection.

Example:

"455218036961"

redemptionRules.coupon.collections.collectionName

string

The name for the collection.

Example:

"Automated Collection"

redemptionRules.coupon.group

object

Coupon group information.

Show child attributes

redemptionRules.coupon.group.handle

string

A unique identifier used to reference the coupon group in the system (only appears in the dashboard).

redemptionRules.coupon.group.title

string

The title of the coupon group.

redemptionRules.coupon.group.url

string

The URL for the coupon group.

redemptionRules.coupon.group.iconPath

string

The path to the icon of the coupon group.

redemptionRules.coupon.group.description

string

A description of the coupon group.

redemptionRules.coupon.group.maxPerCustomer

number

The maximum number of times a customer can use the coupon. Example: 5 indicates that each customer can redeem this coupon up to 5 times.

redemptionRules.coupon.group.startDate

string<date-time>

The date when the coupons within this coupon group will become active and valid for redemption.

redemptionRules.coupon.group.expiryDate

string<date-time>

The date when the coupons within this coupon group will expire and no longer be valid for redemption.

redemptionRules.coupon.group.isAvailable

boolean

Indicates whether the coupon group is currently available.

redemptionRules.coupon.group.isActive

boolean

Indicates whether the coupon group is currently active.

redemptionRules.coupon.options

object

Coupon options and settings.

Show child attributes

redemptionRules.coupon.options.name

string

The name of the redemption rule configured on the dashboard based on required language.

Example:

"Redemption Rule Name"

redemptionRules.coupon.options.expiryAfter

number

The number of days after creation that the coupon will expire. Example: If a coupon expires after 14 days, the customer must use it within that period to receive the discount.

Example:

14

redemptionRules.coupon.options.usageLimit

number

The maximum number of times a single coupon can be used. Example: If a coupon has a usage limit of 5, it can be redeemed up to 5 times before it becomes invalid.

Example:

2

redemptionRules.coupon.options.capping

number

The maximum discount value a coupon can provide, regardless of the order amount. Example: If a coupon offers 20% off with a capping of $50, the discount will not exceed $50, even if 20% of the order total is higher.

Example:

50

redemptionRules.coupon.options.minOrderValue

number

The minimum order amount required to apply the coupon. Example: If a coupon has a minimum order value of $100, the customer must spend at least $100 to use the discount.

Example:

150

redemptionRules.coupon.options.codePrefix

string

The prefix that will be added to the beginning of the generated coupon code. Example: If the prefix is 'SUMMER', the generated coupon codes might look like 'SUMMER12345' or 'SUMMERDISCOUNT'.

Example:

"SUMMER"

redemptionRules.coupon.options.redeemInstructions

string

The instructions on how the customer can redeem the coupon. Example: 'Enter the coupon code at checkout to apply the discount.'

Example:

"Enter the coupon code at checkout to apply the discount."

redemptionRules.image

string

A URL or file path for an image representing the redemption rule.

Example:

"https://s3.us-east-2.amazonaws.com/gameball.stg.uploads/uploads%2fClient_2933%2f936f65d8-e06d-4e28-b423-b5282999801bgameball.webp"

redemptionRules.creationDate

string<date-time>

The date when the redemption rule was created.

Example:

"2025-02-10T10:12:16.783408"

redemptionRules.isActive

boolean

Indicates whether the redemption rule is currently active and can be used to generate new coupons or not. true → The rule is active, and new coupons can be created and redeemed. false → The rule is inactive, meaning no new coupons can be generated. However, previously created coupons will still be valid and can be redeemed. Example: If isActive is false, customers cannot create new coupons, but any coupons generated before the rule became inactive can still be used.

Example:

true

API documentation

Webhooks

Redemption Configurations