On This Page

Recurring Billing Subscription Data Migration Guide

This section presents the guide usage
and additional information sources
.
Audience and Purpose
This guide is for merchants who use the
Token Management Service
 (
TMS
) and transition recurring billing data and workflows from their current provider to
Cybersource
 Recurring Billing.
Conventions
This document uses this statement type:
IMPORTANT
An
Important
 statement contains information essential to completing a task or learning a concept.
Related Documentation
Visit the
Cybersource
 documentation hub to find additional technical documentation.
Customer Support
Visit the Support Center for service support information:

Recent Revisions to This Document

25.10.01

Initial release.

VISA Platform Connect: Specifications and Conditions for Resellers/Partners

The following are specifications and conditions that apply to a Reseller/Partner enabling its merchants through
Cybersource for
Visa Platform Connect
 (“VPC”) processing
. Failure to meet any of the specifications and conditions below is subject to the liability provisions and indemnification obligations under Reseller/Partner’s contract with Visa/Cybersource.
  1. Before boarding merchants for payment processing on a VPC acquirer’s connection, Reseller/Partner and the VPC acquirer must have a contract or other legal agreement that permits Reseller/Partner to enable its merchants to process payments with the acquirer through the dedicated VPC connection and/or traditional connection with such VPC acquirer.
  2. Reseller/Partner is responsible for boarding and enabling its merchants in accordance with the terms of the contract or other legal agreement with the relevant VPC acquirer.
  3. Reseller/Partner acknowledges and agrees that all considerations and fees associated with chargebacks, interchange downgrades, settlement issues, funding delays, and other processing related activities are strictly between Reseller and the relevant VPC acquirer.
  4. Reseller/Partner acknowledges and agrees that the relevant VPC acquirer is responsible for payment processing issues, including but not limited to, transaction declines by network/issuer, decline rates, and interchange qualification, as may be agreed to or outlined in the contract or other legal agreement between Reseller/Partner and such VPC acquirer.
DISCLAIMER: NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR ANY ERRORS OR OMISSIONS BY THE
Visa Platform Connect
 ACQUIRER IN PROCESSING TRANSACTIONS. NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR RESELLER/PARTNER BOARDING MERCHANTS OR ENABLING MERCHANT PROCESSING IN VIOLATION OF THE TERMS AND CONDITIONS IMPOSED BY THE RELEVANT
Visa Platform Connect
 ACQUIRER.

Introduction to Migrating Subscription Data to
Cybersource
 Recurring Billing

Transitioning recurring billing subscriptions from another provider to the
Cybersource
 Recurring Billing service improves payment processes and customer experience. This guide provides step-by-step instructions for migrating existing recurring billing data and workflows to the
Cybersource
 platform.

Migration Flow

The migration process involves writing and running a script that creates Recurring Billing subscriptions in the
Cybersource
 account. This topic presents an overview of the process.
Prepare for the migration.
 Before beginning the migration process, understand the limitations and ensure all migration prerequisites are met.
Perform these five tasks twice: first in your
Cybersource
 test environment and after validating the test migration, in your
Cybersource
 production environment.
  • Task 1: Enable the
    Cybersource
     Recurring Billing service.
     After migration prerequisites are met, request activation of Recurring Billing for your
    Cybersource
     account. When you receive the confirmation notice, proceed to the next task.
  • Task 2: Integrate with the
    Cybersource
     API.
    Generate API keys for your preferred authentication method at the
    Cybersource
    Business Center
    . Integrate this authentication method into your migration script using the
    Cybersource
     API.
  • Task 3: Export your current subscriptions to a file.
    Export all active subscriptions from your current provider to a file. In the next task, you write and run a migration script that parses the export file and creates subscriptions on the
    Cybersource
     system.
  • Task 4: Create new subscriptions in the
    Cybersource
     system.
    Write and run a script that sends subscription creation requests to the
    Cybersource
     subscription service. The new subscriptions replicate the active subscriptions in your current subscriptions provider.
  • Task 5: Validate the new subscriptions in your test environment.
    After running the subscription creation script, verify that the newly created subscriptions match your exported subscription data. Within your test environment, send test transactions in order to validate proper setup.
Finalize the migration.
In your production environment, monitor the transactions of the new subscriptions. Verify that your subscriptions are successfully transitioned from your former subscriptions provider. To avoid creating duplicate charges, deactivate the recurring billing feature on the former subscriptions provider.

Migration Limitations

Only subscriptions in the
active
 state can be migrated to
Cybersource
 Recurring Billing.

Migration Prerequisites

Before migrating subscriptions to
Cybersource
 Recurring Billing, ensure these prerequisites are met.
Understanding of Recurring Billing Subscription Management
Understand Recurring Billing subscription management in the
Cybersource
 system. Review these guides for details:
Cybersource
Token Management Service
 is Configured with a Token Vault
Recurring Billing requires that you have a
Cybersource
 account with a properly configured
Token Management Service
 (
TMS
) at the transacting MID level and with a configured token vault.
 For details, see the .
Customer Tokens from Your Current Provider Are in the
Cybersource
TMS
Cybersource
 Recurring Billing uses only the
customer token
 type. The customer tokens from your current subscriptions provider must be in
Cybersource
TMS
 before you begin to migrate subscription data from that provider to the
Cybersource
 system.
IMPORTANT
Token migration from a system outside the
Cybersource
 system is a separate process that requires coordination with your
Cybersource
 Account Manager.

Task 1: Enable Recurring Billing in Your
Cybersource
 Account

Recurring Billing requires that you have a
Cybersource
 account with a properly configured
Token Management Service
 (
TMS
) at the transacting MID level and with a configured token vault.
 In addition, customer tokens from the current provider must be in the
Cybersource
TMS
.
  1. To enable Recurring Billing:
  2. Verify that you have a
    Cybersource
     account.
  3. Confirm your account has a transacting MID with
    TMS
     and token vault configuration. See Migration Prerequisites for details.
  4. Verify that customer tokens from the current provider exist in the
    Cybersource
    TMS
    . See Migration Prerequisites for details.
  5. Contact your
    Cybersource
     Account Manager to request activation of Recurring Billing for your account.
  6. After receiving the confirmation notice, proceed to Task 2: Integrate with the Cybersource API.

Task 2: Integrate with the
Cybersource
 API

Set up authentication using either JSON Web Token (JWT) or HTTP Signature.
Generate API keys for your preferred authentication method at the
Cybersource
Business Center
. Integrate this authentication method into your migration script using the
Cybersource
 API.
  1. To integrate with the
    Cybersource
     API:
  2. Log in to your
    Cybersource
     account at the
    Business Center
    .
  3. Set up your
    Cybersource
     account for secure communication of REST API messages using either JSON Web Token or HTTP Signature. Generate a P12 key for JWT or a shared secret key pair for HTTP Signature: Set Up Your
    Cybersource
     Account
  4. Integrate the selected authentication method into the subscription creation script.

Task 3: Export Current Subscriptions to a File

Export all active subscriptions from your current provider to a file. In the next task, you write and run a migration script that parses the export file and creates subscriptions on the
Cybersource
 system.
IMPORTANT
Only subscriptions in the
active
 state can be migrated to
Cybersource
 Recurring Billing.
  1. To export subscription data from your current provider:
  2. Export all active subscriptions from your current provider to a local file. Use a flat text file, CSV file, or Excel spreadsheet.
  3. Organize the exported data so that each subscription record is easily processed by the script that you write and run in Task 4: Create New Subscriptions.

    ADDITIONAL INFORMATION

    TIP
    Optionally, include a JSON-formatted REST API request in each subscription record.
  4. Ensure each subscription record in the export file includes information required to construct a
    Cybersource
     API request that creates an equivalent subscription in
    Cybersource
     Recurring Billing.

    ADDITIONAL INFORMATION

    The fields required in the API request message vary based on the plan options for the subscription. For lists of required fields in the
    Cybersource
     API request, see the example requests in Reference Information.
    IMPORTANT
    A Recurring Billing subscription on the
    Cybersource
     platform begins billing on the date specified in the
    subscriptionInformation. startDate
     field of the request unless you manually
    suspend
     or
    cancel
     the subscription after it is created.
  5. Save a copy of the export file.

    ADDITIONAL INFORMATION

    IMPORTANT
    You need this export file for subsequent migration tasks.

Task 4: Create New Subscriptions

Write and run a script that sends subscription creation requests to the
Cybersource
 subscription service. The new subscriptions replicate the active subscriptions in your current subscriptions provider.
This section contains information for writing the subscription creation script:
  • Requirements for the subscription creation script.
    Adhere to these requirements as you write the subscription creation script.
  • Additional API field required for any credit or debit card subscription.
    When migrating a credit or debit card payment subscription from a provider outside of the
    Cybersource
     system, include the network transaction ID of the authorized transaction from the previous provider system to avoid re-authorization for a new, zero-value credit card payment.
  • Additional API field required for a Diners or Discover card.
    For subscriptions on Diners cards or Discover cards, also include the authorized payment amount from your previous provider system.
  • How to obtain the additional information required for a credit or debit card subscription.
    The network transaction ID and the authorized payment amount are in the
    Cybersource
    Token Management Service
     (
    TMS
    ), provided that the network transaction ID of the original subscription (from the previous provider) are now in
    Cybersource
    TMS
    .
     This condition is a prerequisite for migration.
  • Construct your subscription creation script.
    For each subscription record that you exported from your former subscription provider, your script must submit an API request to create a new Recurring Billing subscription in the
    Cybersource
     system.

Requirements for the Subscription Creation Script

Adhere to these requirements as you write the subscription creation script.
Migration log file
The script logs each API request message sent and the corresponding response information returned by the
Cybersource
 subscription service.
Retry logic
For failed subscription creation requests, correct the request and resubmit it to the subscription service.
Billing start date
Cybersource
 Recurring Billing subscriptions begin billing on the date specified in the
subscriptionInformation.startDate
 field.
Reusable set of billing periods and billing cycles
Create a
subscription plan
 that defines a billing period (or billing cycle) and a number of billing cycles. In the REST API, use these fields:
Plan options for new subscriptions
Cybersource
 Recurring Billing subscriptions support these plan options:
  • Define a
    one-time plan
     for a subscription instead of creating a subscription plan.
  • Use the plan information defined in the
    existing plan
     referenced by the
    subscriptionInformation. planId
     field in the subscription creation message.
  • Specify
    overrides
     to some of the information in the referenced plan. For example, if the subscription was for a fixed period, specify the remaining number of billing cycles in the
    planInformation. billingCycles.total
     field.
For detailed examples of how to create plan-specific subscriptions, see Reference Information.

Additional Fields Required for Card Subscriptions

This section describes additional requirments for the subscription creation script. One or two additional fields must be included in a subscription creation request for a credit or debit card subscription.

Additional API Field Required for Any Credit or Debit Card Subscription

If the subscription is for a credit or debit card, the subscription creation request must include the
network transaction ID
 of the transaction that originally initialized the subscription (and allowed for the storage of payment information).
Include the network transaction ID in this field of the subscription creation request message:
subscriptionInformation. originalTransactionId
For information about obtaining the network transaction ID, see Obtaining Additional Values Required for Card Subscriptions.
Continue to use this network transaction ID to uniquely identify future automatic payments for this subscription.
IMPORTANT
Including the network transaction ID in the subscription creation request obtains the payer's consent for you to make automatic (recurring) payments with the new subscription in the
Cybersource
 system.

Additional API Field Required for a Diners or Discover Card

If the subscription is for a Diners card or Discover card, also include the
payment amount
 that was authorized in the provider system that initialized the subscription and allowed for the storage of payment information.
Include the payment amount in this field of the subscription creation request message:
subscriptionInformation. originalTransactionAuthorizedAmount
For information about obtaining the payment amount, see Obtaining Additional Values Required for Card Subscriptions.

Obtaining Additional Values Required for Card Subscriptions

The network transaction ID and the authorized payment amount are in the
Cybersource
Token Management Service
 (
TMS
), provided that the network transaction ID of the original subscription (from the previous provider) are now in
Cybersource
TMS
.
Three possibilities exist:
  • Original subscription data is in
    Cybersource
    TMS
  • Original subscription data is not in
    Cybersource
    TMS
     but it is available from the original subscription provider
  • Original subscription data is not available

Retrieve Original Subscription Data from the
Cybersource
TMS

As a prerequisite to migration, customer tokens from your original provider are in the
Cybersource
TMS
. If this prerequisite is met, you can retrieve the additional data required for card subscriptions from the
Cybersource
TMS
.
This topic applies to migrating a credit or debit card subscription to
Cybersource
 when the original subscription data (from the original subscription provider) is now in
Cybersource
TMS
.
  1. To retrieve original subscription data from the
    Cybersource
    TMS
    :
  2. Perform this GET request:

    ADDITIONAL INFORMATION

    • Production:
      GET
      https://api.cybersource.com
      /tms/v2/customers/{customerId}
    • Test:
      GET
      https://apitest.cybersource.com
      /tms/v2/customers/{customerId}
    Replace the
    {customerId}
     portion of the URL with the ID of the customer associated with the subscription in the previous provider system
  3. Retrieve the ID of the original transaction from this field of the response to the GET request:

    ADDITIONAL INFORMATION

    _embedded.defaultPaymentInstrument. _embedded.instrumentIdentifier. processingInformation. authorizationOptions. initiator. merchantInitiatedTransaction. previousTransactionId
  4. Include the network transaction ID in this field of the subscription creation request message that the script sends to the
    Cybersource
     subscription service:

    ADDITIONAL INFORMATION

    subscriptionInformation. originalTransactionId
  5. If the subscription is for a Diners card or Discover card:
    1. Retrieve the authorized payment amount from this field of the response to the GET request:

      ADDITIONAL INFORMATION

      _embedded.defaultPaymentInstrument. _embedded.instrumentIdentifier. processingInformation. authorizationOptions. initiator. merchantInitiatedTransaction. originalAuthorizedAmount
    2. Include the authorized payment amount in this field of the subscription creation request message that the script sends to the
      Cybersource
       subscription service:

      ADDITIONAL INFORMATION

      subscriptionInformation. originalTransactionAuthorizedAmount

Retrieve Original Subscription Data from the Original Provider

This topic applies to migrating a credit or debit card subscription to
Cybersource
 when the original subscription data is not in
Cybersource
TMS
 but it is available from the original subscription provider.
  1. To retrieve original subscription data from the original subscription provider:
  2. Contact the previous subscriptions provider to obtain data from the original subscription.
  3. Request the network transaction ID for original subscription.
  4. Include the network transaction ID in this field of the subscription creation request message that the script sends to the
    Cybersource
     subscription service:

    ADDITIONAL INFORMATION

    subscriptionInformation. originalTransactionId
  5. If the subscription is for a Diners card or Discover card:
    1. Request the authorized payment amount for the original subscription.
    2. Include the authorized payment amount in this field of the subscription request that the script sends to the
      Cybersource
       subscription service:

      ADDITIONAL INFORMATION

      subscriptionInformation. originalTransactionAuthorizedAmount

When Original Subscription Data Cannot Be Retrieved

To migrate a credit or debit card subscription when the original subscription data is not available in
Cybersource
TMS
 or from the original subscription provider, re-authorize a new, zero-value card payment.
IMPORTANT
Attempting to create a new subscription by re-authorizing a new, zero-value credit card payment often triggers indeterminate conditions, such as
3-D Secure
 authentication failure.

Construct Your Subscription Creation Script

For each subscription record that you exported from your former subscription provider, your script must submit an API request to create a new Recurring Billing subscription in the
Cybersource
 system.
  1. For each subscription, instructions in your script must:
  2. Create the subscription creation request message with the required
    REST
     API fields.

    ADDITIONAL INFORMATION

    ADDITIONAL INFORMATION

  3. Send the message to one of these endpoints:
    • Production:
      POST
      https://api.cybersource.com
      /rbs/v1/subscriptions
    • Test:
      POST
      https://apitest.cybersource.com
      /rbs/v1/subscriptions
  4. Check the response messages to verify that the request was successful.

    ADDITIONAL INFORMATION

    A 200-level HTTP response code indicates success. See the
    Transaction Response Codes
    .
  5. Write the request and response information to the log file for troubleshooting and verification purposes.
  6. For transaction errors, perform error handling and retry logic when appropriate.

Task 5: Validate the New Subscriptions in the
Cybersource
 System

After running the subscription creation script, verify that the newly created subscriptions match your exported subscription data. Within your test environment, send test transactions in order to validate proper setup.
Perform the validation at the
Cybersource
Business Center
 or using REST API requests.

Use the
Business Center
 to Validate Migrated Subscriptions

IMPORTANT
To validate, compare the new
Cybersource
 subscription details to the export file you created in Task 3: Export Current Subscriptions to a File.
  1. To validate migrated subscriptions using the
    Cybersource
    Business Center
    :
  2. Log in to your
    Cybersource
     account at the
    Business Center
    .
  3. On the left navigation panel, click
    Recurring Billing
     and
    Manage Subscriptions
    .

    ADDITIONAL INFORMATION

    The Recurring Billing Manage Subscriptions screen appears. The Search Results section lists all managed subscriptions that are accessible to your
    Cybersource
     account.
  4. To validate the details of a specific subscription:
    1. In the Recurring Billing Manage Subscriptions screen, click
      Add–Filter
      .
    2. In the New Filter drop-down menu, choose the type of data on which you want to filter the subscription list and choose or enter the value on which to match subscriptions.

      ADDITIONAL INFORMATION

      You can filter the list by subscription code, account owner first or last name, plan name, or subscription status.
    3. Click
      Search
      .
    4. In the filtered list, click the subscription code of the subscription you want to view.

      ADDITIONAL INFORMATION

      The Subscription Details screen appears and displays this information:
      • Subscription ID
         is an identifier unique to this subscription. Use this ID to identify this subscription in API references and to assist in customer service.
      • Subscription details
         include the subscription start date, billing cycle, and setup fee.
      • Customer details
         include the customer token and the customer ID.
      • Payment details
         include the card type, card expiration date, billing address, and the payment instrument ID.
      • Shipping details
         are displayed if the information is available for the customer.
    5. Compare the subscription details to the corresponding subscription details in the export file.
  5. To validate subscriptions created for a specific customer:
    1. On the left navigation panel, click
      Token Management
       and
      Customers
      .

      ADDITIONAL INFORMATION

      The Token Management Customers screen appears.
    2. In the New Filter drop-down menu, choose the type of data on which you want to filter customer tokens and choose or enter the value on which to match tokens.

      ADDITIONAL INFORMATION

      To filter subscriptions on a customer email address, select
      Email
       and enter the address.
    3. Click
      Search
      .
    4. In the Search Results, click the token ID of the customer for which you want to view subscriptions.
    5. In the Token Management Customer Details screen, click
      Manage Subscriptions
      . The Recurring Billing Manage Subscription screen appears and lists subscriptions associated with the customer token you viewed.
    6. Compare the subscription details to the corresponding subscription details in the export file.
  6. (Recommended in your test environment) Send test transactions to validate proper setup.

Use the REST API to Validate Migrated Subscriptions

IMPORTANT
To validate the migration, compare the new
Cybersource
 subscription details to the export file you created in Task 3: Export Current Subscriptions to a File.
  1. Follow these steps to use the
    Cybersource
     REST API to validate the migrated subscriptions:
  2. Follow these steps if you want to validate a specific subscription:
    1. To obtain the details of a specific subscription, see Retrieving a Subscription in the
      Recurring Billing Developer Guide
      . The subscription details are returned in the response message.
    2. Compare the subscription details to the corresponding subscription details that you exported to a file in Task 3: Export Current Subscriptions to a File. The subscription details are returned in the response message.
  3. Follow these steps if you want to validate a list of all subscription details:
    1. To obtain a list of all subscription details, see Retrieving a List of Subscriptions in the
      Recurring Billing Developer Guide
      . The list of subscription details is returned in the response message.
    2. Compare the
      Cybersource
       subscription details in the list to the subscription details in the export file from Task 3: Export Current Subscriptions to a File.
  4. (Optional)
    Complete these steps if you want to
    cancel
     a pending, active, suspended, or delinquent subscription:
    1. In the subscription details, find the subscription ID.
    2. Send the message to one of these endpoints, replacing the
      {id}
       portion of the URL with the value of the subscription ID:
      • Production:
        POST
        https://api.cybersource.com
        /rbs/v1/subscriptions/{id}/cancel
      • Test:
        POST
        https://apitest.cybersource.com
        /rbs/v1/subscriptions/{id}/cancel
    3. Check the response message to verify that the request was successful. A 200-level HTTP response code indicates success.
  5. (Recommended in your test environment) Send test transactions to validate proper setup.

Finalize the Migration

In your production environment, monitor the transactions of the new subscriptions. Verify that your subscriptions are successfully transitioned from your former subscriptions provider. To avoid creating duplicate charges, deactivate the recurring billing feature on the former subscriptions provider.
  1. To complete the migration:
  2. Actively monitor the Recurring Billing subscription transactions on the
    Cybersource
     platform.

    ADDITIONAL INFORMATION

    For information about reports that contain Recurring Billing transaction details, see these topics in the
    Reporting User Guide
    :

    ADDITIONAL INFORMATION

    Recommendations:
    • Track subscriptions that have payments scheduled to occur over several consecutive days. Confirm that the payments complete successfully and that the subscriptions remain active.
    • Confirm that the rate of declined transactions is not elevated.
  3. After verifying that all active subscriptions and subscription data are successfully transitioned to
    Cybersource
     Recurring Billing, deactivate Recurring Billing on the former subscriptions provider platform.

Reference Information

This section contains reference information for migrating subscriptions from the current subscriptions platform to Recurring Billing subscriptions on the
Cybersource
 platform.
This reference information is supplemental to Task 4: Create New Subscriptions.
  • How to access and use the interactive REST API reference.
    The
    Cybersource
     Developer Center includes an interactive
    REST API Reference
    . As you write your script, you can use the interactive module to help construct request messages for creating Recurring Billing plans and subscriptions.
  • How to create a subscription for a one-time plan.
    These topics provide detailed information about how to request the creation of a subscription that uses a one-time plan.
  • How to create a subscription for an existing plan.
    These topics provide detailed information about how to request the creation of a subscription that uses an existing plan.
  • How to create a subscription with plan overrides.
    These topics provide detailed information about how to request the creation of a subscription that uses plan overrides.

Using the Interactive REST API Reference

After exporting subscription data from your current provider in Task 3: Export Current Subscriptions to a File, write a subscription creation script that accesses entries in your export file and recreates each subscription within
Cybersource
 Recurring Billing.
The
Cybersource
 Developer Center includes an interactive
REST API Reference
. As you write your script, you can use the interactive module to help construct request messages for creating Recurring Billing plans and subscriptions.

Build a Request to Create a Recurring Billing Plan

  1. Follow these steps to access the interactive REST API reference for creating a Recurring Billing plan:
  2. Go to the
    REST API Reference
     on the Cybersource Developer Center.
  3. On the left navigation panel, click
    Payments
     and
    Recurring Billing Subscriptions
    .
  4. Click
    Create a Plan
    . The screen appears.

Build a Request to Create a Recurring Billing Subscription

  1. Follow these steps to access the interactive REST API reference for creating Recurring Billing subscriptions:
  2. Go to the
    REST API Reference
     on the Cybersource Developer Center.
  3. On the left navigation panel, click
    Payments
     and
    Recurring Billing Subscriptions
    .
  4. Click
    Create a Subscription
    . The screen appears.

Creating a Subscription with a One-Time Plan

As you write your script, refer to the information in this section as a guide for requesting creation of a subscription with a one-time plan:
  • Required and optional fields for the request to create subscription with a one-time plan
  • Example request to create a subscription with a one-time plan

Required and Optional Fields

These fields are required for creating a subscription with a one-time plan:

Optional Fields

subscriptionInformation.originalTransactionId
Required to create any credit or debit card subscription.
Including this field ensures better authorization rates and Strong Customer Authentication (SCA) compliance where necessary.
subscriptionInformation.originalTransactionAuthorizedAmount
Additional required field for a Diners or Discover card.
.

REST Example: Create a Subscription with a One-Time Plan

This example creates a subscription with a one-time plan.
Request
{
  "planInformation": {
    "billingPeriod": {
      "length": "1",
      "unit": "M"
    },
    "billingCycles": {
      "total": "24"
    }
  },
  "subscriptionInformation": {
    "name": "Subscription with one-time plan",
    "startDate": "2025-08-10",
    "originalTransactionId": "123456789",
    "originalTransactionAuthorizedAmount": "0.00"
  },
  "paymentInformation": {
    "customer": {
      "id": "C24F5921EB870D99E053AF598E0A4105"
    }
  }
}
Example Response to a Successful Request
{
    "_links": {
        "self": {
            "href": "/rbs/v1/subscriptions/1619214861",
            "method": "GET"
        },
        "update": {
            "href": "/rbs/v1/subscriptions/1619214861",
            "method": "PATCH"
        },
        "cancel": {
            "href": "/rbs/v1/subscriptions/1619214861/cancel",
            "method": "POST"
        }
    },
    "id": "1619214861",
    "status": "COMPLETED",
    "subscriptionInformation": {
        "code": "AWC-49",
        "status": "PENDING"
    }
}
Example Response to a Failed Request
{
    "status": "INVALID_REQUEST",
    "reason": "INVALID_DATA",
    "message": "One or more fields in the request contains invalid data.",
    "details": [
        {
            "field": "planInformation.billingPeriod.length",
            "reason": "MAX_LENGTH"
        }
    ]
}

Creating a Subscription with an Existing Plan

As you write your script, refer to the information in this section as a guide for requesting creation of a subscription with an existing plan:
  • Required and optional fields for the request to create subscription with an existing plan
  • Example request to create a subscription with an existing plan

Required and Optional Fields

These fields are required for creating a subscription with an existing plan:
subscriptionInformation.planId
Required when you are using a standard plan.

Optional Fields

subscriptionInformation.originalTransactionId
Required to create any credit or debit card subscription.
Including this field ensures better authorization rates and Strong Customer Authentication (SCA) compliance where necessary.
subscriptionInformation.originalTransactionAuthorizedAmount
Additional required field for a Diners or Discover card.

REST Example: Create a Subscription with an Existing Plan

This example creates a subscription that uses an existing plan.
Request
{
  "subscriptionInformation": {
    "planId": "6868912495476705603955",
    "name": "Subscription with plan id",
    "startDate": "2025-08-10",
    "originalTransactionId": "123456789",
    "originalTransactionAuthorizedAmount": "0.00"
  },
  "paymentInformation": {
    "customer": {
      "id": "C24F5921EB870D99E053AF598E0A4105"
    }
  }
}
Example Response to a Successful Request
{
    "_links": {
        "self": {
            "href": "/rbs/v1/subscriptions/1619214690",
            "method": "GET"
        },
        "update": {
            "href": "/rbs/v1/subscriptions/1619214690",
            "method": "PATCH"
        },
        "cancel": {
            "href": "/rbs/v1/subscriptions/1619214690/cancel",
            "method": "POST"
        }
    },
    "id": "1619214690",
    "status": "COMPLETED",
    "subscriptionInformation": {
        "code": "AWC-47",
        "status": "PENDING"
    }
}
Example Response to a Failed Request
{
    "status": "INVALID_REQUEST",
    "reason": "INVALID_DATA",
    "message": "One or more fields in the request contains invalid data.",
    "details": [
        {
            "field": "subscriptionInformation.startDate",
            "reason": "INVALID_DATA"
        }
    ]
}

Creating a Subscription with Plan Overrides

As you write your script, refer to the information in this section as a guide for requesting creation of a subscription with plan overrides.

Required and Optional Fields

These fields are required for creating a subscription with plan overrides:

Optional Fields

Amount charged during the billing period.
The subscription set-up fee charged by the merchant.
planInformation.billingCycles.total
subscriptionInformation.originalTransactionId
Required to create any credit or debit card subscription.
Including this field ensures better authorization rates and Strong Customer Authentication (SCA) compliance where necessary.
subscriptionInformation.originalTransactionAuthorizedAmount
Additional required field for a Diners or Discover card.

REST Example: Create a Subscription with Plan Overrides

This example creates a subscription that overrides part of an existing plan. For example, you can use an existing plan with an indefinite duration and a specific amount, and then, for a given subscription, specify the number of remaining billing cycles.
Request
{
  "planInformation": {
    "billingCycles": {
      "total": "5"
    }
  },
  "subscriptionInformation": {
    "planId": "6868912495476705603955",
    "name": "Subscription with plan id and new number of billing cycles",
    "startDate": "2025-08-10",
    "originalTransactionId": "123456789",
    "originalTransactionAuthorizedAmount": "0.00"
  },
  "paymentInformation": {
    "customer": {
      "id": "C24F5921EB870D99E053AF598E0A4105"
    }
  }
}
Example Response to a Successful Request
{
    "_links": {
        "self": {
            "href": "/rbs/v1/subscriptions/1619214795",
            "method": "GET"
        },
        "update": {
            "href": "/rbs/v1/subscriptions/1619214795",
            "method": "PATCH"
        },
        "cancel": {
            "href": "/rbs/v1/subscriptions/1619214795/cancel",
            "method": "POST"
        }
    },
    "id": "1619214795",
    "status": "COMPLETED",
    "subscriptionInformation": {
        "code": "AWC-48",
        "status": "PENDING"
    }
}
Example Response to a Failed Request
{
    "status": "INVALID_REQUEST",
    "reason": "DUPLICATE_REQUEST",
    "message": "Duplicate requests are not supported within 15 minutes.",
    "details": [
        {
            "field": "subscriptionInformation.planId or paymentInformation.customer.id or subscriptionInformation.startDate or subscriptionInformation.name",
            "subscriptionId": "1619214795",
            "reason": "INVALID_DATA"
        }
    ]
}