Points Exchange API

Search…
Points Exchange API
Use these APIs to perform points exchange transactions and offer new exchange options to your customers.
Exchange
POST /transactions
The following types of of exchange options are currently supported by the qiibee API
All points_to_external_rewards requests have been migrated to exchange type. Depending on the value of brandB_token_id that's passed, determines the exact type of exchange. 
To get the value of brandB_token_id, please check the Exchange partnerships endpoint.
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 value of the cryptocurrency that is credited, will depend on the market rate of said currency at the time this API call is made. Note that exchange to crypto is not available in the sandbox API.
The following fields are optional:
exchange_rate_override: number - 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
brandB_membership_number: 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. The format followed is specified at Membership numbers.
If you do not wish 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 APIs in the Users API section.
If you try to exchange more points than the user currently has, you'll receive a 400. The points/miles to be received will be calculated as the floor of the value obtained after multiplying the points to be burned with the exchange rate. When exchanging to crypto, the floor is not applied to the amount of crypto to be received.
Note:
If you are a light integration user, please make sure that you have registered your webhook URL with us. Head over to Webhooks to learn more. We will call this URL when an exchange transaction has occurred so you can credit the points to your user.
Body: 
amount - The amount of brand A points to be burned. Can be an integer or string but not decimal/fraction.
user_auth_id - The identifier by which a user is identified in your loyalty program.
{
    "transaction": {
        "user_auth_id": "87ydjs798ms-bnsi7gajn..."
        "type": "exchange",
        "brandA_token_id": 12,
        "amount": 10,
        "brandB_token_id": 13,
        "exchange_rate_override": 0.2,
        "brandB_membership_number": "1234567"
    }
}
Responses
Success: HTTP 202
Bad request: HTTP 400
Insufficient balance
User/Token does not exist
Exchange not allowed
Invalid membership number
Exchange partnerships
GET /token-exchange-whitelist
This request returns the list of active exchange partnerships to the brands with whom you're connected. It contains the token IDs that you would need to pass in the request to perform exchange transactions.
The exchange limits can be updated in the Loyalty Admin Dashboard. You can use these to check if the points to be burned is within the specified limit.
Token types
erc20 is a regular points bank token
erc721 is an NFT token
external is a non points bank token
Responses
Success: HTTP 200 with data in the following format:
{
    "data": {
        [
            "id": 21,
            "from_token": {
                "id": "32768",
                "address": "033Bd49F3ace247112AA6D3d16d24L9Eb5533b17",
                "metadata": {},
                "name": "WORKING POINT TOKEN",
                "symbol": "TKN",
                "type": "erc20" | "external",
                "onramp": "24.2" | null,
                "offramp": "23.5" | null
            },
            "to_token": {
                "id": "32726",
                "address": "056Bd49F3ace247112AA6D3d16d24L9Vb5533b17",
                "metadata": {},
                "name": "WORKING POINT TOKEN 2",
                "symbol": "TKN",
                "type": "erc20" | "external" | "miles" | "crypto",
                "onramp": "24.2" | null,
                "offramp": "23.5" | null
            },
             "status" => "active",
             "max_usd_exchange_limit": "100.000000000000000000",,
             "min_usd_exchange_limit": "0.010000000000000000",
             "timestamp": "2022-09-19T11:38:07"
         ]
    }
}
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.
from_time:  (optional) queries for transactions that begin from the specified datetime.
Defaults: The datetime at which the brand was created in the qiibee database.
to_time: (optional) queries for transactions until the specified datetime.
Defaults: The current datetime.
Time parameters
In the time parameters, the date and time must be expressed according to ISO 8601.
eg:  The datetime for 06 June 2022 at 11:23:23 AM will be expressed as 2022-06-01T11:23:23Z
 The params, limit and offset, work exactly as they’re used in SQL.
Token types
erc20 is a regular points bank token
erc721 is an NFT token
external is a non points bank token
Token countries
 AAA represents that the token is operational worldwide.
Responses
Success: HTTP 200 with data in the following format:
{
    "data": {
        "limit": 1,
        "offset": 0,
        "total_tx_count": 25,
        "transactions": [
            {
                "amount_received": "1.00000",
                "brand": null,
                "brand_to": {
                    "brand_config": null,
                    "id": "test_brand2",
                    "locations": [],
                    "name": "Test Brand 2"
                },
                "code": null,
                "exchange_provider": "etihad" | "miles_and_more",
                "id": 706,
                "inserted_at": "2021-09-27T14:31:10",
                "loyalty_event_type": "credit_points",
                "points_burned": null,
                "reward_id": null,
                "status": "success",
                "token": {
                    "id": "3276728",
                    "address": "033Bd49F3ace247112AA6D3d16d24L9Eb5533b17",
                    "metadata": {},
                    "name": "WORKING POINT TOKEN",
                    "estimated_member_count_lower": 1000,
                    "estimated_member_count_higher": 5000,
                    "symbol": "TKN",
                    "type": "erc20" | "erc721",
                    "countries": <list_of_ISO3166_country_codes>,
                    "onramp": "24.2" | null,
                    "offramp": "23.5" | null,
                    "status": "active" | "paused" | "pending"| "stopped" | null
                },
                "token_to": {
                    "id": "3276726",
                    "address": "056Bd49F3ace247112AA6D3d16d24L9Vb5533b17",
                    "metadata": {},
                    "name": "WORKING POINT TOKEN 2",
                    "estimated_member_count_lower": 1000,
                    "estimated_member_count_higher": 5000,
                    "symbol": "TKN",
                    "type": "erc20" | "erc721",
                    "countries": <list_of_ISO3166_country_codes>,
                    "onramp": "24.2" | null,
                    "offramp": "23.5" | null,
                    "status": "active" | "paused" | "pending"| "stopped" | null
                },
                "tx_hash": "0x..xx26",
                "user": {
                    "auth_id": "9f7326f7-ee-41f4-9c10-aa9f12",
                    "country_ISO": "usa",
                    "email": "[email protected]",
                    "first_name": "Jane",
                    "second_name": "Doe",
                    "id": "NH3HQ==-87b7-2bcd-46ac-b426-0bb81",
                    "language": "en",
                    "metadata": null | {
                        "opts_newsletter": true | false
                     }
                },
                "user_to": {
                    "auth_id": "9f7326f7-ee-41f4-9c10-aa9f12",
                    "country_ISO": "usa",
                    "email": "[email protected]",
                    "first_name": "John",
                    "second_name": "Doe",
                    "id": "NH3HQ==-8745-2bcd-46ac-b426-0bb81",
                    "language": "en",
                    "metadata": null | {
                        "opts_newsletter": true | false
                     }
                }
​
            }
        ]
    }
}
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
qiibee Loyalty API - Previous
Users API
Next - qiibee Loyalty API
Points Bank API
Last modified 12d ago
Copy link
On this page
Exchange
Exchange partnerships
Transaction History