> ## 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.

# Migrating to DVM

> Instructions for migrating existing subscriptions and entitlements to DVM.

## Prerequisites

Read the [migration overview](/migrations/migrations-overview) and ensure the pre-requisites are in place.

## How migration works

<Steps>
  <Step title="Prepare your migration files">
    Migration data is submitted as two JSON files, structured to match the DVM API format. If you already have a DVM™ integration, the data model will be familiar.

    **File 1 — Entitlement Migration File**

    Contains one record per entitlement being migrated. Each record describes the entitlement's current state and key lifecycle dates.

    ```csv theme={null}
    [
      {
        "externalEntitlementId": "123456789",
        "merchantEntitlementId": "ABCDEF",
        "entitlementId": "29ea58d1-6250-487c-886e-8336bfc837c5",
        "customerIdentifier": "4407123456789",
        "merchantAccountKey": "BANGO_US",
        "productKey": "MUSIC",
        "notificationUrl": "https://your.notification.url.com",
        "status": "ACTIVE",
        "dateCreated": {},
        "dateActivated": {}
      }
    ]
    ```

    <Note>
      Either `externalEntitlementId` or `entitlementId` must be provided. At least one is mandatory. If you provide `externalEntitlementId` without an `entitlementId`, the migration service will auto-generate a UUID for it. We recommend providing `entitlementId` upfront as a UUID v4, so you have a known reference before migration runs. Note that `dateCreated` must be before `dateActivated`.
    </Note>

    **File 2 — Consumer Offer Migration File**

    Contains pre-determined `consumerOfferId` values for each consumer. The Consumer Offer is the core object used for end-to-end subscription management via the DVM APIs. Getting this right is essential.

    ```csv theme={null}
    [
      {
        "consumerOfferId": "1586a9c8-d2a3-47b8-9576-c3036f078ca7",
        "offerId": "a44df4bf-fc54-4eae-b037-0ed38dd7bf3d",
        "consumerIdentifier": "user_123",
        "entitlementProducts": [
          {
            "resellerProductKey": "BANGO_GAMES",
            "merchantAccountKey": "BANGO_MEDIA"
          }
        ],
        "createRequestedTs": "2025-09-12T15:24:13Z",
        "entitlementIds": [
          "1586a9c8-d2a3-47b8-9576-c3036f078ca7"
        ]
      }
    ]
    ```

    <Note>
      `consumerOfferId` must be a UUID v4 generated by you prior to migration. `offerId` must reference an Offer already configured in the DVM Offer Catalog. The file links each entitlement to its Consumer Offer via the `entitlementIds` array.
    </Note>
  </Step>

  <Step title="Upload your files to cloud service storage">
    Upload both files to an cloud service storage (AWS s3), either your own (with read access granted to Bango) or one provided by Bango. Each file must have a unique name, including any reloads or resubmissions.
  </Step>

  <Step title="DVM imports and validates">
    DVM imports your files into the migration service and validates their contents before any data is written. If any issues are found, you will be notified so they can be resolved before migration proceeds.
  </Step>

  <Step title="Data migration runs">
    Once validation passes, the migration engine processes each record, migrating entitlements and creating the corresponding Consumer Offer objects in the DVM.

    The migration includes configurable error limits to catch problems early. For example, if the error rate exceeds a defined threshold (such as 10% of records, or 10 consecutive failures), the migration pauses automatically so issues can be investigated before continuing.
  </Step>

  <Step title="Post-migration validation">
    After migration completes, a validation script confirms the successful creation of all Consumer Offer records and verifies that the related Entitlement IDs are correctly associated.

    A report is generated containing the objects and metadata you need to manage your subscriptions via the DVM APIs going forward.
  </Step>
</Steps>

***

## Error handling and recovery

The migration is designed to be resilient. If individual records fail during processing, they may be recoverable depending on the stage at which the failure occurred. Bango will work with you to investigate and resolve any failures before reprocessing affected records.

<Tip>
  Configuring an appropriate error threshold before running a large migration is strongly recommended. It limits the blast radius of any unexpected data issues and makes recovery faster.
</Tip>

## What to read next

Read more about migration in our [Migration guide](/guides/reseller-guides/migrating-to-dvm), a full explanation of migration to DVM.