> ## 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. # Change a subscription's plan > Use this endpoint to change a subscription's plan immediately or at a later date, given the unique identifier allocated by Bango for the subscription. This endpoint returns the updated subscription record. To identify the plan, specify both the plan name and the merchant account key for the provider of the product or service. Specify the date on which the plan should change by including **either** the `billingPolicy` **or** `requestedDate` parameters. ## OpenAPI ````yaml /openapi/legacy/subscriptions/partner-to-bango/openapi.yaml put /subscription/{subscriptionId} openapi: 3.0.1 info: title: Bango Subscriptions API version: 1.4.0 description: |- Manage user subscriptions to products and services. ### Change log - 1.4.0: - Adding Plan Management API methods - Add `POST /plan` - Add `GET /plan/{planName}` - Add `GET /plan/{planId}` - Add `GET /plans` - Support for additional character types as the first character of `planName`'s - 1.3.0: - Add `productName` update functionality to `PUT /subscription/{subscriptionId}` - 1.2.0: - Move to OpenAPI 3.0.1 and refactor - Synchronize with API behavior - 1.1.0: - Remove `billingPolicy`, `useRequestedDateForBilling` from `DELETE /subscription/{subscriptionId}/cancel` - 1.0.0: - Add `merchantAccountKey` to `POST` and `GET` - 0.0.1: - Initial release contact: name: Bango Support url: https://bango.com email: support@bango.com termsOfService: https://bango.com/privacy servers: - url: https://virtserver.swaggerhub.com/BangoProducts/Subscriptions-API/1.4.0 security: - basicAuth: [] tags: - name: echo description: Service availability - name: subscriptions description: Subscription management - name: plans description: Plan management externalDocs: description: Bango developer documentation url: https://developer.bango.com paths: /subscription/{subscriptionId}: put: tags: - subscriptions summary: Change a subscription's plan description: >- Use this endpoint to change a subscription's plan immediately or at a later date, given the unique identifier allocated by Bango for the subscription. This endpoint returns the updated subscription record. To identify the plan, specify both the plan name and the merchant account key for the provider of the product or service. Specify the date on which the plan should change by including **either** the `billingPolicy` **or** `requestedDate` parameters. operationId: put-subscription-by-id parameters: - $ref: '#/components/parameters/IdempotencyHeader' - $ref: '#/components/parameters/SubscriptionId' requestBody: $ref: '#/components/requestBodies/SubscriptionUpdate' responses: '200': description: Subscription found and updated content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessResponse' - $ref: '#/components/schemas/Subscription' '400': $ref: '#/components/responses/ErrorBadRequest' '401': $ref: '#/components/responses/ErrorUnauthorized' '429': $ref: '#/components/responses/ErrorTooManyRequests' '500': $ref: '#/components/responses/ErrorUnexpected' '503': $ref: '#/components/responses/ErrorUnavailable' components: parameters: IdempotencyHeader: name: X-RequestIdentifier in: header description: >- An arbitrary, optional, globally unique identifier for the request. If present, this ID is used for idempotency. schema: type: string SubscriptionId: name: subscriptionId in: path required: true description: The unique identifier generated by Bango for a subscription. schema: $ref: '#/components/schemas/SubscriptionId' requestBodies: SubscriptionUpdate: description: Data for changing a subscription's plan. required: true content: application/json: schema: type: object properties: merchantAccountKey: $ref: '#/components/schemas/MerchantAccountKey' productName: allOf: - $ref: '#/components/schemas/ProductName' - description: >- When attempting a productName update, a planName must also be specified. The product catalog defines these identifiers planName: $ref: '#/components/schemas/PlanName' billingPolicy: description: >- When the change of plan becomes effective. (Include either this parameter or `requestedDate` - not both.) type: string enum: - START_OF_TERM - END_OF_TERM - IMMEDIATE requestedDate: description: >- When the change of plan becomes effective. (Include either this parameter or `billingPolicy` - not both.) type: string format: date extensionData: $ref: '#/components/schemas/ExtensionData' required: - merchantAccountKey schemas: SuccessResponse: type: object properties: responseCode: description: Always 'OK' type: string enum: - OK responseMessage: type: string example: Success required: - responseCode - responseMessage Subscription: description: A subscription record in the Bango Platform type: object properties: subscriptionId: $ref: '#/components/schemas/SubscriptionId' bangoUserId: $ref: '#/components/schemas/BangoUserId' externalKey: $ref: '#/components/schemas/ExternalKey' entitlementStartDate: description: The YYYY-MM-DD UTC date on which the subscription entitlement starts type: string format: date example: '2020-08-19' merchantAccountKey: $ref: '#/components/schemas/MerchantAccountKey' productName: $ref: '#/components/schemas/ProductName' extensionData: $ref: '#/components/schemas/ExtensionData' billingPeriod: $ref: '#/components/schemas/BillingPeriod' phaseType: $ref: '#/components/schemas/PhaseType' priceList: type: string planName: $ref: '#/components/schemas/PlanName' state: $ref: '#/components/schemas/SubscriptionState' cancelledDate: description: >- If not null, the effective YYYY-MM-DD UTC date of cancellation. Might be a date in the future. If null, the subscription has not been cancelled. type: string format: date nullable: true chargedThroughDate: description: >- The YYYY-MM-DD UTC date up to which the subscription has been paid for. type: string format: date billingStartDate: description: The YYYY-MM-DD UTC date on which billing starts or started. type: string format: date billingEndDate: description: >- If not null, the YYYY-MM-DD UTC date on which billing ends or ended. If null, billing has not ended. type: string format: date nullable: true billCycleDayLocal: type: integer format: int32 example: 1 nextPayment: $ref: '#/components/schemas/Payment' lastPayment: $ref: '#/components/schemas/Payment' events: type: array items: $ref: '#/components/schemas/EventSubscription' priceOverrides: type: array items: $ref: '#/components/schemas/PhasePrice' prices: type: array items: $ref: '#/components/schemas/PhasePrice' auditLogs: type: array items: $ref: '#/components/schemas/AuditLog' SubscriptionId: description: >- The unique identifier generated by Bango for a subscription. This is a globally unique, opaque string type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174000 MerchantAccountKey: description: >- The unique identifier for the merchant supplying the product or service. Bango assigns these identifiers type: string example: BANGO_ENTERTAINMENT ProductName: description: >- The unique identifier for the product or service the user is subscribing to. The product catalog defines these identifiers. The first character of the planName can't be a number. type: string example: bango-music PlanName: description: >- The unique identifier for the plan detailing the prices and offer periods associated with the subscription. Bango use NCName type which means that the planName cannot contain several symbol characters like :, @, $, %, &, /, +, ,, ;, whitespace characters or different parenthesis. type: string example: bango-music-3-months-free ExtensionData: description: >- Arbitrary key-value pairs, where values are always strings. API consumers can use this to store custom data for the subscription. type: object additionalProperties: type: string example: myCustomField: my-custom-value mySecondCustomField: another-value BangoUserId: description: The Bango user identifier. This is a globally unique, opaque string. type: string example: '1234567890' ExternalKey: description: >- An optional unique identifier for the subscription, meaningful to the API consumer. This must be a globally unique, opaque string. Use this identifier as an alternative to the `subscriptionId` assigned by Bango. type: string example: my-external-identifier BillingPeriod: description: |- How frequently the user is billed. For the avoidance of doubt: - BIWEEKLY = every 2 weeks - BIMESTRIAL = every 2 months - BIANNUAL = every 6 months - BIENNIAL = every 2 years type: string enum: - MONTHLY - DAILY - WEEKLY - BIWEEKLY - THIRTY_DAYS - SIXTY_DAYS - NINETY_DAYS - BIMESTRIAL - QUARTERLY - TRIANNUAL - BIANNUAL - ANNUAL - BIENNIAL - NO_BILLING_PERIOD PhaseType: type: string enum: - TRIAL - DISCOUNT - FIXEDTERM - EVERGREEN SubscriptionState: description: >- The current state of a subscription. A subscription starts in `ACTIVE` if it's created with `entitlementStartDate` set to today's date or a past date. It starts in `PENDING` if `entitlementStartDate` is set to a future date, and automatically transitions to `ACTIVE` on that date. A subscription is `CANCELLED` when the user no longer has access to the product or service. (A subscription scheduled to be cancelled at a future date is still `ACTIVE` until that date, and until then it can be uncancelled.) type: string enum: - ACTIVE - PENDING - CANCELLED Payment: description: >- Details of a single payment. For `nextPayment`, this is the next payment scheduled to occur. For `lastPayment`, this is the most recent successful payment. type: object properties: amount: description: Payment amount as a string. type: string example: 9.99 currency: $ref: '#/components/schemas/CurrencyCode' date: description: The YYYY-MM-DD UTC date on which payment was or will be made. type: string format: date EventSubscription: type: object properties: eventId: type: string format: uuid billingPeriod: $ref: '#/components/schemas/BillingPeriod' effectiveDate: type: string format: date planName: $ref: '#/components/schemas/PlanName' productName: $ref: '#/components/schemas/ProductName' priceList: type: string eventType: type: string enum: - START_BILLING - START_ENTITLEMENT - PAUSE_ENTITLEMENT - PAUSE_BILLING - RESUME_ENTITLEMENT - RESUME_BILLING - PHASE - CHANGE - STOP_ENTITLEMENT - STOP_BILLING - SERVICE_STATE_CHANGE isBlockedBilling: type: boolean isBlockedEntitlement: type: boolean serviceName: type: string serviceStateName: type: string phase: type: string auditLogs: type: array items: $ref: '#/components/schemas/AuditLog' PhasePrice: description: Pricing information for a phase. type: object properties: planName: $ref: '#/components/schemas/PlanName' phaseName: type: string example: free-trial phaseType: $ref: '#/components/schemas/PhaseType' fixedPrice: type: number example: 0 recurringPrice: type: number example: 0 AuditLog: type: object properties: changeType: type: string example: UPDATE changeDate: type: string format: date-time objectType: type: string enum: - SUBSCRIPTION - ACCOUNT - ACCOUNT_EMAIL - BLOCKING_STATES - BUNDLE - CUSTOM_FIELD - INVOICE - PAYMENT - TRANSACTION - INVOICE_ITEM - INVOICE_PAYMENT - SUBSCRIPTION_EVENT - SERVICE_BROADCAST - PAYMENT_ATTEMPT - PAYMENT_METHOD - TAG - TAG_DEFINITION - TENANT - TENANT_KVS objectId: type: string format: uuid changedBy: type: string example: admin reasonCode: type: string example: null comments: type: string example: null userToken: type: string format: uuid history: $ref: '#/components/schemas/Entity' CurrencyCode: description: A three-character ISO 4217 currency code. type: string enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BRL - BSD - BTC - BTN - BWP - BYR - BZD - CAD - CDF - CHF - CLP - CNY - COP - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GGP - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - IMP - INR - IQD - IRR - ISK - JEP - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MUR - MVR - MWK - MXN - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SPL - SRD - STD - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TVD - TWD - TZS - UAH - UGX - USD - UYU - UZS - VEF - VND - VUV - WST - XAF - XCD - XDR - XOF - XPF - YER - ZAR - ZMW - ZWD example: USD Entity: type: object properties: id: type: string format: uuid updatedDate: type: string format: date-time createdDate: type: string format: date-time responses: ErrorBadRequest: description: Bad request content: application/json: schema: type: object properties: responseCode: description: Always 'BAD_REQUEST' type: string enum: - BAD_REQUEST responseMessage: type: string example: Invalid request required: - responseCode - responseMessage ErrorUnauthorized: description: User is not authorized to access the endpoint content: application/json: schema: type: object properties: responseCode: description: Always 'UNAUTHORIZED' type: string enum: - UNAUTHORIZED responseMessage: type: string example: Invalid access credential required: - responseCode - responseMessage ErrorTooManyRequests: description: Too many requests content: application/json: schema: type: object properties: responseCode: description: Always 'TOO_MANY_REQUESTS' type: string enum: - TOO_MANY_REQUESTS responseMessage: type: string example: Request limit reached. Please try again later required: - responseCode - responseMessage ErrorUnexpected: description: Unexpected error content: application/json: schema: type: object properties: responseCode: description: Always 'INTERNAL_ERROR' type: string enum: - INTERNAL_ERROR responseMessage: type: string example: >- The server encountered an unexpected condition which prevented it from fulfilling the request required: - responseCode - responseMessage ErrorUnavailable: description: Service unavailable content: application/json: schema: type: object properties: responseCode: description: Always 'SERVICE_UNAVAILABLE' type: string enum: - SERVICE_UNAVAILABLE responseMessage: type: string example: >- The server is undergoing maintenance and is not available. Please, try again later required: - responseCode - responseMessage securitySchemes: basicAuth: type: http scheme: basic description: Base64 encoding of username:password as supplied by Bango Support ````