Points Exchange API
Use these APIs to perform points exchange transactions and offer new exchange options to your customers.

Point To Crypto

POST /transactions
The following transaction/loyalty event type is supported to perform this transaction:
  • points_to_external_rewards
The value of the cryptocurrency that is credited, will depend on the market rate of the said currency at the time this API call is made. The cryptocurrency will be sent through Coinbase. Visit the qiibee Loyalty Admin Dashboard to view the list of allowed cryptocurrencies. For more info regarding exchanging points to cryptocurrency, visit Exchange Currencies & NFTs - qiibee.
The following field is optional:
  • membership_number_override- string - use this field to override the user's saved email only for this action
    • It will not overwrite the saved email in the account.
If you try to exchange more points than the user currently has, you'll receive a 400.
Body:
  • amount can be an integer or string and not decimal/fraction. The amount has to conform to some certain thresholds. Check the limits (min and max) for the allowed cryptocurrencies here.
1
{
2
"transaction": {
3
"user_auth_id": "d0d15b76-1928-46bb-9927-8ffbf805f",
4
"type": "points_to_external_rewards",
5
"amount": "10",
6
"token_id": 12,
7
"exchange_provider_implementation_name": "coinbase",
8
"membership_number_override": "[email protected]",
9
"symbol": "btc"
10
}
11
}
Copied!
Responses
  • Success: HTTP 202
  • Bad request: HTTP 400
    • Insufficient balance
    • User/Token does not exist
    • Cryptocurrency/exchange provider unsupported
    • Invalid membership number
    • Feature unavailable

Point To Point

POST /transactions
The following transaction/loyalty event type is supported to perform this transaction:
  • exchange
This transaction involves two brands, Brand A (points to exchange from) and Brand B (points to exchange to).
For these transactions to work, it is important that the exchange is allowed from Brand A to Brand B. This is always one way. Head over to the Loyalty Admin Dashboard to check if the exchange partnership is in effect. For more info, visit Exchange Currencies & NFTs - qiibee.
The value of the points credited, will depend on the offramp value of Brand A's points and the onramp value of Brand B's points. The exchange rate is calculated as follows
exchange rate = Brand A token offramp value ÷ Brand B token onramp value
The following field is optional:
  • exchange_rate_override- integer: use this field to override the exchange rate.
    • It will not overwrite the saved token offramp and onramp values.
If you try to exchange more points than the user currently has, you'll receive a 400. The points to be received will be calculated as the floor of the value obtained after multiplying the points to be burned with the exchange rate.
Body:
  • amount can be an integer or string and not decimal/fraction.
1
{
2
"transaction": {
3
"user_auth_id": "87ydjs798ms-bnsi7gajn..."
4
"type": "exchange",
5
"brandA_token_id": 12,
6
"brandB_id": "0182d10b-9b83-42d3-99ff-dwsd...",
7
"brandB_membership_number": "brandB-n8y932y98n9..."
8
"amount": 10,
9
"brandB_token_id": 13,
10
"exchange_rate_override": 0.2
11
}
12
}
Copied!
Responses
  • Success: HTTP 202
  • Bad request: HTTP 400
    • Insufficient balance
    • User/Token does not exist
    • Exchange not allowed
    • Invalid membership number

Point To Miles

POST /transactions
The following transaction/loyalty event type is supported to perform this transaction:
  • points_to_external_rewards
The following fields are optional:
  • membership_number_override- string - use this field to override the user's saved membership number only for this action
    • It will not overwrite the saved number in the account
  • exchange_rate_override- integer - use this field to specify a different exchange rate from what you've configured.
    • eg. 1 point is 40 airline miles but you want to change it to 80 for a particular user based on their tier.
    • It will not overwrite the stored exchange rate
If you do not want to persist membership info for users you can send it with every request but for a better customer experience, we encourage you to store it using the memberships API.
If you try to exchange more points than the user currently has you'll receive a 400.
Body:
  • amount can be an integer or string.
1
{
2
"transaction": {
3
"user_auth_id": "d0d15b76-1928-46bb-9927-8ffbf802455f",
4
"type": "points_to_external_rewards",
5
"amount": "100",
6
"token_id": 12,
7
"exchange_provider_implementation_name": "etihad" | "miles_and_more",
8
"membership_number_override": "xxx...xxx",
9
"exchange_rate_override": "10"
10
}
11
}
Copied!
Responses
  • Success: HTTP 202
  • Bad request: HTTP 400
    • Insufficient balance
    • Invalid amount field
    • User/Token does not exist
    • Non existent exchange provider
    • Invalid membership number

Transaction History

GET /transactions
This request returns paginated transaction history.
By default, it returns the last 100 transactions associated with your brand. The most recent transactions are returned first.
You can query transactions using the following query parameters:
  • limit: (optional) sets the required limit of transaction history to be requested.
    • Defaults: 100
    • Maximum: 100
  • offset: (optional) number of transactions to offset when getting the remaining transactions.
    • Default: 0
  • user_auth_id: (optional) Use this parameter to query transactions for a particular user of your brand. If not passed returns all the transactions for your brand. Can be used along with limit and offset.
  • types: (optional) Use this parameter to query transactions for specific loyalty event types. The events must be sent in a list.
    • Defaults: List of all loyalty event types
  • token_id: (optional) This will let you query the transactions for a specific token ID.
    • Defaults: All tokens that belong to the brand.
The params, limit and offset, work exactly as they’re used in SQL.
Token types
  • erc20 is a regular token
  • erc721 is an NFT token
Token countries
  • AAA represents that the token is operational worldwide.

Responses

  • Success: HTTP 200 with data in the following format:
1
{
2
"data": {
3
"limit": 1,
4
"offset": 0,
5
"total_tx_count": 25,
6
"transactions": [
7
{
8
"amount_received": "1.00000",
9
"code": null,
10
"exchange_provider": "etihad" | "miles_and_more",
11
"id": 706,
12
"inserted_at": "2021-09-27T14:31:10",
13
"loyalty_event_type": "credit_points",
14
"points_burned": null,
15
"reward_id": null,
16
"status": "success",
17
"token": {
18
"id": "3276728",
19
"address": "033Bd49F3ace247112AA6D3d16d24F7Eb5533b17",
20
"metadata": {},
21
"name": "WORKING POINT TOKEN",
22
"estimated_member_count_lower": 1000,
23
"estimated_member_count_higher": 5000,
24
"symbol": "TKN",
25
"type": "erc20" | "erc721",
26
"countries": <list_of_ISO3166_country_codes>,
27
"onramp": "24.2" | null,
28
"offramp": "23.5" | null,
29
"status": "active" | "paused" | "pending"| "stopped" | null
30
},
31
"tx_hash": "0x..xx26",
32
"user": {
33
"auth_id": "9f7326f7-ee-41f4-9c10-aa9f12",
34
"country_ISO": "usa",
35
"email": "[email protected]",
36
"first_name": "Jane",
37
"second_name": "Doe",
38
"id": "NH3HQ==-87b7-2bcd-46ac-b426-0bb81",
39
"language": "en",
40
"metadata": null | {
41
"opts_newsletter": true | false
42
}
43
}
44
45
}
46
]
47
}
48
}
Copied!
If there are no transactions, an empty transactions list will be returned. total_tx_count is the total number of transactions available for the given params.
  • Bad data: HTTP 404 with error message
    • eg. not found