action.skip

Best Practice: Marketplace

Generally, JustOn is set up to issue invoices to one recipient, usually via the account associated to the corresponding source record. Certain business use cases require billing to multiple parties, however – like, for example, in a marketplace scenario.

In a typical setup, the marketplace operator connects merchants (the providers of the traded products) and the buyers (the recipients of the products), processing all transactions between these players. Consequently, the marketplace operator bills the same products to multiple parties: they issue credits to merchants for payouts, and invoices to buyers to receive payments.

marketplace
Billing products to merchants and buyers

Irrespective of the marketplace itself – which is usually an e-commerce site – an implementation of this scenario with Salesforce and JustOn may be:

(1) Both merchants and buyers are represented as accounts.

(2) For every selling transaction between a merchant and a buyer, you create an order with order products attached.

Orders and order products are specifically prepared to be invoiced to merchants and buyers, applying different prices.

(3) You execute a generic invoice run that produces invoices from the orders for buyers to request the payment from them.

(4) You execute a generic invoice run to produce credits from the orders for merchants to indicate the payout to them.

(5) In addition, you can execute another generic invoice run to produce invoices for merchants to request a commission fee (which directly depends on the amount of the processed order) for your brokerage.

Setting up a marketplace scenario usually involves the following tasks:

Depending on your business, you may also have to configure multiple currency billing.

Once set up as outlined, you can execute multiple generic invoice runs – one for each filter in order to create individual invoices for the merchant and the buyer.

Info

Remember that this documentation describes one (of several possible) ways to implement this use case. The appropriate setup may vary depending on your individual business requirements.

Creating Target-Specific Controlling Fields

As explained in Billing Arbitrary Objects, the objects based on which invoices are built require a number of ON fields as controlling fields. To support multiple party billing, these source objects require individual, recipient-specific sets of these controlling fields in order to allocate the correct data to the different recipients. To this end, you add an individual suffix string to the controlling fields.

Info

Remember that with usage data billing, JustOn makes a distinction between controlling fields and data fields (see Fields on Custom Objects). When billing usage data to multiple parties, be aware that JustOn does not support suffixed data fields. To use recipient-specific data fields required for usage data billing, configure them individually on the recipient-specific items (subscription items).

Following the marketplace example, you use these target suffixes:

  • Merch to produce the merchant credits
  • Buy to produce the invoices for the buyers
  • Comm to produce the commission invoices for the merchants

Note

The suffix length must not exceed five characters.

  1. Navigate to the fields list of the source object.
  2. Create and configure the required controlling fields.

    Required target-specific fields on the Order object:

    Merchant Credit Buyer Invoice Merchant Commission
    ON_AccountMerch ON_AccountBuy ON_AccountComm
    ON_TemplateMerch ON_TemplateBuy ON_TemplateComm
    ON_ServiceDateMerch ON_ServiceDateBuy ON_ServiceDateComm
    ON_InvoiceMerch ON_InvoiceBuy ON_InvoiceComm
    ON_LastInvoiceRunMerch ON_LastInvoiceRunBuy ON_LastInvoiceRunComm
    ON_InvoiceBuildErrorMerch ON_InvoiceBuildErrorBuy ON_InvoiceBuildErrorComm

    Required target-specific fields on the Order Product object:

    Merchant Credit Buyer Invoice Merchant Commission
    ON_TitleMerch ON_TitleBuy ON_TitleComm
    ON_QuantityMerch ON_QuantityBuy ON_QuantityComm
    ON_UnitPriceMerch ON_UnitPriceBuy ON_UnitPriceComm

    For details about the fields required for the generic invoice run, see Configuring Parent Object and Configuring Source Object.

    Info

    You can add more fields using the ON field mechanism.

Configuring Price Calculation

Following the marketplace example, we want to produce

  • credits for the merchants to indicate the payout to them,
  • invoices for the buyers to request the payment from them, and
  • invoices for the merchants to request a commission fee.

To this end, you can configure the individual order product price fields as follows:

Field Data Type and Value Notes
ON_UnitPriceMerch Formula (Currency)
ListPrice * (-1)
Reverses the amount to produce a credit.
ON_UnitPriceBuy Formula (Currency)
ListPrice
Copies the defined list price to produce an invoice.
ON_UnitPriceComm Formula (Currency)
ListPrice * 0.1
Calculates a 10% commission to produce a commission invoice.

Creating Target-Specific Filters

To support multiple billing, you must configure target-specific filters. To this end, you add an individual suffix string to the filters – following the example, Merch, Buy and Comm.

Note

The suffix length must not exceed five characters.

  1. Click to enter Setup, then open Custom Settings.

    In Salesforce Lightning, navigate to Custom Code > Custom Settings.

    In Salesforce Classic, navigate to Develop > Custom Settings.

  2. Click Manage in the row of Filters.

  3. Create the filters as necessary.

    Field Filter Value for Merchant Credit Filter Value for Buyer Invoice Filter Value for Commission Invoice
    Name Merchant Buyer Commission
    Target Order Order Order
    Child Relation
    Plural form
    OrderItems OrderItems OrderItems
    Use Case Generic Generic Generic
    Transactional Suffix Merch Buy Comm

    For details about the filter for the generic invoice run, see Creating Invoice Run Filter. For details about filters in general, see Filters.

Configuring Target-Specific Templates

To completely support the marketplace scenario, you can configure target-specific invoice templates with individually configured texts or table definitions.

  1. Create and configure target-specific templates.

    Following the example, you need an individual template for

    • the merchant credit
    • the buyer invoice
    • the commission invoice
  2. For each template, specify the text field values and table configurations as required.

    For details about editing invoice templates, see Working With Templates.

Executing Invoice Run

Once set up as outlined, you can execute multiple generic invoice runs – one for each filter in order to create individual invoices for the merchant and the buyer:

  • Merch to produce the merchant credits
  • Buy to produce the invoices for the buyers
  • Comm to produce the commission invoices for the merchants
Propagating associated documents

During the generic invoice run, JustOn can link documents that are associated to (parent or child) source records with the resulting invoice record. If the file type is not excluded (using the field Email File Types on the template, see Modifying Invoice Email), the linked documents are then attached to the invoice upon distribution (emailing, etc.) and sent to the corresponding recipient.

To allow a fine-grained control over which (of possibly multiple) documents are linked with the invoice, the setting is made using a checkbox on document basis. If required by your business case, make sure that the intended documents are selected accordingly.

For details, see Propagating Associated Documents.

When selecting attachments, be aware of the email size limit imposed by Salesforce. If set up accordingly, the maximum size of one email is 25 MB, which includes the body, headers and attachments (see General email limits in the Salesforce Help). That is, an email with a 25 MB attachment will exceed this limit and would, consequently, not be processed.

To execute a generic invoice run:

  1. Open the Invoice Runs tab.
  2. Click New.
  3. Specify the configuration details as necessary.

    • Period Start/Period End: Specifies the period for the invoice run.
    • Invoice Date: Specifies the date of issue for all invoices. If left empty, JustOn will set the date when finalizing the invoice.
  4. Select the invoice run filter as required.

    If you use filter groups, select a filter group first in order to narrow down the number of available filters.

    To define which records to include in the invoice run, select one or more generic filters.

    Generic filters are presented as checkboxes. You can select multiple (or no) generic filters.

    ir_filters
    Selecting invoice run filters

  5. Click Start.

    This creates draft invoices from all accordingly configured objects that match the filter criteria.