> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bango.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Entitlement

> Schema and fields for the Entitlement resource

An Entitlement represents a consumer's access to a Product or service from a Content Provider. It has an identifier, status, optional activation details, timeline, and source information.

## Attributes

### entitlementId

Unique identifier for this entitlement (UUID).

### merchantAccountKey

Merchant's account key (route identifier for the content provider).

### productKey

Reseller's product key.

### status

The status of the entitlement.

| Value | Description |
| - | - |
| `REQUESTED` | Entitlement creation has been requested. |
| `CREATED` | Entitlement has been created but may not yet be active. |
| `ACTIVE` | Entitlement is active and the consumer has access. |
| `CREATE_FAILED` | Entitlement creation failed. |
| `ENDED` | Entitlement has ended. |
| `SUSPENDED` | Entitlement is temporarily suspended. |

### subStatus

The sub-status of the entitlement.

| Value | Description |
| - | - |
| `PENDING_CREATE` | Creation is in progress. |
| `PENDING_ACTIVATE` | Awaiting activation by the consumer or content provider. |
| `ENDING` | Termination is in progress. |
| `IMMEDIATE` | Applied when an immediate action (e.g. immediate termination) is in effect. |

### sharedCustomerId

Auto-generated unique consumer id for this content provider (UUID).

### activation

Optional activation details. Contains:

* **activationCode** — Merchant's activation code
* **activationUrl** — Merchant's activation URL
* **activationUrlExpiryTs** — Expiry time of the activation URL (ISO 8601 date-time)

### timeline

Timeline of entitlement events. Contains (each ISO 8601 date-time when present):

* **createRequestedTs** — When entitlement creation was requested
* **createdTs** — When the entitlement was created
* **createFailedTs** — When creation failed (if applicable)
* **activatedTs** — When the entitlement was activated (if applicable)
* **terminatedTs** — When the entitlement was terminated (if applicable)

### source

Source of the consumer or offer. Contains:

* **channelType** — Channel used to acquire the offer (see table below)
* **bundleId** — Reseller's bundle identifier
* **brand** — Reseller's brand
* **country** — Consumer's country
* **region** — Consumer's region or area code

Possible values for **channelType**:

| Value | Description |
| - | - |
| `Retail` | Consumer acquired the offer via a retail channel. |
| `SMS` | Consumer acquired the offer via SMS. |
| `App` | Consumer acquired the offer via an app. |
| `Website` | Consumer acquired the offer via a website. |
| `Email` | Consumer acquired the offer via email. |
| `Call Centre` | Consumer acquired the offer via a call centre. |
| `Mobile` | Consumer acquired the offer via a mobile channel. |
| `Set Top Box` | Consumer acquired the offer via a set-top box. |
| `Other` | Consumer acquired the offer via another or unspecified channel. |

<ResponseExample>
  ```json Entitlement theme={null}
  {
    "entitlementId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "merchantAccountKey": "BANGO_MEDIA",
    "productKey": "PREMIUM_1_MONTH_FREE",
    "status": "ACTIVE",
    "subStatus": "PENDING_ACTIVATE",
    "sharedCustomerId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "activation": {
      "activationCode": "ACTIVATION-CODE-123",
      "activationUrl": "https://example.com/activate/ACTIVATION-CODE-123",
      "activationUrlExpiryTs": "2024-07-22T10:00:00.000Z"
    },
    "timeline": {
      "createRequestedTs": "2024-06-22T10:00:06.000Z",
      "createdTs": "2024-06-22T10:00:07.000Z",
      "activatedTs": "2024-06-22T10:05:00.000Z"
    },
    "source": {
      "channelType": "App",
      "bundleId": "bundle-456",
      "brand": "Example Brand",
      "country": "GB",
      "region": "UK"
    }
  }
  ```
</ResponseExample>