> ## 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. # Update an existing entitlement > Update an entitlement. This operation cannot be performed on entitlements that are in SUSPENDED status. ## OpenAPI ````yaml /openapi/legacy/resale/reseller-to-bango/openapi.yaml patch /v1/entitlement openapi: 3.0.0 info: title: Bango Reseller API description: > Changelog * 1.0.24: * Adding /notify endpoint for async notification actioned confirmation * 1.0.23: * Adding optional sharedCustomerId to all responses * 1.0.22: * Adding `409 CONFLICT` to * `POST /v1/entitlement/cancel/{entitlementId}` * `POST /v1/entitlement/revoke/{entitlementId}` * 1.0.21: * Adding financeData support to all responses * Adding `ACTIVE-ENDING` as a new `status` * 1.0.20: * Adding dateAutoSuspend functionality to create and patch entitlement methods * Adding dateAutoSuspend parameter to response objects when parameter has a value set * 1.0.19: * Adding the entitlementBenefits functionality to the patch entitlement method * 1.0.18: * Adding ExternalEntitlementId to the create and patch request * Adding ExternalEntitlementId to the responses * Adding the new GET call in v1/entitlement to retrieve Entitlement information using ExternalEntitlementId * 1.0.17: * Updating API spec to be OpenAPI3 * 1.0.16: * Adding the support for a 201 created response for Create Entitlement * Adding serviceFlow parameter to extraInformation source object * 1.0.15 * Removing support for ACTIVATION_ status' * Extended extraInformation to include communicationInformation and source objects * 1.0.14: Added a new optional object called extraInformation which contains an object called clientDevice * 1.0.13: Added ResumedDate into the EntitlementObject. Date is set when using the ResumeEntitlement method * 1.0.12: Added SuspendEntitlement and ResumeEntitlement methods * 1.0.11: Added EntitlementReport * 1.0.6: Initial release version: 1.0.24 servers: - description: SwaggerHub API Auto Mocking url: https://virtserver.swaggerhub.com/BangoProducts/Reseller-API/1.0.23 security: - basic: [] externalDocs: description: Bango developer documentation url: https://developer.bango.com paths: /v1/entitlement: patch: tags: - Update entitlement summary: Update an existing entitlement description: >- Update an entitlement. This operation cannot be performed on entitlements that are in SUSPENDED status. operationId: update 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/EntitlementUpdate' examples: ProductUpdate: value: entitlementId: a212856a-4fd5-490b-a79c-f6dc950c2497 productKey: BangoMusic2 NotificationUrlUpdate: value: entitlementId: a212856a-4fd5-490b-a79c-f6dc950c2497 notificationUrl: >- https://www.example2.com/notification/a25100b8-4e0c-4e37-b921-cac9cb1e930f CustomerIdentifierUpdate: value: entitlementId: a212856a-4fd5-490b-a79c-f6dc950c2497 customerIdentifier: '4407987654321' ExternalEntitlementIdUpdate: value: entitlementId: a212856a-4fd5-490b-a79c-f6dc950c2497 externalEntitlementId: c843678f-d45a-49f4-868d-2bbc445b2c2e Suspend: value: entitlementId: a212856a-4fd5-490b-a79c-f6dc950c2497 entitlementBenefits: SUSPENDED Resume: value: entitlementId: a212856a-4fd5-490b-a79c-f6dc950c2497 entitlementBenefits: NORMAL ProductUpdateAndResume: value: entitlementId: a212856a-4fd5-490b-a79c-f6dc950c2497 entitlementBenefits: NORMAL productKey: BangoMusic2 description: The entitlement JSON you want to update required: true responses: '200': description: Entitlement updated successfully. content: application/json: schema: $ref: '#/components/schemas/EntitlementResponse' examples: OK: value: entitlementId: a25100b8-4e0c-4e37-b921-cac9cb1e930f customerIdentifier: '4407123456789' sharedCustomerId: 414b3019-0c28-4d14-9c5f-6217b8bd1e3e productKey: BangoMusic entitlementDisplayName: 30 days Bango music offerKey: null merchantAccountKey: BANGO activationCode: null dateCreated: '2020-06-22T17:35:38.92Z' dateActivated: '2020-06-22T17:36:01Z' dateEnded: '0001-01-01T00:00:00Z' dateExpiry: '0001-01-01T00:00:00Z' dateAutoSuspend: null dateFailed: '0001-01-01T00:00:00Z' dateSuspended: null dateResumed: null responseCode: OK responseMessage: Success status: ACTIVE externalEntitlementId: 124130d2-2cbc-45a1-ab9b-dfa8b67a2e63 extensionData: additionalProp1: string additionalProp2: string additionalProp3: string parameters: null extraInformation: clientDevice: 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: emailAddress: 123@abc.co.uk msisdn: 441234567890 source: channelType: WEB_PROMOTION campaignRef: SUMMER_PROMO referrer: SEARCH_ENGINE bundleId: BundleABC123 country: United Kingdom region: East Anglia brand: BrandABC serviceFlow: Activation financeData: source: Merchant type: order timestamp: '2021-10-18T11:09:44Z' '202': description: An action is required to be performed by the client content: application/json: schema: $ref: '#/components/schemas/EntitlementResponse' examples: Accepted: value: entitlementId: a25100b8-4e0c-4e37-b921-cac9cb1e930f customerIdentifier: '4407123456789' sharedCustomerId: 414b3019-0c28-4d14-9c5f-6217b8bd1e3e productKey: BangoMusic entitlementDisplayName: 30 days Bango music offerKey: null merchantAccountKey: BANGO activationCode: null dateCreated: '2020-06-22T17:35:38.92Z' dateActivated: '2020-06-22T17:36:01Z' dateEnded: '0001-01-01T00:00:00Z' dateExpiry: '0001-01-01T00:00:00Z' dateAutoSuspend: null dateFailed: '0001-01-01T00:00:00Z' dateSuspended: null dateResumed: null responseCode: ACCEPTED responseMessage: Update request accepted by merchant. status: ACTIVE externalEntitlementId: 124130d2-2cbc-45a1-ab9b-dfa8b67a2e63 extensionData: additionalProp1: string additionalProp2: string additionalProp3: string parameters: Action: NAVIGATE_TO_URL Url: >- https://example.com/?entitlementId=a25100b8-4e0c-4e37-b921-cac9cb1e930f extraInformation: clientDevice: 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: emailAddress: 123@abc.co.uk msisdn: 441234567890 source: channelType: WEB_PROMOTION campaignRef: SUMMER_PROMO referrer: SEARCH_ENGINE bundleId: BundleABC123 country: United Kingdom region: East Anglia brand: BrandABC serviceFlow: Activation financeData: source: Merchant type: order timestamp: '2021-10-18T11:09:44Z' ClientActionRequired: value: entitlementId: a25100b8-4e0c-4e37-b921-cac9cb1e930f customerIdentifier: '4407123456789' sharedCustomerId: 414b3019-0c28-4d14-9c5f-6217b8bd1e3e productKey: BangoMusic entitlementDisplayName: 30 days Bango music offerKey: null merchantAccountKey: BANGO activationCode: null dateCreated: '2020-06-22T17:35:38.92Z' dateActivated: '2020-06-22T17:36:01Z' dateEnded: '0001-01-01T00:00:00Z' dateExpiry: '0001-01-01T00:00:00Z' dateAutoSuspend: null dateFailed: '0001-01-01T00:00:00Z' dateSuspended: null dateResumed: null responseCode: CLIENT_ACTION_REQUIRED responseMessage: An action is required to be performed by the client. status: ACTIVE externalEntitlementId: 124130d2-2cbc-45a1-ab9b-dfa8b67a2e63 extensionData: additionalProp1: string additionalProp2: string additionalProp3: string parameters: Action: NAVIGATE_TO_URL Url: >- https://example.com/?entitlementId=a25100b8-4e0c-4e37-b921-cac9cb1e930f extraInformation: clientDevice: 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: emailAddress: 123@abc.co.uk msisdn: 441234567890 source: channelType: WEB_PROMOTION campaignRef: SUMMER_PROMO referrer: SEARCH_ENGINE bundleId: BundleABC123 country: United Kingdom region: East Anglia brand: BrandABC serviceFlow: Activation financeData: source: Merchant type: order timestamp: '2021-10-18T11:09:44Z' '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. '403': description: Unable to create entitlement for the service content: application/json: schema: $ref: '#/components/schemas/ResponseObject' examples: NotAvailable: value: responseCode: NOT_AVAILABLE responseMessage: No active entitlement routes found. '404': description: Entitlement not found content: application/json: schema: $ref: '#/components/schemas/ResponseObject' examples: NotFound: value: responseCode: NOT_FOUND responseMessage: Entitlement Not Found '409': description: Entitlement not in the correct state content: application/json: schema: $ref: '#/components/schemas/ResponseObject' examples: InvalidState: value: responseCode: INVALID_STATE responseMessage: >- Operation invalid for the current state of the entitlement. '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: EntitlementUpdate: type: object required: - entitlementId properties: entitlementId: type: string description: Unique identifier representing a specific entitlement. example: a25100b8-4e0c-4e37-b921-cac9cb1e930f activationCode: type: string description: Code or token use for the entitlement activation (optional). example: null customerIdentifier: type: string description: User unique identifier. example: '4407123456789' productKey: type: string description: Entitlement product unique identifier. For example, "30_DAYS_MUSIC". example: 30_DAYS_MUSIC entitlementDisplayName: type: string description: >- Entitlement display name. For example, "30 days Bango music" (optional). example: 30 days of Bango music offerKey: type: string description: Entitlement offer. For example, "BUNDLE" (optional). example: BUNDLE dateExpiry: type: string format: date description: >- Entitlement expiry date in UTC ISO 8601 format. Null if no expiry (yyyy-MM-ddThh:mm:ssZ) example: null dateAutoSuspend: type: string format: date description: >- Entitlement auto-suspension date in UTC ISO 8601 format. Null if no auto-suspension (yyyy-MM-ddThh:mm:ssZ) example: null notificationUrl: type: string format: url description: >- The endpoint where all POST notifications will be sent after subscription creation. The body of the POST request will contain the entitlement information in EntitlementGetResponse format. example: >- https://www.example.com/notification/a25100b8-4e0c-4e37-b921-cac9cb1e930f externalEntitlementId: type: string description: External identifier for the Entitlement from the Reseller. example: 124130d2-2cbc-45a1-ab9b-dfa8b67a2e63 entitlementBenefits: type: string description: >- ENUM parameter for the Reseller to instruct the type of benefits action needed as part of the update request. This enum is used to suspend and resume entitlements using the update method. • You must use `SUSPENDED` when you want to suspend the end-users access to the merchants product/service. The entitlement must be `ACTIVE` to successfully carry out this changed. • You must use `NORMAL` when you want to resume the end-users access to the merchants product/service. The entitlement must be `SUSPENDED` to successfully carry out this changed. enum: - SUSPENDED - NORMAL extensionData: type: object additionalProperties: type: string description: >- Accepts a dynamic list of key-value pairs to cover custom data needs (optional). example: additionalCustomData1: additionalCustomDataValue1 additionalCustomData2: additionalCustomDataValue2 additionalCustomData3: additionalCustomDataValue3 extraInformation: $ref: '#/components/schemas/ExtraEntitlementInfo' EntitlementResponse: type: object required: - entitlementId - customerIdentifier - productKey - offerKey - merchantAccountKey - dateCreated - dateActivated - dateEnded - dateExpiry - responseCode - responseMessage - status properties: entitlementId: type: string description: Unique identifier representing a specific entitlement. example: a25100b8-4e0c-4e37-b921-cac9cb1e930f customerIdentifier: type: string description: User unique identifier. example: '4407123456789' sharedCustomerId: type: string format: uuid description: >- Bango generated id shared between reseller and merchant for this customer (contact support for setup) example: 414b3019-0c28-4d14-9c5f-6217b8bd1e3e productKey: type: string description: Entitlement product unique identifier. For example, "BangoMusic". example: BangoMusic entitlementDisplayName: type: string description: Entitlement display name. For example, "30 days Bango music". example: 30 days Bango music offerKey: type: string description: Entitlement offer. For example, "BUNDLE". example: null merchantAccountKey: type: string description: Merchant unique identifier. For example, "BANGO". example: BANGO activationCode: type: string description: Code or token use for the entitlement activation. example: null 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) dateEnded: type: string format: date-time description: >- Date and time when the entitlement ended due to cancellation or revoke, in UTC ISO 8601 format (yyyy-MM-ddThh:mm:ssZ) example: '0001-01-01T00:00:00Z' 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: '0001-01-01T00:00:00Z' dateAutoSuspend: type: string format: date description: >- Entitlement auto-suspension date in UTC ISO 8601 format. Null if no auto-suspension (yyyy-MM-ddThh:mm:ssZ) example: null dateFailed: type: string format: date-time description: >- Date and time when the entitlement failed, in UTC ISO 8601 format (yyyy-MM-ddThh:mm:ssZ) example: '0001-01-01T00:00:00Z' dateSuspended: type: string format: date-time description: >- Date and time when the entitlement was suspended, in UTC ISO 8601. format (yyyy-MM-ddThh:mm:ssZ) example: null dateResumed: type: string format: date-time description: >- Date and time when the entitlement was resumed, in UTC ISO 8601. format (yyyy-MM-ddThh:mm:ssZ) example: null responseCode: type: string example: OK responseMessage: type: string example: Success status: type: string example: ACTIVE 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. externalEntitlementId: type: string description: External identifier for the Entitlement from the Reseller. example: 124130d2-2cbc-45a1-ab9b-dfa8b67a2e63 extensionData: type: object description: Accepts a dynamic list of key-value pairs to cover custom data needs additionalProperties: type: string parameters: type: object properties: Action: type: string description: The action the reseller should take next enum: - NAVIGATE_TO_URL Url: type: string description: >- The url that the reseller must redirect the user to when the `Action` of `NAVIGATE_TO_URL` is provided extraInformation: $ref: '#/components/schemas/ExtraEntitlementInfo' financeData: $ref: '#/components/schemas/FinanceDataOutput' ResponseObject: type: object properties: responseCode: type: string responseMessage: type: string 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 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 ````