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 amethod 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 (
AdvanceorArrears), informing Subscribe in which direction from the scheduled billing date to select the specified billing date. If nospecified_billing_dayis provided, this parameter is ignored.
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:
accountbillingPlancurrencyitemspaymentMethod(For this call, this field must beCreditCardor MAP)startTimestamp
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,Settledor 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 typeReturn 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.