Marketplace Overview

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

Entities

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

• Customer Accounts
• Affiliate Accounts: Receive a payout when a customer invoice is paid. These are the same as standard accounts, but allow the receipt of 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 define the payout amount any affiliate receives when a subscription is paid by the customer (e.g. 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: When issued this invoice type will state the commission charges an affiliate has earned. Paying this invoices means the organization has sent the money to the affiliate.

Flow

The Marketplace deals with two different scenarios.

Scenario #1: 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

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

To set up 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 working via UI.

The diagram below shows a request made by the UI to the RestAPI, which can be used by any developer to integrate with the flow.

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 sccount. 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. A commission structure, for instance, could state: “This affiliate is going to get 10% every time a customer is pays an invoice on 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 automated and starts as soon as an invoice is generated and paid by the customer (which could be via credit card or offline payment). The following diagram demonstrates a case when a billing period ends, an invoice is issued then paid immediately.

This part is made of 3 steps:

1. An invoice is generated for the customer account for the subscription they are subscribed to.
2. The invoice is paid automatically (e.g. via Stripe payment).
3. At this point BillForward checks if there are any affiliates that have a commission structure linked to the invoice’s rate plan.

If this is the case the affiliate account has a commission charge stored against its account. At this point the money amount owed to the affiliate is stored but not paid out to the affiliate.

Part 3: Invoicing the payout

In this third and final 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.

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

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

Scenario #2: Commission against a subscription

Scenario #2 is similar to scenario #1. The only difference how the affiliate is linked via the commission structure. The example in the diagram above, when Account 1 pays an invoice for Subscription 1 no commission is recorded because the commission structure is linked to Subscription 2 not to the rate plan. When Account 2 pays an invoice for Subscription 2, the Affiliate will receive an affiliate charge, because in this case the commission structure is linked to Subscription 2 .

This case has four steps:

1. create_customer_account(): 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 considerations 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. A commission structure, for instance, could state: “This affiliate is going to receive 10% of every invoice paid against this subscription”.

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

Special case: Fallback mechanic

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

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 1 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 1 is going to benefit only from one commission structure at the time of each single paid subscription. Even if Subscription 2 is linked to both commission structures (10% of and fixed 5$), the commission structure linked to the subscription takes precedence.

Paying out an affiliate invoice

An affiliate invoice can be created 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 occurs outside the BillForward platform (e.g. a bank cheque). This kind of payment can be added via the UI using Add offline payment button on the invoice page:

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 basic accounts. They are similar to managed accounts, but do not include certain features, such as receiving payments.

In 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 (e.g. in the form of Bank Account details) 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 to the affiliate payment method.

Reports

It is possible to download a report, at any time, for all 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