Marketplace

The Marketplace allows you to create and pay affiliates for your rate planes or subscriptions.


Entities

This is a basic schema of the entities involved in the marketplace and their relationships (in green the entities exclusive to the marketplace):

model
  • Customer Accounts
  • Affiliate Accounts: Receive a payout when a customer invoice is paid. These are simple accounts which the only difference is that they are allowed to receive commission payments. Any account is considered to be an affiliate automatically as soon as it is linked to a Rate Plan or a Subscription via a Commission Structure.
  • Subscriptions
  • Product Rate Plans
  • Invoices
  • Commission Structures: These entities defines the amount of payout any affiliate gets when a subscription is paid by the customer (es: 10% of total value, 5$ fixed amount, etc.)
  • Commission Charges: these are special charges that states how much money an affiliate has accumulated. A commission charge is created each time an invoice is paid by a customer for a subscription an affiliate is linked to.
  • Affiliate Invoices: these special type of invoices, when issued do state the commission charges an affiliate has earned. Paying this invoices means the organization has sent the money to the affiliate.

Flow

The Marketplace is meant to deal with two different basic scenarios, both of which ends with the same result.

Main case scenario: Commission against a Rate Plan

In this scenario we are going to:

  • Create the necessary users
  • Create an affiliation between an affiliate and a rate plan
  • Generate the commission charges for an affiliate
  • Issue an affiliate invoice
  • Pay the affiliate invoice
Part 1: Set up the affiliation
Rate plan affiliateion

We are going to create an affiliation similar to the example in the picture above. The final result will link an affiliate account to a rate plan via a commission. Each time an invoice will be paid for that rate plan, the affiliate will be granted money. In the above example, each time Account 1 or Account 2 pay their invoices, Affiliate will receive an affiliation charge.

To set this use case we need to:

  • Create the necessary users
  • Create an affiliation between an affiliate and a rate plan

We are going to see the flow from the point of view of an admin of the organization setting up the data via the UI.

In the same graph are shown the request made by the UI to the RestAPI, which can be used by any developer to integrate with the flow (API Reference).

Flow - part 1

As we can see from the chart, this part is composed by 4 steps:

  1. create_customer_account(): in this first step a customer account is created. A customer account is a simple account. It will be subscribed to a rate plan later on.
  2. create_affiliate_account(): an affiliate account is a special account that can receive payouts. No special consideration are used when creating this account. At this stage, both the customer account and the affiliate account are basically the same (they represent two different individuals, but they are the same otherwise).
  3. add_commission($affiliate_account, $rate_plan): the affiliate account is linked to a rate plan via a commission structure. A commission structure states how much a specific affiliate is going to earn each time an invoice is paid of a certain rate plan. Basically a commission structure, for instance, could state something similar to: "This affiliate is going to get 10% every time a customer is going to pay an invoice for this rate plan".
  4. subscribe($customer_account, $rate_plan): the customer account is subscribed to the rate plan.
Part 2: Payout generation

This process is completely automatic and it starts as soon as an invoice is generated and paid by the customer (which could be via credit card as via credit or offline payment). For simplicity in the following graph we are demonstrating the case when a billing period ends and an invoice is issued and paid straight away.

Flow - part 2

This part is made of 3 steps:

  1. An invoice is generated for the customer account for the subscription he is subscribed to.
  2. The invoice is paid automatically with success (ie. via a Stripe payment).
  3. At this point the BillForward checks if there are any affiliates that have a commission structure that links them to the invoice's rate plan.

If the data has been set up as in part 1, now the affiliate account has a commission charge stored against its account. At this point the money amount owe to the affiliate is stored inside a bucket and has not been paid out to che affiliate yet.

Part 3: Invoicing the payout

In this third and last step we are going to generate the affiliate invoice.

The generation of an affiliate invoice can be triggered manually or automatically at the end of the payout period (end of each month). Each time an affiliate invoice is generated for an affiliate, his buckets containing the owe money are emptied.

Generating the affiliate invoice can be easily achieved manually following this step:

Flow - part 3

This one step operation generates an invoice for every currency the affiliate has commissions for.

Alternative scenario: Commission against a subscription

Rate plan affiliateion

This use case is really similar to the main one. The only difference is to what is the affiliate linked to via the commission structure. In the example showed in the above image, each time Account 2 pays an invoice for Subscription 2, the Affiliate will receive an affiliate charge. This is not true when Account 1 pays his subscription.

Alternative Flow - part 1

This case also reckon on 4 steps, which are slightly different:

  1. create_customer_account(): in this first step a customer account is created. A customer account is a simple account. It will be subscribed to a rate plan later on.
  2. create_affiliate_account(): an affiliate account is a special account that can receive payouts. No special consideration are used when creating this account. At this stage, both the customer account and the affiliate account are basically the same (they represent two different individuals, but they are the same otherwise).
  3. subscribe($customer_account, $rate_plan): the customer account is subscribed to the rate plan.
  4. add_commission($affiliate_account, $subscription): the affiliate account is linked to a subscription via a commission structure. A commission structure states how much a specific affiliate is going to earn each time an invoice is paid of a certain subscription. Basically a commission structure, for instance, could state something similar to: "This affiliate is going to get 10% every time a customer is going to pay an invoice for this subscription".

This use case deals with subscription instead of rate plans. In this case, the affiliate will get his commissions only if a specific subscription is going to be paid.

Special case: Fallback mechanic

Rate plan affiliateion

What happens if at any time an affiliate is linked via a commission structure to both a subscription and a rate plan like in the above example?

In this case the commission structure at subscription level take precedence. In the above example, if both Account 1 and Account 2 pay their invoices, Affiliate is going to benefit:

  • fixed 5$ from the subscription paid by Account 1
  • 10% of the subscription paid by Account 2

Please notice that Affiliate is going to benefice only from one commission structure at the time for each single paid subscription. Even if Subscription 2 in theory is linked contemporary to both commission structures (10% of and fixed 5$), the commission structure linked to the subscription take always precedence.


Paying out an affiliate invoice

An affiliate invoice can be crated manually or automatically at the end of each payout period (at the end of the month).

The affiliate invoices are special invoices, which are not paid by the owner account, but are paid by the organization to the affiliate. For this reason, they cannot be paid using the traditional payment methods stored against an account. There are two ways to pay an affiliate invoice currently implemented in BillForward:

  • Via an Offline Payment
  • Via Stripe (currently WIP)

Offline payments

An offline payment is a payment that happens outside the BillForward platform (ie. a bank check). This kind of payment is easily achievable via the UI by the simple press of the Add offline payment button:

Add offline payment

Payments via Stripe

BEWARE: this feature is still Work In Progress and it could differ widely from the final implementation

It is possible to pay the affiliates' payout using stripe Connect feature:

https://stripe.com/docs/connect

Add payout method

Stripe manages three different types of accounts: customers, managed accounts and platforms.

The main differences are:

  • Platforms are fully fledged accounts (they are proper accounts with user and password).
  • Managed accounts are accounts inside a platform account. They don't need a user and password.
  • Customers are a really simple kind of account. They are similar to managed accounts, but are not allowed some features, like receiving payments.

Given BillForward's model:

  • BF Organizations are Stripe platforms
  • BF Affiliate Accounts are Stripe managed accounts
  • BF Customer Accounts are Stripe customers

Before an organization is able to send money to an affiliate it has to set a payout method to the affiliate (in the form of a Bank Account details for instance) which can be done via BillForward's UI. Since each affiliate account has to have a corresponding managed account on Stripe, when a payout method is added to an affiliate, BillForward creates under the organization's Stripe platform a managed account for the affiliate automatically. Stripe also require an identity verification process (KYC) before allowing anybody to send money to its managed accounts, because of that, BillForward requires a scan of a document (ie. Passport) while creating a payout method on stripe.

At this point, each time an affiliate invoice is paid, Stripe will start a transaction from the organization's to the affiliate payment method.


Reports

It is possible to download a report at any time for the affiliates across the whole organization by following this link:

https://api.billforward.net:443/v1/reports/affiliate/overview.csv?organizations=$ORGANIZATION_ID&access_token=$ACCESS_TOKEN

It is also possible to specify the dates the report should be run across by adding two query parameters:

https://api.billforward.net:443/v1/reports/affiliate/overview.csv?recognition_start=$FROM_DATE&recognition_end=$TO_DATE&organizations=$ORGANIZATION_ID&access_token=$ACCESS_TOKEN

In both URLs:

  • $ORGANIZATION_ID is the organization ID
  • $ACCESS_TOKEN is the access token
  • $FROM_DATE and $TO_DATE are the from and to dates following BillForward's time standard