# Introduction

This section describes endpoints destined for end user (e.g. for mobile apps) that work only within context of (signed in) member.

Navigate to [Offers Admin](doc-341695) section to see docs for offers management endpoints.

## Scoping

A scoping is introduced in order to divide offers into multiple independent namespaces in the API.

Scope defines on which types (See: [Offer types](doc-341695#offers-types)) of offers the API operates on and can
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

```json
{
  "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](doc-341695#offers-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](api-3511011)
| 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](doc-341649#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](doc-341697#file-model)