# Introduction

Placewise Rewards is a Loyalty Program that awards members for achieving some defined goals with points.

The points may be spent on acquiring (purchasing) special rewards and then using them.
Points may expire after some time.

Participation in program is optional, so member can enroll (join) to it and leave it.

## Achievements

Every Loyalty Club that has Placewise Rewards enabled, has defined list of achievements that have rules attached to them.
The rules are described below.

## Achievement model

Key | Type | Description
--------- | --------- | ---------
id | integer | Achievement id
type | string | see [Achievement types](doc-341651#achievement-types)
name | string | Display name of the rule. Depends on [X-Locale header](doc-341635#x-locale-header)
points | integer | How many points the achievement grants
limit | integer | Maximum number of times the member can have the achievement granted (when null, there's no limit)
frequency | Object | How often the achievement may be granted to member (when null, there are no constraints). For example, achievement with frequency defined as `{"timespan": "day", "limit": 5}` means that member may get points for it at most 5 times a day.
frequency['timespan'] | string | One of: `['hour', 'day', 'week', 'month', 'year']`
frequency['limit'] | integer |

### Achievement types

type | Event
---- | -----------
app_opened | The member opened the loyalty club mobile application
coupon_used | Member used some coupon
link_clicked | Member clicked on link that has been sent from us
email_opened | Member opened an email that has been sent from us
push_opened | Member opened a push message that has been sent from us
wifi_approached | Member approached (logged in to) loyalty club's WiFi
geofence_approached | Member approached geofence defined by loyalty club mobile application
beacon_approached | Member approached one of loyalty club's beacons
consent_granted | Member granted one of loyalty club's consents

## Member levels

> Example configuration for regular levels

```json
{
    "type": "regular",
    "levels": [
        {
            "name": "1",
            "points_threshold": 0
        },
        {
            "name": "2",
            "points_threshold": 300
        },
        {
            "name": "3",
            "points_threshold": 500
        },
        {
            "name": "4",
            "points_threshold": 500
        }
    ]
}
```

> Example configuration for virtual level

```json
{
    "type": "virtual_level",
    "maximum_points": 1500
}
```

Loyalty Club may have members level defined (available in [Rewards Program > Get info](api-3510873) response).
There are two types of them: `regular` and `virtual_level`.

### Regular levels

When regular levels are enabled, members get levels based on the amount of points that they have earned
in program (in **total**, not the current balance) and may need to have minimal level to purchase some rewards.

Each level has `points_threshold` value (integer) that describes how many points are needed to reach the level (first level always requires 0 points to have).
Levels are returned in ascending order, sorted by the `points_threshold` attribute.

### Single virtual level

When single virtual level is enabled, it is just used to show member how he performs in the Rewards Program.

It defines `maximum_points` value, that is meant to be compared with member's **current** points balance.

### Transaction types 

Type | Description |
----- | -----------
achievement | Addition of points triggered by fulfilling an achievement goal
reward_purchase | Reduction of points caused by purchasing a reward by member
expiration | Reduction of points caused by automatic expiration of old transactions
correction | Change of points caused by admin's manual correction
grant | Arbitrary addition of points 
cancellation | Cancellation of another transaction

## Common error responses

Status | Response body
--------- | -----------
`467` | `{"error": "Member is banned!", "banned_until": "2020-10-28T17:24:06.207Z"}` | -
`480` | `{"error": "Member is not participating in Rewards Program"}` | -