Migrate to Relationship Invoicing

Chargify’s Relationship Invoicing Architecture (RI), launched in 2018, provides customers with a reengineered set of billing, subscription, customer, and invoice capabilities. If you are an existing Chargify customer, prior to 2018, you use Chargify’s Statement Architecture (SA). You can now make the upgrade from SA to RI.

How to Migrate

1. Review & Explore
   1. Review this documentation to learn about RI. 
   2. Set up an RI test environment
      1. Log in to your Chargify Account > click Create New Site
      2. Under Select Your Site’s Bill Presentation > Relationship Invoicing > click Select > click Continue > enter the details > click Create Site
      3. Explore the changes
   3. As an alternative to the option above, you can contact [e-mail] with the subject line “RI Demo Site Request - Exploring RI Migration” and request an RI Demo Site with pre-populated data.
   4. Explore
2. Test your Chargify Integration/use of Chargify
   1. Clone your Statement Architecture live site (this will create a new test mode site). 
   2. In the newly created site, edit the site settings, and set Bill Presentation to “Relationship Invoicing”. Save the changes.
   3. In your newly created site, begin by going to Config > Settings > Invoices and configure your Invoice Settings (this is important, as we will use these settings during the migration process, so make sure you configure them like a production environment). 
   4. Test your existing Chargify integration/use of Chargify with the RI test environment. Your testing rule of thumb is simple: test every touch point you have with Chargify (UI and API). This is your most important step. Based on what you find, prepare the necessary changes.
3. Migrate
   1. Request the RI Migration - contact [e-mail] to get started. Be sure steps 1 and 2 above are completed before you make your request. Chargify will schedule the date/time of the Migration.
   2. Chargify Performs The Migration - See what to expect, in the During the Migration and After the Migration Section

Noteworthy New Features

Feature	About
Modern Invoices	Statements are replaced with Invoices
Invoice-centric Financial Activity	In Statement Architecture, all Financial Activity is Subscription-centric. In RI, all Financial Activity is Invoice-centric. Specifically: Payments, Refunds, Voids, Prepayments, Service Credits, Credit Notes.
Customer Hierarchies	Create Parent/Child Customers
Subscription Groups	Group multiple subscriptions together. This unlocks Consolidated Invoicing.
Consolidated Invoicing	Bill multiple subscriptions on a single invoice
Remittance Billing	Net terms Issue invoice in advance Proforma invoicing Remittance dunning
Ad Hoc Invoices	One time charges in Statement Architecture, are replaced with Ad Hoc Invoices.

 
UI Changes inside the Chargify App

Statement Architecture	Relationship Invoicing Architecture
Subscription-centric Financial Activity. One time charges Balance adjustments Refunds Deleting Payments The actions are performed on the Subscription level.	Invoice-centric Financial Activity. Payments Refunds Prepayments Service Credits Voids The actions are performed on the Invoice level, rather than the Subscription level.
Create One Time Charge	Create Ad Hoc Invoice and Apply Payment to the newly created Invoice
Increase Balance	Create Open Invoice
Decrease Balance	Create Service Credit
Issue Refund (on a Subscription)	Issue Refund (on the respective Invoice)
Delete Payment	Issue Refund for the Invoice, and then Void the Invoice
Pay Statement	Pay Invoice (choose to pay with payment method on file, prepayment, service credit, or external payment).

UI Changes for your End-Users

Category	Statement Architecture	Relationship Invoicing Architecture
Statements	Customers receive/view Statements	Customers receive/view Invoices
Statement Email	Customer receive a Statement Email (if enabled). Email uncustomizable.	Customers receive invoice email (if enabled). Email fully customizable.
Pay Online	If Customer pays invoice online, they are redirected to a single payment page.	A Customer can pay the invoice from the actual invoice.
Billing Portal	The Chargify Billing Portal lists Statements in a Statements Section	The Chargify Billing Portal lists Invoices in a Invoices Section

API Changes (Deprecated Endpoints)

Category	Statement Architecture (deprecated)	Relationship Invoicing
Legacy Invoices	GET /invoices/{invoice_id}	Read Invoice (Uses invoice uid. Example: inv_9g89bknwpvyvr)
Legacy Invoices	GET /invoices	List Invoices
Legacy Invoices	POST /invoices/{invoice_id}/payments This endpoint creates an external payment on an existing invoice	Create Payment on Invoice (set `type` to `external``) This records an external payment on an existing invoice
Legacy Invoices	POST /invoices/{invoice_id}/charges This endpoint is designed to add an unpaid line item to an existing invoice	Create an Ad Hoc Invoice (Ask Chargify Support to enable this api endpoint) This results in a new remittance invoice, with a status of `open`. The invoice can be paid as needed.
Legacy Invoices	POST /invoices/{invoice_id}/adjustments This endpoint creates a credit on an existing invoice	Step 1: Create Service Credit Step 2: Apply Service Credit  to Invoice (set `type` to `service_credit`)
Subscription Balance	POST /subscriptions/{subscription_id}/adjustments This endpoint adjusts a subscription’s balance, with a positive or negative number.	Create Service Credit This endpoint issues a service credit. For example, if you pass a value of `50`, the subscription has a service credit balance of $50. If the next invoice is $200, the service credit is used, and the invoice total will be $150. The invoice will denote the $50 service credit..
Subscription Balance	POST /subscriptions/{subscription_id}/charges This endpoint creates a one time charge on a subscription, attempting to bill the default payment method on file.	Coming soon. There is not yet an equivalent API endpoint. If necessary, you can use an alternative approach: Allocate to a one-time component. This endpoint charges the default payment method on file and generates an invoice.
Subscription Balance	POST /subscriptions/{subscription_id}/payments This endpoint records an external payment on a subscription.	Create Prepayment This endpoint creates a prepayment on a subscription. For example, if you pass a value of `50`, the subscription has a prepayment balance of $50. If the next invoice is $200, the prepayment is used, and the invoice total will be $150. The invoice will denote the $50 prepayment.
Subscription Balance	POST /subscriptions/{subscription_id}/refunds This endpoint issues a refund at the subscription level.	Create Refund on Invoice This endpoint issues a refund at the invoice level.
Subscription Balance	PUT  /subscriptions/{subscription_id}/reset_balance This endpoint resets a subscription’s balance to 0.	n/a
Creating Subscription	When creating an invoice subscription to POST /subscriptions, you set `payment_collection_method` to `invoice`	When creating a remittance subscription to POST /subscriptions, you set `payment_collection_method` to `remittance`

 

API Changes (Non-Deprecated Endpoints)

Statement Architecture	API Endpoint
Statements	GET /statements/{statement_id} GET /statements GET /subscriptions/{subscription_id}/statements GET /statements/ids GET /subscriptions/{subscription_id}/statements/ids GET /statements/count
Transactions	GET /transactions/{transaction_id} GET /transactions GET /subscriptions/{subscription_id}/transactions GET /transactions/count

 

Webhook Changes

Statement Architecture	Relationship Invoicing Architecture
statement_settled	The statement_settled webhook is deprecated. Use the invoice_issued webhook instead.
In all webhook payloads, the attribute balance_in_cents	RI uses multiple balance types (service credits, prepayments, etc). Use the Account Balances API Endpoint to read balances.

How does the Migration work?

Before the Migration

1. You test RI extensively.
   1. New UI workflows in Chargify (especially around balances)
   2. You test your Chargify API integration (if you have one). Ensure no currently leveraged API endpoints will be deprecated to prevent something breaking on the upgrade. See the API section for more information.
2. If your end-users currently receive statements, let them know their experience will be changing to prevent confusion.
3. Set invoice customization settings on a test RI instance - otherwise you will need to be ready to set your invoice customization settings post-migration.
4. You tell Chargify you want to migrate to RI, and you understand this is a permanent change. There is no going back. We assume all steps above to be true, and we schedule your migration, and let you know when it will occur.

During the Migration

1. Your renewals are delayed during the migration.
2. Any errors caught by the dev team will be remediated after the migration
   

After the Migration

Error Handling
After the Migration, there will be some standard remediation. We’ll help you through the process.

Error Message	Reason	How to Fix
Subscription balance does not match open provisional invoice balance.	The subscription has a balance. In RI, this balance could represent a Prepayment or Service Credit.	Our Migration Team will ask you if the balance represents a Prepayment or Service Credit, and apply the balance accordingly.

Remaining Items

1. Ask your Chargify CSM to regenerate your Revenue Recognition report.

 

FAQ

1. How long does the migration take?
   Times vary, primarily based on the number of Statements that need to be migrated. Large migrations tend to take up to 4-6 hours; small migrations less than an hour. This does not include any errors that occur. Errors are remediated after the migration is complete, and take more time since they are manual fixes. See the Error Handling section for common/anticipated errors.
   
   
2. Is it possible to switch back after the migration?
   No. This is a permanent change.
   
   
3. Can new customers signup while the migration is in progress?
   Yes.
   
   
4. Can my existing customers manage their subscriptions while the migration is in progress?
   Yes.
   
   
5. How long are renewals typically delayed for?
   This depends a lot on the volume of Subscriptions and volume of Statements your Chargify Site has. As an example, if a Site has 10,000 subscriptions and 150,000 statements, we would typically delay for 4 hours. 
   
   
6. As soon as the switch is complete, is all of the customer's new RI data ready to go?
   Yes, with the exception of any subscriptions that encounter errors. See the Error Handling section for common/anticipated errors.
   
   
7. Will the invoice numbers change if the customer previously had legacy invoices?
   Yes, we end up needing to issue new invoice numbers but we store a reference to the previous legacy invoice number on the invoice and display that in the UI so that the customer can reconcile the old and new numbers.
   
   
8. Can I accept new signups while the migration is running?
   Yes, but use common sense (eg: do not accept a large volume of signups at the same time the migration is running, as it increases the likelihood of errors). See Error Handling section for common/anticipated errors.
   
   
9. Are there any errors that can occur?
   Yes, and some errors are expected. See Error Handling section for common/anticipated errors. Overall, there is a near-100% success rate.
   
   
10. Are there any integrations that are affected?
    If you use Chargify’s QBO or Xero Integrations, there can be some errors in future syncs, only if you happen to use the new features service credits, prepayments, or voids in RI. In the near future, a more robust RI-focused QBO and Xero integrations will be introduced.