Use sales developer APIs to migrate users into Arc XP Sales

You can migrate active subscriptions and their transactions (for example, payments and refunds) into Arc XP Subscriptions with no impact to your users. This process includes migrating and creating user accounts, products, prices, and offers for the digital subscription records.

Arc XP Subscriptions (Sales) accepts payment methods in the form of tokens from one of our approved PCI-compliant payment providers like Stripe Intents or Braintree.

1. Payment provider setup: You can configure the payment provider of your choice in the Admin tool. See Payment gateway providers.

2. Product and prices configuration: Configure your subscription products and prices in Subscriptions Retail Admin. You can link Arc XP products and price rates to the migrated subscriptions from the previous provider. Copy into Arc XP the same product SKUs and price structures (for example, rates, currency) that existed in the previous provider.

   Note

   If no products, prices, and tax rates that are identical to the originals exist in Arc XP Subscriptions, you cannot migrate the subscriptions successfully.

   Include the products and prices to be used in the migration within an offer, and publish it. Products and prices in published offers are automatically marked as published, which prevents accidental updates that may lead to errors in the future.

3. Migrate user accounts: Arc XP Sales links each subscription to its owner in Arc XP Identity. For subscriptions to be connected correctly, you must migrate current users need into Arc XP Subscriptions using the Batch Migration Developer API.

   Note

   For each user migrated, our system creates a user identifier (uuid, Login ID in CSR, e.g., 80f0e7cb-f129-4f46-81e0-c1afbca1789f). This is the value you need to pass as ownerClientID when migrating subscriptions.

4. Configure tax structure: If required, set up your tax structure. Arc XP Subscriptions currently offers two types of tax calculators: custom tax & Taxamo integration.

5. Request a placeholder provider: Migrated end users with subscriptions that plan to renew need to give the customer consent and agree that the accounts and payment details are correct before their renewals are processed. Because of this, during the subscription migration, all original payment providers are set aside to be referred to during a final migration step.

   The support team substitutes a placeholder payment provider (paymentProviderTypeId: 14), which is assigned to the migrated subscriptions. Now, any renewals that should happen after the migration are not charged until the customer has seen and agreed to the changes. When the customer agrees that their subscriptions are correct, the subscriptions team switches the placeholder provider with the actual provider ID for each migrated user subscription, and renewals are processed as normal.

   Note

   Subscription migrations are off in the Sandbox & Production environment by default due to the processing capacity required on the backend. Work with your Technical Account Manager to enable this configuration. You should coordinate a time with the Subscriptions team to perform your migration.

   Once you are familiar with migrations in the sandbox environment and have verified that all subscriptions were migrated correctly, you can proceed with the migration in the production environment. We recommend identifying a period of a couple of hours to run the subscription migrations in production. Performing the migration within a short time window is advisable because, once a subscription is migrated into Arc, we will begin charging for it. Therefore, the client is responsible for stopping payments in their old system.

   If you are migrating subscriptions different to paid ones (e.g. linked, complimentary, etc) you will need to use a different providerID for each subscription type. Work with your Technical Account Manager to grab the providerIDs. Once you complete the migration, we recommend going to the Subscription tab and checking that each subscription contains the correct information based on its subscription type.

6. Payment method migration: Arc XP Subscriptions can work with payment providers that we currently support to transition your payment tokens.

   If switching payment providers, then the PCI data needs to be extracted from the legacy provider and imported into the new provider, who then needs to provide a payment token to Arc XP that will be used for upcoming renewal payments. Clients must work with both payment providers to transition the payment information and obtain a JSON file with the payment tokens. This is needed during the subscription migration step.

   Note

   • All subscriptions must be migrated in batches. If a client wants to migrate multiple payment gateways in to Arc, then multiple place holders are required. For example, if the client is using Braintree and Stripe Intents, two place holders (with paymentProviderTypeId: 14) are requiered.
   • The payments migration batch should come after the batch that includes the subscriptions. Payments are optional and are so that the CSR app can show what happened for the user.
   • You may need two batches per website: subscription batch and payment info batch (optional).

7. Migrate subscriptions: After you complete the previous steps, you can start migrating your subscriptions. You can migrate your subscriptions by calling the Developer Subscription Migration API.

   Use a file containing all subscriptions and payment tokens with the Migration API. Migration API is not a standard application/json POST, like all the other APIs, but a multi-part file upload. This is due to the allowed size of the submitted data which can go up to 3MB.

   A WebSocket event of type Subscription_Migration is sent for each imported record.

   curl --request POST \
       --url 'https://{base_URL}/sales/api/v1/migrate?site={siteID}' \
       --header 'Authorization: Bearer {ARC_ACCESS_TOKEN}' \
       --header 'Content-Type: multipart/form-data' \
       --form subs=@/path/to/file/subs_to_migrate.json

   

   

Important!

• We do not store credit cards in any of our databases. The payment gateways store them for us, we store the resulting tokens. A token represents a credit card that has been stored. A subscription gets a token during checkout (passed to the finalize-payment API). During migrations we do not check that tokens are not reused, so many subscriptions can end up with the same token.
• Terminated subscriptions cannot be imported and therefore the associated payment tokens cannot be imported either. All imported subscriptions will be imported as active and could have historical payments imported for display purposes only.

In the next section, you will find details about the information that needs to be considered depending on the subscription type. For example, if you are trying to migrate a <LinkedSubscription> please check the Linked Subscriptions section.

Migrating Subscriptions: detailed information

Once the previous steps have been carried out, you can start to migrate subscriptions.

Main request

{
    "subscriptions": null | [
        { <LinkedSubscription> | <SharedSubscription> | <FreeSubscription> | <PaidSubscription> },
        { <LinkedSubscription> | <SharedSubscription> | <FreeSubscription> | <PaidSubscription> },
     { ... }
    ],
    "payments": null | [
        { <PaymentInfo> },
        { <PaymentInfo> },
        { ... },
    ]
}

Linked subscriptions

Linked is a subscription that is managed externally to Arc XP Subscriptions.

Dependencies: The following elements should be created in the system before migration: client (“ownerClientID”), product (“sku”), payment provider (“providerID”).

LinkedSubscription
{
    “type”:”linked”,
    "legacyID" *: "<legacy subscription ID – max 2048 characters>",
    "ownerClientID" *: <Arc Identity client ID>,
    "sku" *: <Arc Retail SKU>,
    “nextEventDateUTC” *: ”<YYYY-MM-DD HH24:mm – e.g. 2019-04-25 01:02– expiration date>”,
    "paymentMethod":  {
        "providerID" *: <integer provided by Arc>
    },
    "attributes": [
        {
            "name": "numSharesAllowed",
            "value": "integer – number of shares allowed – defaults to 0"
        },
        {
            "name": "linkToken",
            "value" *: "id in external system – max 2048 characters"
        }
    ]
}

Shared subscription

Shared is a subscription that is linked to a subscription managed by Arc XP Subscriptions.

Dependencies: The following elements should be created in the system before migration: client (“ownerClientID”), product (“sku”), payment provider (“providerID”), parent subscription (“value” for “name”: ” parentLegacyID”).

SharedSubscription
{
    “type”:”shared”,
    "legacyID" *: "legacy subscription ID - max 2048 characters",
    "ownerClientID" *: "Arc Identity client ID",
    "sku" *: "<Arc Retail SKU>"
    “paymentMethod”:{
        “providerID” *: <integer – provided by Arc>
    },
    “attributes”: [
        {
            "name”: ” parentLegacyID”,
            “value” *: “<parent subscription’s legacy ID – must have been imported prior>”
        }
    ]
}

Free subscription

Free is a subscription provided by the system during a certain period of time without paying for it.

Dependencies: The following elements should be created in the system before migration: client (“ownerClientID”), product (“sku”), payment provider (“providerID”).

FreeSubscription
{
    “type”:”free”,
    "legacyID" *: "<legacy subscription id  - max 2048 characters>",
    "ownerClientID" *: "<Arc Identity client ID>",
    "sku" *: "<Arc Retail SKU>",
    “nextEventDateUTC” *: ”<YYYY-MM-DD HH24:mm – e.g. 2019-04-25 01:02– expiration date>”,
    “paymentMethod”:{
        “providerID” *: <integer – provided by Arc>
    }
}

Paid subscription

Paid is a subscription acquired by a customer through a payment process.

Dependencies: The following elements should be created in the system before migration: client (“ownerClientID”), product (“sku”), price (price code), payment provider (“providerID”).

Paid subscriptions require tokenized card info (paymentMethod.token), the token format depends on the payment provider. Some examples are provided below.

Payment provider	Format	Example
Stripe Intents	<Token> (27 chars)	pm_1JsRLCCB9PxBy8pMCsf0AAQ2
Braintree	<UUID>~<card type> (36 chars~cardType)	88888888-4444-4444-4444-121212121212~MASTERCARD

PaidSubscription
{
    “type”:”paid”,
    “legacyID” *:”<legacy subscription ID – max 2048 characters>”,
    “ownerClientID” *:”<Arc Identity client ID”>”,
    “sku” *:”<Arc Retail SKU>”,
    “priceCode” *:”<Arc Retail price code>”,
    “currentCycle” *: <integer – where in the pricing sequence is this sub>,
    “nextEventDateUTC” *: ”<YYYY-MM-DD HH24:mm – next renewal due date>”,

    “paymentMethod” *:
        {
            “providerID” *: <integer – provided by Arc>,
            “token” *: ”<string – token from payment gateway>”,
            “firstSix”: ”<first six digits of credit card>”,
            “lastFour”: ”<last four digits of credit card>”,
            “expiration”: ”<MMyy>”,
            “cardholderName”: ”<string>”,
            “identificationNumber”: ”<string>”
        }

        “billingAddress” *:
        {
            “line1”:”<string>”,
            “line2”:”<string>”,
            “locality”:”<string>”,
            “region”:”<string>”,
            “postal”:”<string>”,
            “country” *:”<two characters e.g. US>”
        }

        “attributes": [
            {
                “name”:” numSharesAllowed”,
                “value”: <integer – number of shares allowed – defaults to 0>
            },
            {
                “name”:” campaignCode”,
                “value”:”<string for tracking purposes – max 2048 characters>”,
            },
            {
                “name”:” priorPaymentsURL”,
                “value”:”<link to legacy system – max 2048 characters>”
            }
        ]

PaymentInfo
    {
        "legacySubcriptionID" *: "<ID of associated legacy subscription>",
        "type" *: "payment",
        "paymentDateUTC" *: "<YYYY-MM-DD HH24:mm - e.g. 2019-04-21 01:02>",
        "amount" *: <e.g. 1.23>
        "currency" *: "<e.g. USD>"
        “tax” *: <e.g. 0>,
        “periodFromUTC” *: ”<YYYY-MM-DD HH24:mm – e.g. 2019-04-21 01:02 – accounting start time>”,
        “periodUntilUTC” *: ”<YYYY-MM-DD HH24:mm – e.g. 2019-05-18 01:02 – accounting end time>”,
        "providerReference": ”<if supplied may enabled refunds on legacy payments>”,
        "refunds" : null | [
            {
                "refundDateUTC" *: "YYYY-MM-DD HH24:mm – e.g. 2019-04-25 01:02 – refund date"
                "amount" *: <e.g. 0.5 – refunded amount>
                "currency" *: "<e.g. USD>"
                "tax" *: <e.g. 0 – tax portion of refund>
                "providerReference": ”<provider's reference number>”,
            }
        ]
    }

Migrating a PayPal Subscription

In order to migrate PayPal Subscriptions, you should first enable and configure additional settings. PayPal refers to those billing agreements starting with B- (ex: B-7TL686699Y2543901).

• The client’s PayPal account must be enabled for reference transactions via PayPal’s classic NVP/SOAP API. For this, the client must work with its PayPal rep.

PayPal can also be configured with the Braintree payment gateway. Braintree requires that reference transactions be available in the client’s PayPal account. For migrating PayPal Subscriptions via Braintree you will need:

• Migrate PayPal billing agreements to Braintree. The client must work directly with its Braintree rep to migrate PayPal billing agreements. This is out of the purview of Arc XP Subscriptions.

Risk, Assumptions, and Dependencies

• Clients are responsible for working with payment gateway needs in order to migrate the payment tokens.
• Arc XP Subscriptions is not PCI compliant so payment methods can only be imported in tokenized form for using tokens that work with one of Arc XP Sales’ payment providers.
• It is assumed that the client will use Arc XP Identity for user management
• It is assumed that client will use Arc XP Retail for product management.