Data Flows

Understand the core entities you’ll be working with as well as the typical flows of data involved in a seller focused integration.

11 minute read

What you’ll learn

In this section we’ll cover the following topics:

The core entities of the Marketplacer platform
The core data flows involved in a seller integration
The core relationships between data entities

Core Entities

Marketplacer is a large product, composed of many entities, so to describe them all here in detail would be counter to the nature of this playbook. Instead, we will focus on the core (or primary) entities that will be of interest to you when integrating into Marketplacer as a seller.

🛰️ A full schema is exposed for you to explore via GraphQL Voyager

The table below describes the core entities we’ll be discussing further in this guide:

Entity	Alias	Purpose	Context
Advert	Product	Primary container for Products that a Seller wishes to sell on the marketplace. These products would be referred to as 3rd party products when sold alongside an operator’s own 1st party products.	Products
Variant		Describes how the Advert can vary, e.g. different sizes or colors. An Advert must always have at least 1 variant. It is at the variant level where attributes such as: SKU, Bar code, Inventory are located, and ultimately it is the variant that is purchased by the customer.	Products
Order		An Order is the “marketplace-level” object that acts as the container for a customer’s entire purchase. An Order in Marketplacer will always have at least 1 Invoice attached to it, (1 invoice per seller) NOTE: The Order is not exposed to the Seller given that an order can contain information related to other sellers. However information required by the seller, such as shipment address, will be made available via the Invoice entity.	Orders
Invoice	Order	An Invoice is the part of the overall customer order that an individual Seller has to fulfil. An Order will always have at least 1 Invoice (1 Invoice per Seller participating in the Order). From a Sellers perspective the Invoice is the Order.	Orders
Line Item		Line Items represent the products purchased by the customer. Line Items have a direct line of sight back to the Variant. I.e. When a variant is purchased it is then represented as a Line Item. Line Items are attached to both the Order and the Invoice.	Orders
Refund Request		A Refund Request models the stages that both Cancellation (pre-dispatch) and Refund (post-dispatch) requests go through. A successful Refund Request will result in an Invoice Amendment.	Orders
Invoice Amendment	Refund	Represents an adjustment to an Invoice. Usually generated after a successful Cancellation or Refund Request.	Orders
Shipment		Represents the dispatch of 1 or more Line Items, Sellers are typically responsible for the creation of shipments.	Shipments
Shipped Item		You can choose to split shipments, so either individual line items on an Invoice, or even specific quantities of the same line item. This is represented by a Shipped Item	Shipments
Seller	Retailers	Sellers are 1 of the primary participants on the marketplace and are responsible for the listing of (3rd party) products for sale.	Sellers
Remittance		The marketplace operator is responsible for taking payment for orders, remembering that orders can be composed of products from multiple sellers. This is referred to as the Merchant of Record. At some point however the Sellers participating in marketplacer orders will need to be paid (by the marketplace operator), this payment is referred to as a Remittance.	Sellers
Taxon	Category	Represents where the product sits in the categorization hierarchy, e.g. Computers -> Storage -> SSH Hard Drives. In this example we have 3 Taxons, with Parent / Child relationships between each.	Categorization
Option Type	Attribute	Option Types refer to the way an Advert or Variant can be defined. So common Option Types would be color and Size. Option Types will then have 1 or move Option Values, which contain the range of values that it is possible for the Option Type to have.	Categorization
Option Value	Attribute Value	The values that an Option Type can have. In the example where we have an Option Type of Color, possible Option Values would be: Red, Green, Blue etc.	Categorization
Prototype	Attribute Profile or Group	Prototypes are the glue between a Taxon and the Option Types that Taxon has. So we assign Option Types to a Prototype, and then assign a Prototype to the Taxon. This means we can assign that same defined Prototype to any number of other Taxons.	Categorization

Data Flows

Let’s review the high-level end to end product / order flow for a typical Marketplacer instance:

Seller Integration Playbook

Sellers will list products on the marketplace
Seller products (aka 3rd Party Products) will need to flow through to the eCommerce platform
Customers will browse products on the front end (3rd party and possibly 1st party)
Customers will place an order on the eCommerce platform (payment is taken here)
Orders (for 3rd party products only) are passed through to Marketplacer
Sellers will pick up their orders and process

Seller Integration Context

For the purposes of this guide we are interested only in the direct interactions between Sellers and Marketplacer, this context is highlighted below:

Seller Integration Context

For an overview of the flows between Marketplacer and the Operator integration, you can refer to the Connected Integration Blueprint for operators.

This context can be expanded beyond products and orders to cover the other entities that you could expect to flow between a Seller Integration and Marketplacer:

Full Seller Context

NOTE: This list is not exhaustive, (e.g. it does not depict chat interactions that can occur between the seller and the operator), but for the purposes of this guide the entities depicted represent the vast majority of use-cases implemented in a typical seller integration.

With our high-level entity movements mapped out, let’s focus on each in more detail.

Provider Vs Consumer

For the remainder of this guide we’ll use the terms Provider and Consumer in relation to the movement of data. While these are fairly well used and understandable terms it’s worth just clarifying:

Provider: The source of data / where data is moving from.
Consumer: The target for the data / where data is moving to.

NOTE: This section elaborates the data movement use-cases, in the next section (Integration Points), we discuss the integration points (API & Webhook) that can be used to implement these use-cases.

Product Flows

Provider	Consumer	Use Case	Description
Seller	Marketplacer	Create a product	To sell products on the marketplace, you first need to create them!
Seller	Marketplacer	Update a product	Product updates will probably represent the vast majority of traffic volume for the integration. We have generically called this the Product Update use-case, but it could encapsulate different flavours of this scenario, including but not limited to: - General product updates - Pricing Updates - Inventory Updates - Products resubmitted for vetting - Products being taken off line
Seller	Marketplacer	Delete a product	No further explanation required.
Marketplacer	Seller	Get rejected products	When product vetting is enabled, operators can reject products that do not meet their requirements. In this case sellers will need to retrieve rejected products and rectify.

Order Flows

Note that we have included those flows related to refunds in this section.

Provider	Consumer	Use Case	Description
Marketplacer	Seller	Get new orders	Orders are placed by customers on the operators marketplace, these orders are then “split” into Invoices, (1 invoice per seller). Sellers can then retrieve their orders (invoices) from Marketplacer to action.
Marketplacer	Seller	Get updated orders	A seller may want to get updated orders, e.g. when a refund request is raised against an order that will result in an order update.
Seller	Marketplacer	Update an order	In the case of Click and Collect orders, a seller will need to update the order to reflect that: - The order is ready to collect -The order has been collected. Order dispatch (shipments) will be covered in that dedicated section.
Marketplacer	Seller	Get refund requests	Customers can cancel orders (pre-dispatch) or return orders (post-dispatch). If these refund requests originate via the marketplace frontend, then sellers will need a way to retrieve those requests and action accordingly.
Seller	Marketplacer	Create a refund request	In some instances (e.g. a seller realizing they have no stock), refund requests may originate from the seller.
Seller	Marketplacer	Update a refund request	The refunds workflow has a number of potential pathways, some of which require further input from the seller, e.g. choosing whether a product needs to be returned or not. In this case the seller has to update the refund request accordingly.

Shipment Flows

Provider	Consumer	Use Case	Description
Seller	Marketplacer	Create a shipment	Upon receipt of new orders, sellers will dispatch those orders that require shipment. NOTE: Sellers can create multiple (aka split) shipments against a single order (e.g. those with multi-line or multi-quantity line items).
Seller	Marketplacer	Update a shipment	A seller may want to update existing shipments, e.g. to change the tracking number for example.
Seller	Marketplacer	Create a return shipment	Where a refund request has been raised for an order, and those order items need to be returned to the seller, the seller can create a return shipment.
Seller	Marketplacer	Create a shipping rule	When shipping rules are being used, and an operator permits the use of seller-defined shipping rules, these can be created by the seller.
Seller	Marketplacer	Update a shipping rule	When shipping rules are being used, and an operator permits the use of seller-defined shipping rules, these can be updated by the seller.
Marketplacer	Seller	Get shipping profiles	When shipping rules are being used, sellers will need to attach the associated shipping profile to their product variants. This flow relates to the retrieval of that information from Marketplacer.

Categorization Flows

Provider	Consumer	Use Case	Description
Marketplacer	Seller	Get brands	If sellers are electing to create products in Marketplacer using Marketplacer reference Ids, then Brand data (along with their associated Ids) will need to be retrieved from Marketplacer.
Marketplacer	Seller	Get taxons	If sellers are electing to create products in Marketplacer using Marketplacer reference Ids, then Taxon (aka Category) data (along with their associated Ids) will need to be retrieved from Marketplacer.
Marketplacer	Seller	Get option types	If sellers are electing to create products in Marketplacer using Marketplacer reference Ids, then Option Type data (along with their associated Ids) will need to be retrieved from Marketplacer.
Marketplacer	Seller	Get option values	If sellers are electing to create products in Marketplacer using Marketplacer reference Ids, then Option Value data (along with their associated Ids) will need to be retrieved from Marketplacer.

Remittance Flows

Provider	Consumer	Use Case	Description
Marketplacer	Seller	Get remittances	When the operator pays the seller via a remittance, the seller may wish to retrieve that information from Marketplacer.