Introduction
Member context
Member ID OAuth (recommended)
/me/ URL segment and requires token provided with authorization header.Member ID
/:member_id/ URL segment and requires no authentication.should not be used on front-end implementations, where API token is exposed to an end user.
Guest access
/guest/ URL segment instead of /me/ or /member_id/ and may be used by bothaforementioned approaches.
Scoping
be specified by query param. To access offers within a specific scope, user should have the corresponding permit.
| Scope | Description | Requred permit |
|---|---|---|
| standard | For general use (default) | Offers:Api:Scopes:Standard |
| informational | For non-usable offers | Offers:Api:Scopes:Informational |
| parking | For parking-related benefits | Offers:Api:Scopes:Parking |
| carbon_offset | For carbon offset member check-ins | Offers:Api:Scopes:CarbonOffset |
| reward | For rewards | Offers:Api:Scopes:Reward |
Offer model
Example
{
"id": 1000115,
"name": "Buy two shoes, get one jacket",
"description": null,
"type": "REGULAR",
"external_url": "https://example.com/foo",
"usable_since": "2019-03-13T17:32:00.000Z",
"usable_until": null,
"usage_authorization_token_required": false,
"collection_ids": [1000016, 1000017],
"stores": ["M&H"],
"images": [
{
"url": "https://offers-api.s3.eu-central-1.amazonaws.com/offer-1000115-offer_default-original.jpg",
}
],
"display": {
"read_more": { "button_title": "Button title", "url": null, "title": "Title", "text": "Text" },
"activation_texts": { "modal": "Modal", "button": "Button", "description": null }
},
"liked": false,
"usage": {
"usable": true,
"max_uses": 10,
"uses_left": 3,
"active_until": "2019-03-13T18:41:00.000Z",
"period": null
},
"extras": {
"category": 42
}
}Definition
| Key | Type | Optional? | Description |
|---|---|---|---|
| id | integer | no | |
| name | string | yes | |
| type | enum | no | See: Offer types (uppercase) |
| description | string | yes | |
| external_url | string | yes | The URL the offer may be linked with |
| usable_since | Date | yes | Time since the offer may be used. If null, there is no restriction. |
| usable_until | Date | yes | Time until the offer may be used. If null, there is no restriction. |
| usage_authorization_token_required | Boolean | no | When required, a special authorization code is required for using the offer |
| collection_ids | integer[] | no (may be empty) | List of collections ids the offer belongs to |
| stores | string[] | no (may be empty) | List of shop names associated with the offer |
| images | Object[] | no (may be empty) | A list of offer images (must be uploaded to Files API as offer_image type) |
| images[].url | String | no | |
| liked | Boolean | no | Has offer been liked by user? |
| usage | Usage | no | Usage information object - see Offer usage model |
| extras | Object | no (may be empty) | Extendable container for any potential extra data |
| display | Object | no | Stores display information |
| display.read_more | Object | yes | |
| display.read_more.button_title | string | yes | |
| display.read_more.url | string | yes | |
| display.read_more.title | string | yes | |
| display.read_more.text | string | yes | |
| display.read_more | Object | yes | |
| display.activation_texts.modal | string | yes | |
| display.activation_texts.button | string | yes | |
| display.activation_texts.description | string | yes |
Offer usage model
| Key | Type | Optional? | Description |
|---|---|---|---|
| usable | Boolean | no | Is the offer usable? |
| max_uses | integer | yes | Maximum number of times the specific member can use the offer. When null, there's no limit. |
| uses_left | integer | yes | How many more times the specific member can use the offer - this number can be also affected by global offer limit. When null, there's no limit. |
| active_until | Date | yes | The last time time the offer has been used at+ activation time (configurable per Loyalty Club, e.x. 30s). When null, the offer has not been activated (used) yet |
| period | Object | yes | If present, it describes limtations of using the offer by member within specific period |
| period.timespan | enum: ['MINUTE', 'HOUR', 'DAY', 'WEEK', 'MONTH', 'YEAR'] | no | Defines the period in which usage is limited |
| period.max_uses | integer | no | Defines how many times the offer may be used by member within period |
| period.uses_left | integer | yes | Defines how many times member may use the offer until end of current period |
Collection model
| Key | Type | Optional? | Description |
|---|---|---|---|
| id | integer | no | |
| title | string | yes | |
| description | string | yes | |
| offers_order | integer[] | no (may be empty) | Describes order in which offers should be displayed inside this collection |
| files | File[] | no | A list of Offer Files - see File model |