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 [e-mail].

• 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": "[e-mail]",
            "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": "[e-mail]",
      "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": "[e-mail]",
                    "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": "[e-mail]",
                    "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