Points Engine API

Search…
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.
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.
Approve/Reject NFT personalisation
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"].
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
    }
  ]
}
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
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_until": "2021-11-23T15:19:19Z",
            "value": 5,
            "website": "https://qiibee.com/?extralong_link=verylonglink"
        },
        "transaction": {
            "amount_received": "20.000",
            "code": null | "GDUTY5F",
            "exchange_provider": "etihad" | "miles_and_more",
            "id": 562,
            "inserted_at": "2021-08-10T15:53:25",
            "loyalty_event_type": "points_to_rewards",
            "points_burned": 5,
            "reward_id": 29,
            "status": "success",
            "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
                
            },
        "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
​
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": "1627976023"
    }
}
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
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 12d ago
Copy link
On this page
Codes
Create Code
NFTs
Approve/Reject NFT personalisation
List NFTs Owned By a User
Rewards
Get Reward Details
Redeem a Reward
Transactions
Point to Reward
Transaction History