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 support@chargify.com 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 support@chargify.com 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

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.

Create Ad Hoc Invoice

This endpoint creates a one-time invoice, and optionally attempts to bill the invoice to the payment method on file. If the payment is successful, the response returns an invoice `status` of `paid`. If the payment fails, the response returns an invoice `status` of `banished`.

Example JSON:

{
  "invoice": {
    "line_items": [
    {
      "title": "One time charge",
      "quantity": 1,
      "unit_price": "150.00"
    }
  ],
  "collection_method": "automatic",
 "issue_invoice_on_failed_payment": false
  }
}

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.
Was this article helpful?
0 out of 0 found this helpful