> ## 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 top ups > Only resellers are permitted to create top ups. You must include the idempotency header **X-RequestIdentifier** to ensure you do not accidentally add a top up multiple times to an entitlement in the event of an unexpected response (e.g. a timeout). You can also use the Get endpoint to check what top ups have been created for the entitlement. New top ups are automatically stacked to extend the duration of the entitlement. A suspended entitlement will be re-activated automatically. The 201 (created) response returns all dates associated to the top ups requested, as well as information on when the entitlement will now end, and what action will be taken at that time, e.g. either a `SUSPEND` or `TERMINATE_IMMEDIATE` request will be sent automatically to the merchant. ## OpenAPI ````yaml /openapi/current/dvm/reseller-to-dvm/entitlement/openapi.yaml post /topups/entitlements/{entitlementId} openapi: 3.1.0 info: title: Entitlements version: 1.4.2 description: > # Change log **2026-06-02** | v.1.4.2 - Updated authentication: replaced single Basic Auth scheme with X-API-Key, Basic Auth, and OAuth2 (client credentials) security schemes, aligned with Reseller Notifications API **2025-06-12** | v.1.4.1 - Overview & change log added **2024-09-04** | v.1.4.0 - Top ups released **2023-08-14** | v.1.3.0 - Added reseller-initiated /activationInfo endpoint - Added metadata to error responses to identify whether the error originated from Bango or the merchant. This is to help resellers resolve integration issues more easily. **2022-09-22** | v.1.2.0 - Added Bango-generated sharedCustomerId to reseller notifications, merchant requests and all responses **2021-08-05** | v.1.1.0 - Added extensionData for resellers - Added merchantExtensionData for merchants - Added financeData to relevant merchant-initiated API requests, reseller notifications and all responses - Added merchantBangoExtensionData for merchant requests and responses - Added externalEntitlementId for resellers **2020-11-03** | v.1.0.0 - Initial release servers: - url: https://resale.api.sandbox.bango.com description: Integration test environment - url: https://resale.api.bango.com description: Production environment security: - XApiKey: [] - BasicAuth: [] - OAuth2: [] tags: - name: Echo description: Check your connection to the Bango resale API - name: Entitlement description: Manage the lifecycle of your entitlements - name: Top Ups description: >- Top up short-lived entitlements for automated duration extension and suspend/terminate flows paths: /topups/entitlements/{entitlementId}: post: tags: - Top Ups summary: Create top ups description: > Only resellers are permitted to create top ups. You must include the idempotency header **X-RequestIdentifier** to ensure you do not accidentally add a top up multiple times to an entitlement in the event of an unexpected response (e.g. a timeout). You can also use the Get endpoint to check what top ups have been created for the entitlement. New top ups are automatically stacked to extend the duration of the entitlement. A suspended entitlement will be re-activated automatically. The 201 (created) response returns all dates associated to the top ups requested, as well as information on when the entitlement will now end, and what action will be taken at that time, e.g. either a `SUSPEND` or `TERMINATE_IMMEDIATE` request will be sent automatically to the merchant. parameters: - name: X-RequestIdentifier in: header description: Unique request identifier which supports idempotency required: true schema: type: string - name: entitlementId in: path description: Bango's unique id of the entitlement required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/TopUpRequest' responses: '201': description: Top up created content: application/json: schema: $ref: '#/components/schemas/TopUpResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BangoErrorResponse' '401': description: Unauthorized (no response body returned) '404': description: Entitlement not found content: application/json: schema: $ref: '#/components/schemas/BangoErrorResponse' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/BangoErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/BangoErrorResponse' '503': description: Service unavailable content: application/json: schema: $ref: '#/components/schemas/BangoErrorResponse' components: schemas: TopUpRequest: type: object required: - topUps properties: topUps: $ref: '#/components/schemas/TopUpsArray' TopUpResponse: type: object properties: entitlementId: type: string format: uuid topUpsExpiry: $ref: '#/components/schemas/TopUpsExpiry' topUps: type: array items: $ref: '#/components/schemas/TopUp' BangoErrorResponse: required: - responseMessage properties: responseMessage: type: string examples: - >- Variable error message providing more information about what went wrong metadata: $ref: '#/components/schemas/ErrorMetadata' TopUpsArray: type: array items: $ref: '#/components/schemas/TopUpRequestItem' TopUpsExpiry: type: object properties: ts: type: string format: date-time examples: - '2024-05-18T03:12:23.122Z' behavior: type: string enum: - SUSPEND - TERMINATE_IMMEDIATE TopUp: properties: topUpId: type: string format: uuid productKey: type: string examples: - MUSIC_10_DAYS createdTs: type: string format: date-time examples: - '2024-05-06T14:37:54.324Z' startTs: type: string format: date-time examples: - '2024-05-08T03:12:23.123Z' endTs: type: string format: date-time examples: - '2024-05-18T03:12:23.122Z' ErrorMetadata: properties: responseMessageFrom: type: string examples: - BANGO TopUpRequestItem: type: object required: - productKey properties: productKey: type: string examples: - MUSIC_10_DAYS securitySchemes: XApiKey: type: apiKey in: header name: x-api-key BasicAuth: type: http scheme: basic OAuth2: type: oauth2 description: > Bango uses https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/. Please note that when requesting a token, we only support the option to send the client secret in the request body flows: clientCredentials: tokenUrl: https://auth.bango.com/oath2/token scopes: any: >- grants Bango access to the merchant system based on merchant defined rules ````