Marketplace API Integration Guide

Transparency & Other Guides

This is a combined retailer/supplier guide intentionally so both parties transparently understand each other's integration requirements and responsibilities as success in e-commerce transactions is a two-party dance.

Overview

This guide explains how a partner, a retailer or supplier, would use Rithum's Dsco Platform APIs to integrate to Dsco whether doing a dropship integration or a marketplace integration.

This guide explains the work a partner, a retailer or supplier, would do to create a private marketplace integration using the Dsco Platform APIs. Note that by intent, the work a partner would do for a private marketplace is very similar to the work for a dropship integration. While there are meaningful differences between a private marketplace and dropship Dsco integration, the objects shared between you and your trading partners (order, inventory, etc.) are nearly identical.

Marketplace Work Summary

Marketplace requires partners do some things differently than for dropship. Here's an overview of the work that partners need to do that's specific to marketplace.

Retailer

To get the marketplace model working for suppliers to connect with a retailer's marketplace, a retailer must...

To get the marketplace model working for suppliers to connect with a retailer's marketplace, a retailer may...

Supplier

To get the marketplace model working to connect with a retailer's marketplace, a supplier must...

To get the marketplace model working to connect with a retailer's marketplace, a supplier may have to...

Object Model Differences

The marketplace model uses the exact same object definitions for order, inventory, catalog, etc. that the dropship model uses, adding a few attributes on these objects specific to marketplace. It also introduces a few new objects. Here's a summary of these marketplace-specific attributes on core e-commerce objects and the few marketplace-specific objects. Each of these will be discussed in greater detail later.

Order Object

This object definition is shared across both dropship and marketplace orders with these additional marketplace-specific attributes.

Item Catalog Object

This object definition is shared across both dropship and marketplace orders with these additional marketplace-specific attributes.

Settlement Record Object

This is a new object that only applies to marketplace. It is a record of a financial transaction, an order line item, that is used to account for the moneys owed for a marketplace order line item.

Payment Object

This is a new object that only applies to marketplace. It is created by a retailer to associate a number of settlement records with a specific payment to a supplier.

Allocation Object

This is a new object that only applies to marketplace. It is the association of a given settlement record to a payment.

Promotion Object

This is a new object that only applies to marketplace. It is a supplier-created discount, agreed upon by the retailer with a handshake process, that applies to a set of items in a marketplace.

ShippingZoneDefinition Object

A shipping zone as defined in the Dsco platform. This is used in an item's shipProfile to delineate shipping information by zone.

Item Setup in a Private Marketplace

TODO: finish talking

Retailer Marketplace Work Details

We will now go through the same steps delineated in the Marketplace Work Summary above, filling in more details.

Catalog Setup

A retailer must choose if they will use Advanced Catalog to define their catalog taxonomy or not. Most retailers do choose to use this product because it enables fast supplier onboarding and item setup, removing many of the manual and error prone steps that exist otherwise.

Retailers use the Advanced Catalog product to define all the requirements for content attribution of the items suppliers list within their private marketplace.

Due to the complexity of modeling a three dimensional catalog structure with its nested categories, retailers will often use the web application to define the catalog category structure with its required and optional attributes. However, a retailer may use the Update Catalog Attribution Large Batch API to post a two dimensional, file-based representation of its catalog. The format of the content of this file is defined in the Advanced Catalog Attribution File Format Guide.

Explicit or Inferred Marketplace Order Type

Retailers must decide how Dsco will know an order is a marketplace order. Retailers may explicitly set the orderType to marketplace when giving orders to Dsco to fulfill. Some retailers prefer to not change their order integration and don't want to set orderType on orders, preferring Dsco infer orderType. Retailers may use the Channel Overrides feature to set the active retailModels attribute on the items that they want associated with marketplace to dropship or marketplace specifically using the Update Channel Overrides API. The active retailModels is assumed to be dropship if not set by a retailer.

Then, when Dsco receives an order the system will lookup the retailer's active retailModels for each order item to know whether it's a marketplace or dropship order.

Of course, in both the explicit and implicit methods describe, Dsco will reject retailer-provided marketplace orders for items a supplier hasn't made available for marketplace orders.

Commission Management

Retailers must set the agreed upon commission percent Dsco is meant to use for marketplace order items. Dsco will use the commission percent to account for moneys owed to suppliers in settlement report records (below).

Retailers set the supplier agreed upon commission percent that is the basis of the financial accounting using the Set Commissions API or by using the web application by going to main menu in the web app and navigating to Settings -> General Settings -> Marketplace Nav Element and then click on the View Page button in the Commission region.

Commissions are set based on a set of precedence rules used to determine the commission percentage for a given item when an order is received. The actual commission percent used is saved in each order line item's commissionPercentage attribute. The system considers commission percentages in the following order, stopping and using the commission percentage as soon as one of the following rules are met:

Settlement and Payments

Retailers must make payments to suppliers and settle the financial transactions each fulfilled order line item represents. As marketplace orders come into the system, an entry is made in the Marketplace Settlement Report for each line item. Initially, these items are in the incomplete status meaning that the line item is not entirely shipped or canceled yet. Once a supplier ships or cancels all quantity of a line item, it moves to the complete status.

Each complete order line item record in the settlement report records the transaction and the financial implications that ensue.

These transactions accrue. Retailers and suppliers use the Get Settlement Records API to find transactions in the report.

A payment is an accounting of money paid to a supplier for entries in the settlement report. A payment may be made either by a retailer or by the system itself to account for a returned item. The settlement report records associated with a payment are referred to as allocations.

Retailers may either designate which settlement report records are part of the payment when creating the payment by providing the list of allocations or after the fact using the Allocate Payment API.

Specifically, retailers will allow unallocated settlement report records to accrue and then after a period of time, the retailer uses the Create Payment API to mark which records in the settlement report are part of the payment. A payment is between exactly one retailer and one supplier, thus in this case the retailer created payment may only include settlement report records for a single supplier's order line items. The payment must also include the ID that correlates this payment back to the retailer's back office system called transactionId as well as the total amount of the payment. The system will validate that the amount of the payment correlates with the settlement report records associated with the payment.

Either party involved in the payment, the retailer or the supplier, may call the Get Payments API to retrieve payments.

As mentioned previously, the system may create a payment to account for the need to debit some part of an order that was returned. The system will create these debit payments with a transactionType of return.
Retailers will periodically call the Get Payments API searching for these debit payments created by the system as a result of a return who must then call the Allocate Payment API to account for how the money in question will be withheld.

Customer Care

Retailers may choose to require suppliers to respond to direct end consumer inquiries and complaints. Please reference the Customer Care Integration Guide for more information.

Supplier Marketplace Work Details

We will now go through the same steps delineated in the Marketplace Work Summary above, filling in more details.

Marketplace Item Selection

The supplier must mark which items are available for use in a private marketplace. The supplier uses the Item Catalog's retailModelRules.allowedModels to designate which retail models apply to the item. By default, all items are available for use in the dropship model. Suppliers must add marketplace on each item they wish to use in a private marketplace. If this attribute is provided and the item is meant to be traded in both a private marketplace and in a dropship model then the supplier most designate this by providing both marketplace and dropship in the array for the retailModelRules.allowedModels attribute.

Note that in the near future, suppliers will be able to designate that all items in their account are meant to be available for inclusion in a private marketplace so they don't have to do this item by item.

Marketplace Item Price

Suppliers must provide the marketplace price that retailers will use for an item in the marketplace.

Suppliers must set a listing price for each currency they mean to sell the item within for a private marketplace. Suppliers set this value for each Item Catalog object in the listingPrices.<currency-code> attribute. The currency code is a ISO 4217 3 digit value. For example, the following sets the private marketplace listing price to 20 US dollars and also 18 UK pounds.

{
    "listingPrices": {
        "USD": 20.00,
        "GBP": 18.00
    }
}

Marketplace Item Shipping Profiles

Suppliers must populate the shipProfile for each marketplace item that delineates the supported shipment information by geographical zone. The zones supported by Dsco may be retrieved using the Get Shipping Zone Definitions API.

Here's the structure of shipProfile on an item.

  "shipProfile": {
    "profileId": "string",
    "profileName": "string",
    "zones": [
      {
        "zoneId": "string",
        "rateName": "string",
        "description": "string",
        "rates": [
        {
          "rateId": "string",
          "rateName": "string",
          "leadTime": "string",
          "transitTime": "string",
          "weightClasses": [
            {
              "minValue": 0,
              "maxValue": 0,
              "cost": 0,
              "currency": "string",
              "unit": "string",
              "default": true
            }
          ]
        }
      ]
    }
  ]
}

See the Shipping Zones & Rates Guide for more information.

Settlement and Payments

Suppliers are encouraged to use the Get Settlement Records API to understand Dsco's accounting of marketplace transactions.
Suppliers may call the Get Payments API to reconcile payments made to the supplier with the corresponding allocated order line item transactions. Note that returns are handled essentially as a chargeback debit payment. Please read the corresponding Retailer Settlement and Payments section for more details on all of this.

Item Content via Advanced Catalog

Most retailers will use Advanced Catalog meaning that suppliers must provide item content for each marketplace item in compliance with the retailer's category rules in order for an item to be listed on a retailer's marketplace.

Promotions

Suppliers may use the Create Promotion API to create a promotion. Retailers will approve or reject the promotion. Both parties may retrieve promotions using the Get Promotions API.

Customer Care

Some retailers will require that suppliers respond to direct inquiries and complaints from end consumers. Please reference the Customer Care Integration Guide for more information

© 2024 Rithum Holdings, Inc., together with its subsidiaries, all rights reserved, protected under U.S. and international copyright law. Rithum and the Rithum logo are trademarks of Rithum, LLC