> ## 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. # Get a list of entitlements for a bangoUserId or sharedCustomerId, matching specific criteria > Get a list of entitlements for a bangoUserId or sharedCustomerId, matching specific criteria ## OpenAPI ````yaml /openapi/legacy/resale/content-provider-to-bango/openapi.yaml post /v1/merchant/entitlement/report openapi: 3.0.0 info: version: 1.1.0 title: Resale Merchant - Server API description: | Changelog * 1.2.0: * Adding optional `sharedCustomerId` to all responses * 1.1.0: * Adding `extraInformation` to `PATCH /v1/entitlement/{merchantEntitlementId}` and response object * Adding `merchantExtensionData` to response object * Adding `merchantBangoExtensionData` to response object * Adding `customerId` and `resellerId` to response object * Adding `POST /v1/merchant/entitlement/report` to retrieve entitlements by `bangoUserId` * 1.0.4: * Adding `financeData` to: * `POST /v1/entitlement/activate/{merchantEntitlementId}` * `PATCH /v1/entitlement/{merchantEntitlementId}` * `POST /v1/entitlement/terminate/{merchantEntitlementId}` * Response object * 1.0.3: * Updating API spec to be OpenAPI3 * Adding the `entitlementBenefits` to `PATCH /v1/entitlement/{merchantEntitlementId}` * 1.0.2: Initial release servers: - description: SwaggerHub API Auto Mocking url: >- https://virtserver.swaggerhub.com/BangoProducts/MerchantInterface_Server_API/1.1.0 security: - basic: [] paths: /v1/merchant/entitlement/report: post: tags: - Entitlement summary: >- Get a list of entitlements for a bangoUserId or sharedCustomerId, matching specific criteria description: > Get a list of entitlements for a bangoUserId or sharedCustomerId, matching specific criteria parameters: - name: X-RequestIdentifier in: header description: >- Request unique identifier. If present, this id will be used for idempotency. schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/EntitlementReport' description: The report filters JSON. required: true responses: '200': description: Retrieval successful content: application/json: schema: $ref: '#/components/schemas/EntitlementReportResponse' '400': description: Invalid API request content: application/json: schema: $ref: '#/components/schemas/ResponseObject' examples: InvalidAPIRequest: value: responseCode: BAD_REQUEST responseMessage: Invalid request. NotSupported: value: responseCode: OPERATION_NOT_SUPPORTED responseMessage: Operation not supported for entitlement route. '401': description: IP address or access credentials are invalid content: application/json: schema: $ref: '#/components/schemas/ResponseObject' examples: Unauthorized: value: responseCode: UNAUTHORIZED responseMessage: >- You have not provided adequate credentials to access this resource. MessageSigningNoKey: value: responseCode: UNAUTHORIZED responseMessage: No valid key found. MessageSigningMissingContent: value: responseCode: UNAUTHORIZED responseMessage: Signature or header content is missing. MessageSigningInvalidSignature: value: responseCode: UNAUTHORIZED responseMessage: Signature is invalid. '429': description: Request limit reached content: application/json: schema: $ref: '#/components/schemas/ResponseObject' examples: TooManyRequests: value: responseCode: TOO_MANY_REQUESTS responseMessage: Request limit reached. Please try again later. '500': description: Unexpected server issue content: application/json: schema: $ref: '#/components/schemas/ResponseObject' examples: InternalError: value: responseCode: INTERNAL_ERROR responseMessage: null '503': description: Bango Platform undergoing maintenance content: application/json: schema: $ref: '#/components/schemas/ResponseObject' examples: ServiceUnavailable: value: responseCode: SERVICE_UNAVAILABLE responseMessage: null components: schemas: EntitlementReport: type: object description: List of filters applied to retrieve a list of existing entitlements required: - resellerId properties: bangoUserId: type: string description: User unique identifier. Include this OR the sharedCustomerId example: '1549053185' sharedCustomerId: type: string description: >- Bango generated id shared between reseller and merchant for this customer (contact support for setup). Include this OR bangoUserId example: 414b3019-0c28-4d14-9c5f-6217b8bd1e3e format: uuid productId: type: string description: Entitlement product unique identifier. For example, "BangoMusic". example: BangoMusic status: type: string enum: - ACTIVE - CANCELLED - REVOKED - SUSPENDED - PENDING - FAILED - ACTIVE-ENDING description: |- Entitlement status. Possible values are: - "ACTIVE": The entitlement has been successfully activated - "CANCELLED": The entitlement has been cancelled. - "REVOKED": The entitlement has been revoked. This usually happens on fraud and user contract termination cases. - "SUSPENDED": The entitlement has been suspended. - "PENDING": The entitlement has been initiated, but the user has not yet finalized the activation process. - "FAILED": The entitlement failed - "ACTIVE-ENDING": The entitlement is ending at the end of the current period. resellerId: type: string description: Unique reseller identifier example: XYZ_RESELLER EntitlementReportResponse: type: object properties: responseCode: type: string example: OK responseMessage: type: string example: Success entitlements: type: array items: type: object properties: merchantEntitlementId: type: string description: Merchants unique identifier representing an entitlement. example: 6673b39e-8302-412d-bbdb-446c96c34871 requestId: type: string description: Bango unique identifier representing an entitlement. example: 981a55a5-b3a4-46dc-9fac-a86227b26344 bangoUserId: type: string description: User unique identifier. 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 productId: type: string description: >- Entitlement product unique identifier. For example, "30_DAYS_MUSIC". example: 30_DAYS_MUSIC 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 resellerId: type: string description: Unique reseller identifier example: XYZ_RESELLER status: type: string enum: - ACTIVE - CANCELLED - REVOKED - SUSPENDED - PENDING - FAILED - ACTIVE-ENDING description: |- Entitlement status. Possible values are: - "ACTIVE": The entitlement has been successfully activated - "CANCELLED": The entitlement has been cancelled. - "REVOKED": The entitlement has been revoked. This usually happens on fraud and user contract termination cases. - "SUSPENDED": The entitlement has been suspended. - "PENDING": The entitlement has been initiated, but the user has not yet finalized the activation process. - "FAILED": The entitlement failed - "ACTIVE-ENDING": The entitlement is ending at the end of the current period. 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 dateCreated: type: string format: date-time description: >- Date and time when the entitlement was created, in UTC ISO 8601 format (yyyy-MM-ddThh:mm:ssZ) dateActivated: type: string format: date-time description: >- Date and time when the entitlement was activated, in UTC ISO 8601 format (yyyy-MM-ddThh:mm:ssZ) dateExpiry: type: string format: date-time description: >- Entitlement expiry date in UTC ISO 8601 format. Null if no expiry (yyyy-MM-ddThh:mm:ssZ) example: null dateEnded: type: string format: date-time description: >- Date and time when the entitlement ended due to termination, in UTC ISO 8601 format (yyyy-MM-ddThh:mm:ssZ) example: null dateSuspended: type: string format: date-time description: >- Date and time when the entitlement was suspended, in UTC ISO 8601. Null if status is not Suspended. format (yyyy-MM-ddThh:mm:ssZ) example: null dateResumed: type: string format: date-time description: >- Date and time when the entitlement was suspended, in UTC ISO 8601. Null if the entitlement hasn't ever been resumed before. Format (yyyy-MM-ddThh:mm:ssZ) example: null dateAutoSuspend: type: string format: date-time description: >- Date and time when the entitlement will be automatically suspended at the request of the reseller, in UTC ISO 8601. Null if date is not set. format (yyyy-MM-ddThh:mm:ssZ) example: null merchantExtensionData: $ref: '#/components/schemas/MerchantExtensionData' extraInformation: $ref: '#/components/schemas/ExtraEntitlementInfo' financeData: $ref: '#/components/schemas/FinanceDataOutput' merchantBangoExtensionData: $ref: '#/components/schemas/MerchantBangoExtensionData' ResponseObject: type: object properties: responseCode: type: string responseMessage: type: string 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: basic: type: http description: Basic authentication scheme: basic ````