Object Model

Advanced Billing organizes everything it bills against into a small number of core objects. The catalog holds what you sell; the customer holds who you sell it to; the subscription ties the two together and is where invoices, payments, and balances accumulate. Understanding how these objects nest is the fastest way to work out where a given record lives or which object an API call should target.

The diagram below shows the full model, and the same relationships are described in text underneath it, each marked as one-to-one or one-to-many.

Catalog objects

The catalog is the container for everything you sell.

• A catalog holds many product families.
• A product family holds many products, many components, many coupons, and many offers. Grouping these at the family level is what makes a component available to every product in the family.
• A product has many product price points, and a component has many component price points. Price points are what let you charge a different amount or a different frequency for the same product or component.
• An offer belongs to one product family and one product, and can point to a specific product price point. It packages that product together with components, each at a chosen price point and starting quantity, and with coupons applied as discounts. You can then present the whole bundle at signup.

Customer objects

The customer is the entity you bill.

• A customer has many custom fields and many payment profiles, one of which is the default.
• A customer has one hierarchy, and that hierarchy has many parent/child customer relationships. This is the structure that features such as WhoPays build on. A hierarchy can nest up to 10 levels deep.
• A customer has many subscriptions and many subscription groups.

Subscription objects

The subscription is where billing actually happens, and it carries the largest set of related objects.

• A subscription has one product and one product price point, and may carry many components and many coupons.
• A subscription has many transactions. A transaction is one of several kinds: a charge, a payment, a credit, or a refund. A payment has many refunds.
• A subscription has one account balance, which in turn has many prepayments and many service credits.
• A subscription has many invoices, one invoice preview, and many proforma invoices.
• A subscription bills against one payment profile.
• A subscription has many custom fields.

Subscription group objects

A subscription group mirrors the subscription's structure, but applies it at the group level. That is what allows several subscriptions to bill on one document.

• A subscription group contains many subscriptions, one of which is the primary member.
• At the group level, transactions, payments, refunds, credits, account balance, prepayments, service credits, and payment profiles all follow the same relationships they do on an individual subscription.
• Where an individual subscription has invoices, a group has consolidated invoices, one consolidated invoice preview, and consolidated proforma invoices. These are issued on the primary group member's billing schedule.