Skip to content
Hubble logo Hubble logo Hubble Documentation

Coin Integration

The Hubble SDK supports a powerful feature that allows your users to burn their in-app currencies or “coins” to get discounts on gift card purchases. To enable this, you will need to expose a set of APIs that our backend can call to manage user coin balances.

Coin Burn Models

We support two primary models for burning coins, which can be configured based on your needs:

1. Coins as Additional Discount

In this model, coins provide an additional discount on top of any existing offers.

Example: A user is buying a voucher that already has a 5% discount, saving them ₹100. If the user has 100 coins, they can use them to get an additional ₹100 off, increasing their total savings.

2. Coins to Enable Discount

In this model, coins are required to unlock the discount in the first place.

Example: A user is buying an Amazon voucher worth ₹1000 with a discount of ₹20. To avail this discount, the user must have and spend at least 20 coins.

The conversion ratio (e.g., 1 coin = ₹1), limits on coin usage, and other rules can be configured from our end.

Required APIs

To power the coin integration, you need to expose the following APIs for our backend to consume.

1. Get Coin Balance

An API to get a user’s current coin balance.

  • Request: Our backend will call this endpoint with the user’s ID.
  • Response: You should return the user’s total available coins.

Request Parameters:

  • userId

Response Body:

{
  "userId": "user-123",
  "totalCoins": 500
}

2. Debit Coins

An API to debit coins from a user’s account when they make a purchase.

  • Request: Our backend will specify the user and the number of coins to debit.
  • Response: You should return the status of the transaction, a unique transaction ID, and the new balance.

Request Parameters:

  • userId
  • coinsToDebit

Response Body:

{
  "status": "success",
  "coinTransactionId": "txn-abc-456",
  "newBalance": 450
}

3. Reverse A Debit

An API to reverse a debit in case voucher generation fails on Hubble’s end.

  • Request: Our backend will provide the userId and the original coinTransactionId to reverse.
  • Response: You should return the status of the reversal and the new coin balance.

Request Parameters:

  • userId
  • coinTransactionId

Response Body:

{
  "status": "success",
  "newBalance": 500
}