Last Updated: Friday, November 15, 2019
Overview
The Incentives Manager is a module in the Vibes Mobile Engagement Platform that allows the issuance and redemption of incentive codes.
When issuing a code, you must provide the pool that you want the code to come from. However, if you want to see the status of a code, or redeem a code, you only need to provide the company and code, and we'll figure out which pool the code is on. This enables your redemption system to not worry about pools, and only check the validity of codes regardless of what pool they came from.
Topics in this Section
Incentive Pool Entity
The following is the JSON representation of an Incentive Pool entity within the APIs.
{
"id": 42,
"name": "Store Coupons",
"issuance_allowed": true,
"redemption_allowed": true,
"incentive_codes": {
"total": 500,
"issued": 143,
"remaining": 357,
"low_threshold": 100,
"max_characters": 50
},
"distribution": {
"method": "unique"
},
"notification_email_address": "your.name@vibes.com",
"created_at":"2017-01-01T12:00Z",
"updated_at":"2017-04-07T12:00Z",
"url":"/companies/:company_id/incentives/pools/:pool_id"
}
Elements
| Data Element | Type | Max Char Length | Description |
|---|---|---|---|
id | Integer | 20 | Vibes unique identifier for each Incentive Pool. |
name | String | The name of the Incentive Pool. | |
| issuance_allowed | Boolean | Whether issuance of codes is allowed. | |
| redemption_allowed | Boolean | Whether redemption of codes is allowed. | |
incentive_codes | Object | An object describing this pool's Incentive Codes. | |
| incentive_codes.total | Integer | Total number of Incentive Codes in the pool. | |
incentive_codes.remaining | Integer | Remaining number of available Incentive Codes in the pool. | |
incentive_codes.low_threshold | Integer | The number of remaining Incentive Codes where a notification is sent. | |
| incentive_codes.max_characters | Integer | The maximum number of characters allowed in an Incentive Code in this pool. | |
| distribution | Object | An object describing this pool's distribution type. | |
| distribution.method | String | 10 | The method of distribution (unique|multi). |
| notification_email_address | String | The email address for all notifications. | |
| created_at | Timestamp | 20 | The date this pool was created. It should be in the ISO 8601 format - for example: 2017-01-01T12:00Z. |
| updated_at | Timestamp | 20 | The date this pool was last updated. It should be in the ISO 8601 format - for example: 2017-04-07T12:00Z. |
| url | String | 50 | The URL to access this resource. |
Incentive Code Entity
The following is the JSON representation of an Incentive Code entity within the APIs.
{
"code": "coupon01",
"active": true,
"issuances": {
"total": 2,
"unique": 1
},
"redemptions": {
"total": 1,
"unique": 1
},
"incentive_pool": {
"id": 42,
"url": "/companies/:id/incentives/pools/:pool_id"
},
"created_at: "2017-01-18T17:24Z",
"updated_at: "2017-04-18T17:24Z",
"url": "/companies/:company_id/incentives/codes/:code"
}
Elements
| Data Element | Type | Max Char Length | Description |
|---|---|---|---|
incentive_pool_id | Integer | 20 | Vibes unique identifier for each Incentive Pool. |
code | String | The incentive code | |
| active | Boolean | Whether issuance of the incentive code is currently allowed. | |
| issuances | Object | An object describing this code's issuances. | |
| issuances.total | Integer | The total number of times this code has been issued. | |
| issuances.unique | Integer | The number of unique times this code has been issued. | |
| redemptions | Object | An object describing this code's redemptions. | |
| redemptions.total | Integer | The total number of times this code has been redeemed. | |
| redemptions.unique | Integer | The number of unique times this code has been redeemed. | |
| created_at | Timestamp | The date this code was created. It should be in the ISO 8601 format - for example: 2017-01-18T17:24Z. | |
| updated_at | Timestamp | The date this code was last updated. It should be in the ISO 8601 format - for example: 2017-04-18T17:24Z. | |
| url | String | The URL to access this resource. |
Incentive Code Issuance Entity
The following is the JSON representation of an Incentive Code entity within the APIs.
{
"id": 8,
"external_issuee_id": "user@mycompany.com",
"issuee_id": "0eef8961-7568-485b-9b13-fc7dbd1cf712",
"referring_application": "system",
"referring_application_ref_id": "1234",
"incentive_code": {
"code": "aabb-ccdd",
"url": "/companies/:company_id/incentives/codes/:code"
},
"incentive_pool": {
"id": 1,
"url": "/companies/:company_id/incentives/pools/:pool_id"
},
"updated_at": "2017-04-13T18:34Z",
"created_at": "2017-02-13T18:34Z"
}
Elements
| Data Element | Type | Description |
|---|---|---|
id | Integer | Vibes unique identifier for each issuance. |
| external_issuee_id | String | Unique external issuee ID. |
| issuee_id | String | Vibes generated issuee ID. |
| referring_application | String | Application issuing the code. |
| referring_application_ref_id | String | Application reference ID (campaign ID). |
incentive_code | Object | An object describing this Issuance's Incentive Code. |
| incentive_code.code | String | Incentive Code. |
incentive_code.url | String | Incentive Code's URL. |
incentive_pool | Object | An object describing this Issuance's Pool. |
| incentive_pool.id | Integer | The unique identifier for the pool. |
| incentive_pool.url | String | The URL to access the Incentive Pool resource. |
| created_at | Timestamp | The date this Issuance was created. It should be in the ISO 8601 format - for example: 2017-02-13T18:34Z. |
| updated_at | Timestamp | The date this Issuance was last updated. It should be in the ISO 8601 format - for example: 2017-04-13T18:34Z. |
Incentive Code Redemption Entity
The following is the JSON representation of an Incentive Code Redemption entity within the APIs.
{
"id": 8,
"external_issuee_id": "user@mycompany.com",
"issuee_id": "0eef8961-7568-485b-9b13-fc7dbd1cf712",
"referring_application": "system",
"referring_application_ref_id": "1234",
"incentive_code": {
"code": "aabb-ccdd",
"url": "/companies/:company_id/incentives/codes/:code"
},
"incentive_pool": {
"id": 1,
"url": "/companies/:company_id/incentives/pools/1"
},
"updated_at": "2017-04-13T18:34Z",
"created_at": "2017-02-13T18:34Z"
}
Elements
| Data Element | Type | Description |
|---|---|---|
id | Integer | Vibes unique identifier for each redemption. |
| external_issuee_id | String | Unique external issuee ID. |
| issuee_id | String | Vibes-generated issuee ID. |
referring_application | String | Application redeeming the code. |
| referring_application_ref_id | String | Application reference ID (campaign ID). |
incentive_code | Object | An object describing this Redemption's Incentive Code. |
| incentive_code.code | String | Incentive Code. |
incentive_code.url | String | Incentive Code's URL. |
incentive_pool | Object | An object describing this Redemption's pool. |
| incentive_pool.id | Integer | The unique identifier for the pool. |
| incentive_pool.url | String | Pool's URL. |
| created_at | Timestamp | The date this Redemption was created. It should be in the ISO 8601 format - for example: 2017-04-13T18:34Z. |
| updated_at | Timestamp | The date this Redemption was last updated. It should be in the ISO 8601 format - for example: 2017-02-13T18:34Z. |
Overview
Content Tools