> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slm.m1amdocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AutoBill.migrate

The `migrate` method enables you to import existing subscription and transaction information from your current billing system into Subscribe. This call creates new `AutoBills` that reflect the imported information.

You can call `AutoBill.migrate` multiple times for a given `AutoBill`. With the first call, Subscribe creates the `AutoBill` and builds the billing schedule records that correspond to any `MigrationTransactions` that are included in the call.

You can also use this method to specify a regular billing in advance of, or after, the Service Period start date. You can allow the service dates to be maintained according to the billing plan, while billing for those periods on specified days of the month, before or after the scheduled service date, using the *specifiedBillingDay* and *billingRule* parameters.

When you call `AutoBill.migrate` on an existing `AutoBill`—that is, when you specify the `VID` or of an existing AutoBill—Subscribe backfills the AutoBill Transaction history, (importing older Transactions for the subscription), and makes no attempt to update the `AutoBill` itself.

**Note:** While you can create new `Accounts` and `PaymentMethods` with this call, you cannot create new `Products` or `BillingPlans`, so be sure to create any `Products` or `BillingPlans` referenced by an input `MigrationTransaction` object before making the call.

`AutoBill.migrate` supports the following payment processors:

* Chase Paymentech
* Merchant e-Solutions
* Litle & Co.
* PayPal

`AutoBill.migrate` supports the following payment methods:

* Credit Card
* PayPal
* Merchant accepted payment (MAP)—Pay By Invoice

## Input

*srd*: sparse response description, a SOAP string (which must be a JSON object), in which you specify the elements you want returned.This parameter enables the calling system to constrain a `method` call to return only components you specify. This gives you greater control over returned content, and improves response time within the Vindicia platform by reducing the processing needed for the call.

Some fields are required, either practically or in the WSDL, and will be returned regardless of the *srd*. A null *srd* returns the complete response.

*autobill*: the `AutoBill` object to migrate to Subscribe.

To specify a regular billing in advance of, or after, the regularly scheduled Service Period start date, use the following parameters:

* *specifiedBillingDay*: an integer (1-31) specifying the day of the month on which to bill (values 29-31 automatically work as the last day of the month for calendar months that do not have 29, 30, or 31 days). Providing no value or null in this parameter instructs Subscribe to bill on the service period start date (the default).
* *billingRule*: an enumerated string value (`Advance` or `Arrears`), informing Subscribe in which direction from the scheduled billing date to select the specified billing date. If no `specified_billing_day` is provided, this parameter is ignored.

You can use these parameters to change the billing date at migration (or creation) of an AutoBill object, or specify them later using `AutoBill.update`. For more information, see Advance and Arrears Billing Option for AutoBills in the Subscribe Programming Guide.

**Note:**

For this call, the following `AutoBill` data members are required:

* `account`
* `billingPlan`
* `currency`
* `items`
* `paymentMethod` (For this call, this field must be `CreditCard` or MAP)
* `startTimestamp`

*nextPeriodStartDate*: the next scheduled billing date for this AutoBill. If not provided, it will be assumed that this AutoBill is terminal and no future billings are to be scheduled. (For the first `AutoBill.migrate` call for a given `AutoBill`, this field is required.)

When migrating a subscription with a Merchant Accepted Payment (MAP), specifying a `nextPeriodStartDate` will alter the invoice/billing schedule. If this parameter is not set, Subscribe will create all invoices from the last transaction provided to “now” and schedule the next (an invoice in OPEN status) according to the billing plan provided.

*migrationTransactions*: an array of `MigrationTransaction` objects that define the history of this AutoBill.

When migrating Transactions with a MAP, a Transaction for this `AutoBill` must be included in the initial `AutoBill.migrate` call; and the latest status record must show that the `Transaction` is either `Captured`, `Canceled`, `Refunded,Settled`or `Void`. No other `TransactionStatus` values may be used for this call.

Also for MAP, we strongly recommend that you provide at least the last invoice transaction. Regardless of how many transactions you include, Subscribe will create invoices for all periods between the “last transaction” and “now”. If you provide no Transactions, Subscribe will create an invoice for every period since the indicated start date of the subscription. Unless a successful Transaction is provided, Subscribe will assume an invoice period is unpaid (DUE or OVERDUE).

Subscribe will not create invoices for periods prior to the last provided transaction unless covered by another migrated transaction—unspecified periods will be assumed to have been PAID in full.

**Note:** Any Transactions migrated to Subscribe will follow your defined retry sequence. For example, an `AutoBill` migrated to Subscribe with a single `Transaction` with status `Cancelled` will trigger a retry.

*cancelReason*: (Optional) reason for canceling the AutoBill. You can use predefined Subscribe cancel reason codes, or define additional codes using the Subscribe Portal or the API. (See Canceling AutoBills with Reason Codes in the Subscribe Programmer’s Guide.) Supplying an undefined cancel reason code may result in an error.

## Output

*return*: an object of type `Return` that indicates the success or failure of the call.

*autobill*: the `AutoBill` object that was created through migration. If you specify a VID or for *autobill*, and that ID does not yet exist in the Subscribe database, this method will create a new `AutoBill` object. If the ID does exist, Subscribe will update the corresponding `AutoBill` object.

## Returns

In addition to those listed in [The Return Object](The_Return_Object), this call returns:

| Return Code | Return String |
| - | - |
| `400` | One of the following: - `At least one migrationTransaction must be included in AutoBill.migrate request.` - `Error validating parameters for AutoBill Migration.` - `Migrated AutoBills must have at least one item.` - `Product must be pre-defined for *AutoBillItem*.` - `Product not defined for AutoBillItem *autoBillItem*.` - `Invalid AutoBillItem addedDate *date*.` - `Invalid AutoBillItem removedDate: *date*.` - `BillingPlan must be pre-defined.` - `BillingPlan with identifier *identifier* not found.` - `Campaign code *campaignCode* is not valid.` - `Invalid value for transitionedFromMerchantAutoBillItemId: *autoBillItemId*.` - `Invalid value for transitionedToMerchantAutoBillItemId: *autoBillItemId*.` - `Invalid value for nextPeriodStartDate.` - `Transaction Migration attempt failed: *error*.` (See the `Transaction.migrate` error list for details that could be appended to this message.) - `Migration Transactions not specified.` - `PaymentMethod not specified.` - `Unsupported Payment Type: *type*.` - `TransactionBilling migration details not provided for initialization of AutoBill.` - `No BillingPlan: Cannot determine TransactionBillingSequence details.` - `Billing Plan on last Transaction submitted does not match AutoBill BillingPlan.` - `AutoBillCycle (transaction_billing_sequence) not defined.` - `Unable to determine current AutoBill BillingPlanPeriod.` - `Unable to determine Billing Period billing sequence.Failed to determine BillingPlanPeriod index for AutoBill Migration.` - `BillingPlanCycle cannot be greater than autoBillCycle (transaction_billing_sequence).` - `Currency code not defined in row *n* of Transaction Array for AutoBill Migration.` - `Transaction currency (*currency*) does not match AutoBill currency (*currency*).` - `Transaction for retry # *n* in billing sequence *m* already exists.` - `Transaction migration failed for Transaction # *n* during Migration of AutoBill *autoBill*.` (See the `Transaction.migrate`error list for details that could be appended to this message.) - `Mismatch found between AutoBill billing sequence (*n*), and the max TransactionBilling sequence (*m*).` - `Transactions cannot be associated with an AutoBill's final TransactionBilling.` - `TransactionBilling for sequence *sequence* is in invalid state *state*() for AutoBill migration.` (TransactionBillings generated by the migrate process should be in one of the following states: Success, Free, or Deferred.) - `Original activity date for historical TransactionBilling sequence *n* is in the future (*date*).` - `billing date for TransactionBilling (*date*) is greater than latest allowed (*date*).` - `Transaction (*index*) in sequence *sequence* is in an invalid state (*state*) for AutoBill migration.` (The Transaction state (which is derived from the disposition log) must be one of the following: Captured, Cancelled, Refunded, Settled, or Void.) - `NRC Transaction in sequence $sequence is in an invalid state (*state*) for AutoBill migration` (Non-Recurring-Charge Transactions must be in one of the states specified for Recurring Transactions (above).) - `Transaction autoBillCycle not defined.` - `billingPlanCycle not defined.` - `billingPeriodStart not defined.` - `Failed to map AutoBill Items to Transaction Items during Transaction Migration.` - `Cannot map Transaction Items to AutoBill Items - No Transaction Items!` - `Cannot map Transaction Items to AutoBill Items - No AutoBill Items!` - `Failed to determine Product SKU for AutoBill Item index *n* while attempting to map Transaction Items to AutoBill Items.` - `Failed to map AutoBillItem ID *autoBillItemId*, to a TransactionItem.` - `Unable to determine AutoBill BillingPlanPeriod for Transaction ident *transactionId*.` - `Unable to determine Billing Period billing sequence for Transaction ident *transactionId*.` - `Failed to determine BillingPlanPeriod index associated with Transaction ident *transactionId*.` |
| `400` (Transaction migration error messages) | - `MigrationTransaction not provided.` - `Invalid paymentProcessor: *paymentProcessor*.` - `MigrationTransaction must include at least one statusLog record.` - `Failed to convert salesTaxAddress.` - `Attempt to migrate Transaction which already exists.` - `Unsupported Payment Type: *paymentType*.` - `Failed to prepare auth_response for Migrated Transactions.` - `Unable to determine currency for migrated Transaction.` - `Calculated Transaction amount (*XXX.XX*) does not match input amount (*YYY.YY*) on migrated Transaction.` |

## Example

```

//To migrate an AutoBill for a pre-existing BillingPlan, 
//Product, Account, and PaymentMethod.
//Note that it is possible to define new Account and 
//PaymentMethod objects within AutoBill.migrate.
//The Product(s) and BillingPlan must, however, be pre-defined.
$billplanVid = 'c6743226ea41afd9db71c0c612a870bfcaa68fa7';
$productVid = '124a5540e359d59ba2a301a4b86cd5434f5c99d3';
$accountVid = '3915038987280cc31b103dbdf291cfd68181b385';
$paymentmethodVid = '822690237671dbb37014bb4c5262e0067ab94f97';
$addressVid = '3c14d744baa5cd618c1e0ff2c1f54b408e8c65e9';
$billPlan = new BillingPlan();
$product = new Product();
$account = new Account();
$autobill = new AutoBill();
$paymentMethod = new PaymentMethod();
$address = new Address();
$billPlan->setVid($billplanVid);
$product->setVid($productVid);
$account->setVid($accountVid);
$paymentMethod->setVid($paymentmethodVid);
$address->setVid($addressVid);
//Define the AutoBill to be Migrated
$item = new AutoBillItem();
$item->setIndex(0);
$item->setAddedDate('2014-01-06T10:14:14-08:00');
$item->setMerchantAutoBillItemId('merchantAutoBillItem1391710456');
$item->setProduct($product);
$autobill->setaccount($account);
$autobill->setItems(array($item));
$autobill->setBillingPlan($billPlan);
$autobill->currency('USD');
$autobill->setCustomerAutoBillName('MGRT_1391710573_cabn_1391710456');
$autobill->set('MGRT_1391710573_valg_1391710456');
$autobill->setPaymentMethod($paymentMethod);
$autobill->setStartTimestamp('2014-01-06T10:14:14-08:00');
//Next, define the MigrationTransaction to be included 
//in the AutoBill.migrate call
$taxItemA = new MigrationTaxItem();
$taxItemA->setAmount(.92);
$taxItemA->setJurisdiction('COUNTY_19');
$taxItemA->setName('SALES TAX');
$taxItemB = new MigrationTaxItem();
$taxItemB->setAmount(6.67);
$taxItemB->setJurisdiction('DISTRICT');
$taxItemB->setName('CA DISTRICT SALES TAX');
$txItemA = new MigrationTransactionItem();
$txItemA->setItemType('RecurringCharge');
$txItemA->setMigrationTaxItems(array($taxItemA, $taxItemB));
$txItemA->setName('product 1391710450 default plan');
$txItemA->setPrice(49.99);
$txItemA->setServicePeriodStartDate('2014-01-06T00:00:00');
$txItemA->setServicePeriodEndDate('2014-03-05T00:00:00');
$txItemA->setSku('bp_1391710450');
$txItemA->setTaxClassification('DC010500'); 
   // This should be the Avalara tax code associated with this product
$txItemB = new MigrationTransactionItem();
$txItemB->setItemType('RecurringCharge');
$txItemB->setMerchantAutoBillItemId('merchantAutoBillItem1391710456');
$txItemB->setName('product_1391710450_1');
$txItemB->setPrice(42.00);
$txItemB->setServicePeriodStartDate('2014-01-06T00:00:00');
$txItemB->servicePeriodEndDate('2014-03-05T00:00:00');
$txItemB->setSku('1391710450_1');
$txItemB->setTaxClassification('DC010500');
   // This should be the Avalara tax code associated with this product
$creditCardStatusA = new TransactionStatusCreditCard();
$creditCardStatusA->setAuthCode('000');
$statusLogA = new TransactionStatus();
$statusLogA->setCreditCardStatus($creditCardStatusA);
$statusLogA->setPaymentMethodType('CreditCard');
$statulLogA->setStatus('Captured')
$statusLogA->setTimestamp('2014-02-06T10:16:06-08:00');
$creditCardStatusB = new TransactionStatusCreditCard();
$creditCardStatusB->setAuthCode('000');
$statusLogB = new TransactionStatus();
$statusLogB->setCreditCardStatus($creditCardStatusB);
$statusLogB->setPaymentMethodType('CreditCard');
$statusLogB->setStatus('New');
$statusLogB->setTimestamp('2014-02-06T10:14:51-08:00');
$migrationTransaction = new MigrationTransaction();
$migrationTransaction->setAccount($account);
$migrationTransaction->setAmount(99.58);
$migrationTransaction->setAutoBillCycle(0);
$migrationTransaction->setBillingDate('2014-01-06T00:00:00');
$migrationTransaction->setBillingPlanCycle(0);
$migrationTransaction->setCurrency('USD');
$migrationTransaction->setDivisionNumber('iAmTheWalrus');
$migrationTransaction->setMerchantBillingPlanId('bp_1391710450');
$migrationTransaction->setMigrationTransactionItems
      (array($txItemA, $txItemB));
$migrationTransaction->setPaymentMethod($paymentMethod);
$migrationTransaction->setPaymentProcessor('Litle');
$migrationTransaction->setPaymentProcessorTransactionId('1069115');
$migrationTransaction->setRetryNumber(0);
$migrationTransaction->setSalesTaxAddress($address);
$migrationTransaction->setShippingAddress($address);
$migrationTransaction->setStatusLog(array($statusLogA, $statusLogB));
$migrationTransaction->setType(Recurring);
//Migrate AutoBill into Subscribe
$response = $autobill->migrate('2014-03-06T00:00:00', 
array($migrationTransaction));
if($response['returnCode'] == 200)
{
   //AutoBill and Transaction(s) migrated successfully
   print "AutoBill migrated with VID " .
   $response['data']->autobill->getVID() . "\n";
}
else
{
   //AutoBill migration failed
}
```

**Parent topic:**[AutoBill Methods](../topics/AutoBill_Methods)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.