Points Engine API

This page contains endpoints for additional features that you use to enhance your loyalty program.
Codes
Use this set of endpoints to manage codes that can be given out to users for points.
Create Code
POST /codes
Create a new code. 
We will give you all your campaign_id values.
Fields:
value - value of points the code is worth
The external reward rate will be calculated based on your settings.
eg. if 1 point is 10 miles, then a code of 5 points is worth 50 miles.
campaign_id - all the IDs for your campaigns will be provided by us
length - optional. Length of the code to generate.
Minimum: 9
Default: 9
email - optional. If an email is passed we will also send the user an email with the code generated. You can choose a template or make a new one. Defaults to null. The email will be validated, failing which, it returns a 400. To send out emails via qiibee, please write to us at [email protected].
language - optional. Language for the email. Defaults to en 
reference_id - optional. type: string. 
is used as a duplicate check, so if it's sent it always needs to be unique for every request. The uniqueness is determined along with the campaign_id.
For example, you could pass your internal receipt/order ID to make sure that one transaction in your system is never processed twice, even if you happen to send the request twice.
eg. 
{
    "code": {
        "value": "100",
        "campaign_id": 1,
        "language": "en",
        "reference_id": "Order 109348HJ61"
    }
}
Responses:
Success: HTTP 201 and the code:
{
    "data": {
        "code": "719026461",
        "value": "100",
        "campaign_id": 1,
        "reference_id": "Order 109348HJ61"
    }
}
Bad request: HTTP 400
eg. Invalid campaign id or Code length too short
Conflict: HTTP 409 when reference_id was already used
NFTs
Manage your NFTs and approve/reject user personalisations like engravings and personal messages. 
Mint/credit NFT to user
POST /transactions
Use this endpoint to credit an NFT to the user's account.
Populate the request body with the following fields. All fields are mandatory.
type (string): "credit_nft" indicates the type of transaction.
token_id (number): This is the token ID of your NFT as saved in our system.
user_auth_id (string): The auth ID of the user to whom the NFT should be credited 
Example request:
{
    "transaction": {
        "type": "credit_nft",
        "token_id": 387,
        "user_auth_id": "9f7326f7-ee-41f4-9c10-aa9f12"
    }
}
Responses:
Success: HTTP 202
Bad data: HTTP 400 with error message
Transfer NFT ownership
POST /transactions
Use this endpoint to transfer an NFT from one user's account to another.
Populate the request body with the following fields. All fields are mandatory.
type (string): "nft_transfer" indicates the type of transaction.
token_id (number): This is the token ID of your NFT as saved in our system.
user_auth_id (string): The auth ID of the user to whom the NFT should be transferred from. This user owns the NFT.
user_b_auth_id (string): The auth ID of the user to whom the NFT should be transferred to.
nft_id (number): The ID tied tied to the NFT.
Example request:
{
    "transaction": {
        "type": "nft_transfer",
        "token_id": 387,
        "user_auth_id": "9f7326f7-ee-41f4-9c10-aa9f12",
        "user_b_auth_id": "5dw326f7-th-1631-xc10-ab9h15",
        "nft_id": 0
    }
}
Responses:
Success: HTTP 202
Bad data: HTTP 400 with error message
Approve/Reject NFT personalisation (deprecated)
POST /nfts
Use this endpoint to approve or reject a user's NFT personalisation. 
If you reject it, the user will receive an email asking them to change the personalisation. You can pick from existing mail templates or create a new one. 
All fields are mandatory.
Example request:
{
    "userNFT": {
      "user_nft_id": "37329",
      "status": "approved" | "rejected"
    }
}
​
List NFTs Owned By a User
GET /nfts
This endpoint returns a list of NFTs that are owned by a given user. You need to pass in the following query parameters:
user_auth_id: (mandatory) the auth_id of the user who owns the NFTs.
status: (optional) the status of the NFT. If not sent, it will query the NFTs irrespective of their status. The status can only be one of [null, "pending", "approved", "rejected"].
token_id: (optional) the token ID of a specific NFT. If not sent, the response body will contain all the NFTs that are tied to the sent user_auth_id.
Example response:
{
  "data": [
    {
      "name": "My Test Token",
      "personalised_data": {"key": "value"},
      "status": null | "pending" | "approved" | "rejected",
      "type": "erc721",
      "user_nft_id": 28
    },
    {
      "name": "My Test Token",
      "personalised_data": {"key": "value"},
      "status": null | "pending" | "approved" | "rejected",
      "type": "erc721",
      "user_nft_id": 29
    }
  ]
}
Tokens
Manage your tokens (loyalty point, NFTs).
Get Token Details
GET /tokens/:token_id
This endpoint will fetch a token and the associated with your brand and the specified token_id. This will also return the amount of points that have been issued and burned of your loyalty point.
Responses:
Success: HTTP 200 with data in the following format:
{
    "data": {
        "issued": "221.0000",
        "burned": "453.000",
        "token": null | {
            "id": "23421",
            "address": "0x..3849hz654",
            "name": "My Token Name",
            "type": "erc20" | "erc721" | "external",
            "metadata": {
                "key": "value"
            },
            "estimated_member_count_lower": 1000,
            "estimated_member_count_higher": 5000,
            "countries": <list_of_ISO3166_country_codes>,
            "onramp": "24.2" | null,
            "offramp": "23.5" | null,
            "status": "active" | "paused" | "pending"| "stopped" | null,
            "brand_id": <your_brand_id>,
            // NFT fields
            "supply": null | 100,
            "can_sell": true | false,
            "sales_fee_percentage": null | 7,
            "can_transfer": true | false,
            "can_redeem": true | false,
            "created_at": "2022-05-25T07:43:38"
        },
    }
}
Bad data: HTTP 400 with error message
Not Found: HTTP 404
List tokens
GET /tokens/
This endpoint will fetch a list of tokens associated with your brand with the query params as mentioned below.
types: (optional) a list of token types that you want to fetch. Defaults to all token types that qiibee supports.
type: list
eg: ["erc20", "erc721"]
status: (optional) the status of the token. Defaults to all status types that qiibee supports.
type: string
eg: "active", "pending", "stopped", "paused", 'rejected"
An empty list will be returned if no tokens are found.
Response:
Success: HTTP 200 with data in the following format. The tokens will be ordered by their age (date at which created).
{
    "data": [
              {
                "id": "23421",
                "address": "0x..3849hz654",
                "name": "My Token Name",
                "type": "erc20" | "erc721" | "external",
                "metadata": {
                    "key": "value"
                },
                "estimated_member_count_lower": 1000,
                "estimated_member_count_higher": 5000,
                "countries": <list_of_ISO3166_country_codes>,
                "onramp": "24.2" | null,
                "offramp": "23.5" | null,
                "status": "active" | "paused" | "pending"| "stopped" | null,
                "brand_id": <your_brand_id>,
                // NFT fields
                "supply": null | 100,
                "can_sell": true | false,
                "sales_fee_percentage": null | 7,
                "can_transfer": true | false,
                "can_redeem": true | false,
                "created_at": "2022-05-25T07:43:38"
              },
          ]
}
Rewards
Manage your rewards. Eg. Discount Coupons
Users exchange points for a reward. 
Soon you will also be able to send rewards to users dynamically.
Get Reward Details
GET /rewards/:reward
This endpoint will fetch a reward and the associated transaction, used_at, anduser_id if it has already been sent to a user. 
Check out the Transactions section of the documentation to see what the loyalty event types are.
Token types
erc20 is a regular token
erc721 is an NFT token
external is a non points bank token
fiat represents fiat currencies
miles represents the miles tokens
crypto represents cryptocurrencies
donation represent donation campaigns
Token countries
AAA represents that the token is operational worldwide.
Responses:
Success: HTTP 200 with data in the following format:
{
    "data": {
        "code": "testcode29",
        "reward_type": {
            "id": 1,
             "locations": [
              {
                  "id": "2039",
                  "street": "Falkenstrasse",
                  "city": "Zurich",
                  "country": "Switzerland",
                  "zip": "8008",
                  "geolocation": "Geolocation point"
              }
          ],
            "metadata": {
                "coverImage": "https://picsum.photos/id/1025/200/300"
            },
            "name": "Online Coupon",
            "valid_urc20" | "erc721",
                "metadata": {
                    "key": "value"
                },
                "estimated_member_count_lower": 1000,
                "estimated_member_count_higher": 5000,
                "countries": <list_of_ISO3166_country_codes>,
                "onramp": "24.2" | null,
                "offramp": "23.5" | null,
                "status": "active" | "paused" | "pending"| "stopped" | null
                
            },
        "tx_hash": "0x.......293dsf23"
        "used_at": null | "2021-09-28T14:57:49Z",
        "user": null | {
            "id": "3r2esf3423r",
            "email": "[email protected]",
            "auth_id": "e24c962d-c81c-4a01-b0cd-57dd233553f1",
            "first_name": "John",
            "second_name": "Doe",
            "language": "en",
            "country_ISO": "usa",
             "metadata": null | {
                 "opts_newsletter": true | false
                 }
             }
        }
    }
}
Bad data: HTTP 404 with error message
eg. not found
Redeem a Reward
PUT /rewards/:reward | PATCH /rewards/:reward
This endpoint is used to mark a reward as used.
We mark it as used by setting the used_at property to the UTC time of the request.
Currently, each reward can be used only once.
Token types
erc20 is a regular token
erc721 is an NFT token
external is a non points bank token
fiat represents fiat currencies
miles represents the miles tokens
crypto represents cryptocurrencies
donation represent donation campaigns
gift_card represent gift cards
​
Token countries
AAA represents that the token is operational worldwide.
Responses
Success: HTTP 200 with data in the following format:
{
    "code": "SPECIAL20",
    "used": true,
    "user": {
      "id": "3253124153214",
      "auth_id": "e24c962d-c81c-4a01-b0cd-57dd233553f1",
      "first_name": "Jane",
      "second_name": "Doe",
      "email": "[email protected]",
      "language": "en",
      "country_ISO": "usa",
      "metadata": null | {
        "opts_newsletter": true | false
        }
      }
    },
    "reward_type": {
        "id": 10,
        "name": "20 EUR Discount",
        "value": "100",
        "website": "www.domain.com",
        "valid_until": "1659515347",
        "locations": [
            {
                "id": "2039",
                "street": "Falkenstrasse",
                "city": "Zurich",
                "country": "Switzerland",
                "zip": "8008",
                "geolocation": "Geolocation point"
            }
        ]
    },
    "transaction": {
        "id": "284798327469",
        "loyalty_event_type": "points_to_rewards",
        "exchange_provider": "etihad" | "miles_and_more",
        "tx_hash": "0x.......293dsf23",
        "points_burned": "100",
        "token": null | {
            "id": "23421",
            "address": "0x..3849hz654",
            "name": "My Token Name",
            "type": "erc20" | "erc721",
            "metadata": {
                "key": "value"
            },
            "estimated_member_count_lower": 1000,
            "estimated_member_count_higher": 5000,
            "countries": <list_of_ISO3166_country_codes>,
            "onramp": "24.2" | null,
            "offramp": "23.5" | null,
            "status": "active" | "paused" | "pending"| "stopped" | null
        },
        "status": "success",
        "reward_id": 3443,
        "inserted_at": "2022-05-25T07:43:38"
    }
}
Conflict: HTTP 409
If the reward was already marked as used
Bad data: HTTP 404 with error message
eg. not found
Transactions
Point to Reward
POST /transactions
The following transaction/loyalty event type is supported to perform this transaction:
points_to_rewards - redeem points for a reward like a discount coupon
Redeem Point
All fields are mandatory.
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.
{
    "transaction": {
        "user_auth_id": "d0d15b76-1928-46bb-9927-8ffbf802455f",
        "type": "points_to_rewards",
        "amount": "100",
        "token_id": 12,
        "reward_type_id": 2432
    }
}
Responses
Accepted: HTTP 202
Bad Request: HTTP 400
eg. unknown transaction type
Bad data: HTTP 404 with error message
eg. not found
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
Token types
erc20 is a regular points bank token
erc721 is an NFT token
external is a non points bank token
fiat represents fiat currencies
miles represents the miles tokens
crypto represents cryptocurrencies
donation represent donation campaigns
gift_card represent gift cards
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
Points Bank API
Next - qiibee Loyalty API
Exchange Options
Last modified 1mo ago