The Marketplace allows you to create and pay affiliates for your rate planes or subscriptions.
This is a basic schema of the entities involved in the marketplace and their relationships (in green the entities exclusive to the marketplace):
The Marketplace is meant to deal with two different basic scenarios, both of which ends with the same result.
In this scenario we are going to:
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:
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).
As we can see from the chart, this part is composed by 4 steps:
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.
This part is made of 3 steps:
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.
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:
This one step operation generates an invoice for every currency the affiliate has commissions for.
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.
This case also reckon on 4 steps, which are slightly different:
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.
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:
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.
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:
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:
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:
Stripe manages three different types of accounts:
managed accounts and
The main differences are:
Platformsare fully fledged accounts (they are proper accounts with user and password).
Managed accountsare accounts inside a platform account. They don't need a user and password.
Customersare 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:
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.
It is possible to download a report at any time for the affiliates across the whole organization by following this link:
It is also possible to specify the dates the report should be run across by adding two query parameters:
In both URLs:
todates following BillForward's time standard