> ## 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. # Create Entitlement > Request that is sent to the merchant to create a new Entitlement and return Activation URL and related parameters to be sent to the user. Expected responses as defined below. ## OpenAPI ````yaml /openapi/legacy/resale/bango-to-content-provider/openapi.yaml post /v1/entitlement openapi: 3.0.0 info: version: 1.1.0 title: Resale Merchant - Client API description: > **Changelog** * 1.2.0: * Adding optional `sharedCustomerId` to all Bango-initiated outbound requests * 1.1.0: * Removing `extensionData` from `POST /v1/entitlement` * Removing `POST /v1/entitlement/suspend/{merchantEntitlementId}` and `POST /v1/entitlement/resume/{merchantEntitlementId}` * Removing `merchantExtensionData` from response object * Adding `bangoUserId`, `productId`, `offerId`, `customerId`, `merchantExtensionData` and `extraInformation` to `POST /v1/entitlement/terminate/{merchantEntitlementId}` * Adding `merchantExtensionData` to request object: * `POST /v1/entitlement` * `PATCH /v1/entitlement` * `POST /v1/entitlement/terminate/{merchantEntitlementId}` * `POST /v1/entitlement/checkeligibility` * Adding `financeData` to request object: * `POST /v1/entitlement` * `PATCH /v1/entitlement` * `POST /v1/entitlement/terminate/{merchantEntitlementId}` * Adding `status` to request object: * `POST /v1/entitlement` * `PATCH /v1/entitlement` * `POST /v1/entitlement/terminate/{merchantEntitlementId}` * Adding `merchantBangoExtensionData` to request object * 1.0.8: * Adding `409 CONFLIFT` to * `POST /v1/entitlement/terminate/{merchantEntitlementId}` * 1.0.7: * Adding `entitlementBenefits` to `PATCH /v1/entitlement` * Adding `extraInformation` to `PATCH /v1/entitlement` * 1.0.6: * Adding customerId to the `POST /v1/entitlement` and `PATCH /v1/entitlement` * 1.0.5: * Updating API spec to be OpenAPI3 * Adding resellerId to `PATCH /v1/entitlement` and `POST /v1/entitlement/terminate/{merchantEntitlementId}` * 1.0.4: * Adding `extensionData` to `PATCH /v1/entitlement` * Adding `offerId` and `customerIdentifier` to `POST /v1/entitlement/checkeligibility` * Adding the support for a `201 created` response for `POST /v1/entitlement` * 1.0.3: Initial release **Available authorization options** * Basic Auth - Bango uses Basic; base64-encoded credentials * OAuth2 - Bango uses https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/ * AWSToken - apiKey See security definition secton for more information contact: name: Bango Support url: https://bango.com email: support@bango.com termsOfService: https://bango.com/privacy servers: - url: >- https://virtserver.swaggerhub.com/BangoProducts/MerchantInterface_Client_API/1.1.0 security: - BasicAuth: [] paths: /v1/entitlement: post: tags: - Entitlement summary: Create Entitlement description: >- Request that is sent to the merchant to create a new Entitlement and return Activation URL and related parameters to be sent to the user. Expected responses as defined below. operationId: create parameters: - name: X-RequestIdentifier in: header description: Request unique identifier. This id should be used for idempotency. schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/EntitlementCreate' description: The entitlement JSON sent to merchant to create a subscription required: true responses: '200': description: Entitlement created and activated successfully. content: application/json: schema: $ref: '#/components/schemas/EntitlementCreate200Response' '201': description: Entitlement created. content: application/json: schema: $ref: '#/components/schemas/EntitlementCreate201Response' '202': description: An action is required to be performed by the client content: application/json: schema: $ref: '#/components/schemas/EntitlementCreate202Response' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequest' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Unauthorized' '409': description: Already exists content: application/json: schema: $ref: '#/components/schemas/AlreadyExists' '429': description: Too many requests content: application/json: schema: $ref: '#/components/schemas/TooManyRequests' '500': description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/InteralServerError' '503': description: Service unavailable content: application/json: schema: $ref: '#/components/schemas/ServiceUnavailable' components: schemas: EntitlementCreate: type: object required: - requestId - bangoUserId - resellerId - productId properties: requestId: type: string description: Unique identifier representing a specific entitlement. example: a25100b8-4e0c-4e37-b921-cac9cb1e930f bangoUserId: type: string description: >- Unique identifier representing a specific customer of the reseller as a Bango anonymised value. example: '1549053185' sharedCustomerId: type: string description: >- Bango generated id shared between reseller and merchant for this customer (contact support for setup) example: 414b3019-0c28-4d14-9c5f-6217b8bd1e3e format: uuid resellerId: type: string description: Unique reseller identifier as agreed with the merchant example: XYZ_RESELLER productId: type: string description: Entitlement product unique identifier. For example, "BangoMusic". example: BangoMusic offerId: type: string description: >- The offer given to the user for the merchant service. For example, "FREE_FOR_6_MONTHS". example: FREE_FOR_6_MONTHS customerId: type: string description: >- Unique identifier representing a specific customer of the reseller not anonymised. This value will only be sent by Bango if the Merchant and Reseller both approve the sharing of this data status: type: string example: PENDING enum: - ACTIVE - SUSPENDED - PENDING - ACTIVE-ENDING description: |- Entitlement status. Possible values are: - "ACTIVE": The entitlement has been successfully activated - "SUSPENDED": The entitlement has been suspended. - "PENDING": The entitlement has been initiated, but the user has not yet finalized the activation process. - "ACTIVE-ENDING": The entitlement is ending at the end of the current period. merchantExtensionData: $ref: '#/components/schemas/MerchantExtensionData' extraInformation: $ref: '#/components/schemas/ExtraEntitlementInfo' financeData: $ref: '#/components/schemas/FinanceDataOutput' merchantBangoExtensionData: $ref: '#/components/schemas/MerchantBangoExtensionData' EntitlementCreate200Response: type: object required: - merchantEntitlementId properties: merchantEntitlementId: type: string description: >- Unique identifier representing the entitlement as identified by the merchant. Value must be URL friendly. example: a25100b8-4e0c-4e37-b921-cac9cb1e930f EntitlementCreate201Response: type: object required: - merchantEntitlementId properties: merchantEntitlementId: type: string description: >- Unique identifier representing the entitlement as identified by the merchant. Value must be URL friendly. example: a25100b8-4e0c-4e37-b921-cac9cb1e930f EntitlementCreate202Response: type: object required: - merchantEntitlementId - activationUrl - expiry properties: merchantEntitlementId: type: string description: >- Unique identifier representing the entitlement as identified by the merchant. Value must be URL friendly. example: a25100b8-4e0c-4e37-b921-cac9cb1e930f activationUrl: type: string description: URL which the user can follow through to activate the entitlement. example: https://merchant-website.com/new-entitlement/activation-url expiryTime: type: string format: date-time description: The expiry date for when the URL will no longer be active example: '2020-01-28T14:15:03Z' BadRequest: type: object properties: responseCode: type: string example: BAD_REQUEST responseMessage: type: string example: Invalid request. Unauthorized: type: object properties: responseCode: type: string example: UNAUTHORIZED responseMessage: type: string example: Invalid access credentials. AlreadyExists: type: object properties: responseCode: type: string example: ALREADY_EXISTS responseMessage: type: string example: Entitlement already exists. TooManyRequests: type: object properties: responseCode: type: string example: TOO_MANY_REQUESTS responseMessage: type: string example: Request limit reached. Please try again later. InteralServerError: type: object properties: responseCode: type: string example: INTERNAL_ERROR responseMessage: type: string example: >- The server encountered an unexpected condition which prevented it from fulfilling the request. ServiceUnavailable: type: object properties: responseCode: type: string example: SERVICE_UNAVAILABLE responseMessage: type: string example: >- The server is undergoing maintenance and is not available. Please, try again later. MerchantExtensionData: type: object additionalProperties: type: string description: Accepts a dynamic list of key-value pairs to cover custom data needs example: merchantCustomData1: merchantCustomDataValue1 merchantCustomData2: merchantCustomDataValue2 merchantCustomData3: merchantCustomDataValue3 ExtraEntitlementInfo: type: object properties: clientDevice: $ref: '#/components/schemas/ClientDevice' communicationInformation: $ref: '#/components/schemas/CommunicationInformation' source: $ref: '#/components/schemas/Source' FinanceDataOutput: type: object required: - source - type - timestamp properties: source: type: string description: the party who added the finance event enum: - Merchant - Reseller type: type: string description: the type of finance event enum: - order - return - renew timestamp: type: string format: date-time description: UTC ISO 8601 retailCurrency: type: string description: ISO 3 retailPrice: type: number format: double description: as per standard price element, including tax retailPriceTax: type: number format: double description: as per standard price element, tax included in the retailPrice offerPrice: type: number format: double description: as per standard price element, including tax offerPriceTax: type: number format: double description: as per standard price element, tax included in the offerPrice notes: type: string description: 255 length limit MerchantBangoExtensionData: type: object additionalProperties: type: string description: >- Contains a defined list of key-value pairs to cover static custom data needs example: merchantCustomData1: merchantBangoCustomDataValue1 merchantCustomData2: merchantBangoCustomDataValue2 merchantCustomData3: merchantBangoCustomDataValue3 ClientDevice: type: object additionalProperties: type: string description: >- When the clientDevice object is present the type is a mandatory key. The clientDevice object will only be returned if data has been provided. - "type": the type of the device. For example, "STB", "MOBILE", "DESKTOP", "TABLET" - "id": the unique identifier for the users device - "typeId": the common identifier for the type of device - "modelName": the device model name - "modelNumber": the device model number - "serialNumber": the serial number of the device - "osType": the OS type of the device - "osVersion": the OS version of the device - "macAddress": the mac address of the device - "browser": the browser being used example: type: STB id: bc449c9e-406f-4399-a3ff-8671a27ac410 typeId: P49AJFND8NFN23NANGAJG modelName: STB Model X7 modelNumber: IAH45IAOF/5 serialNumber: JHFJHA43JNFA9393GFD osType: Linux osVersion: 10.3.8 macAddress: 4A-0F-99-F2-D3-DD browser: Firefox CommunicationInformation: type: object additionalProperties: type: string description: |- Accepts the defined key-value pairs. - "emailAddress": the end-users email address. - "msisdn": the end-users mobile number in international format. example: emailAddress: 123@abc.co.uk msisdn: '441234567890' Source: type: object additionalProperties: type: string description: |- Accepts the defined key-value pairs. - "channelType": the source channel of the entitlement request. - "campaignRef": the campaign reference that the user clicked on. - "referrer": where the user request originated from. - "bundleId": a string identifier for the bundle which the OTT service is part of. - "country": the end-users country. - "region": the end-users region within their country. - "brand": the brand of which the user originated from. - "serviceFlow": the service flow for which the request originated. Valid values are Creation or Activation. If not passed Bango will treat this as Activation. example: channelType: WEB_PROMOTION campaignRef: SUMMER_PROMO referrer: SEARCH_ENGINE bundleId: BundleABC123 country: United Kingdom region: East Anglia brand: BrandABC serviceFlow: Creation securitySchemes: BasicAuth: type: http scheme: basic ````