Integration Points

Understand how you can integrate into Marketplacer to facilitate the flow of data in a Seller Integration.

5 minute read

What you’ll learn

In this section you’ll learn about:

The integration points available to you when building a seller-based integration into Marketplacer
The specific integration points that can be mapped to each data flow (from the previous section)

Integration Points

As a Seller or Channel Manager you can use the following to build out an integration solution:

Integration Point	Description	Full Solution Build
Seller API	Strategic API solution for Sellers, utilizes the GraphQL API design pattern	Yes - you could build a full solution using just this API.
Legacy Seller API	Legacy API solution for Sellers, utilizes the REST API design pattern. Not to be used for new build solutions.	No - this API does not support newer features used by most operators, e.g. retrieving adverts rejected by vetting. Aside from any necessary supporting patches, this API does not receive product updates.
Webhooks	Event driven solution that allows for the “push” of data updates from Marketplacer	No - data is unidirectional (from Marketplacer to Seller), so you would still be reliant on the API to facilitate the movement of data from the Seller to Marketplacer, e.g. Product Creation. In short webhooks would be used in concert with the Seller API.

Documentation

The Seller API and Webhooks are fully discussed in the Documentation section of this site. For the most part this guide will point you to resources in that section. We also offer a set of seller-focused videos exploring concepts related to the API and Webhooks.

API Vs Webhooks

As indicated above, you could use the Seller API to build a full solution, (without resorting to using webhooks), so why use webhooks?

The answer to that is of course up to the individual integrator and their associated requirements and constraints, but generally speaking webhooks would be used when you want to receive event-based updates related to entities, as opposed to using API retrieval (and possibly polling for high cadence updates).

Example

Looking back at the Order Flows, arguably the key data flow here is the retrieval of orders (aka invoices) from Marketplacer. As an integrator building into Marketplacer you could achieve this using the following methods:

Method	Description	Further Reading
Seller API ( Data is pulled)	Use the invoices query to retrieve invoices at a regular cadence.	- API Docs - Video - Code
Webhooks (Data is pushed)	Use the invoices webhook to receive created and updated events on invoices	- Webhooks - Video - Code

There are of course other use-cases to consider when it comes to whether you want to use webhooks over the API.

Points to consider

If using the API to pull data, you will need to determine an acceptable cadence for that retrieval. This will be largely dependent on the nature of the data, and your business processes.
If using webhooks you will need to set up an accessible HTTP POST endpoint for Marketplacer to send data to.
If using webhooks and you expect to experience high traffic volumes, your end point will need to be tuned for that

A full API-based solution is (in most cases) simpler to implement than one that combines API calls and Webhooks. However the decision on which approach to take should (as usual) be driven by your business requirements and constraints.

Methods Mapped to Flows

In this section we revisit the Data Flows we identified in the prior section, and map the available integration points that could be used to facilitate the movement of data.

Product Flows

Let’s remind ourselves of the classes of data involved in the product flows:

Product Flows

Provider	Consumer	Use Case	Seller API	Webhooks
Seller	Marketplacer	Create a product	`advertUpsert`	N/a
Seller	Marketplacer	Update a product	`advertUpsert` `variantUpdate`	N/a*
Seller	Marketplacer	Delete a product	`advertDelete`	N/a
Marketplacer	Seller	Get rejected products	`advertsWhere`	N/a

Further Viewing

🎥 Product Flow Videos

Order Flows

Let’s remind ourselves of the classes of data involved in the order flows:

Order Flows

Provider	Consumer	Use Case	Seller API	Webhooks
Marketplacer	Seller	Get new orders	`invoices`	`Invoice (Create)`
Marketplacer	Seller	Get updated orders	`invoices`	`Invoice (Update)`
Seller	Marketplacer	Update an order	`clickAndCollectStatusUpdate`	N/a
Marketplacer	Seller	Get refund requests	`updatedRefundRequests`	`RefundRequest (Update)`
Seller	Marketplacer	Create a refund request	`refundRequestCreate`	N/a
Seller	Marketplacer	Update a refund request	`refundRequestLineItemReturn` `refundRequestLineItemAccept`	N/a

Further Viewing

🎥 Order Flow Videos
🎥 Refund Flow Videos

Shipment Flows

Let’s remind ourselves of the classes of data involved in the shipment flows:

Shipment Flows

Provider	Consumer	Use Case	Seller API	Webhooks
Seller	Marketplacer	Create a shipment	`shipmentCreate`	N/a
Seller	Marketplacer	Update a shipment	`shipmentUpdate`	N/a
Seller	Marketplacer	Create a return shipment	`returnShipmentCreate`	N/a
Seller	Marketplacer	Create a shipping rule	`shippingZoneCreateOrUpdate` `shippingRateCreateOrUpdate` `shippingOptionUpsert`	N/a
Seller	Marketplacer	Update a shipping rule	`shippingZoneCreateOrUpdate` `shippingRateCreateOrUpdate` `shippingOptionUpsert`	N/a
Marketplacer	Seller	Get shipping profiles	`shippingProfiles`	N/a

Further Viewing

🎥 Shipment Flow Videos

Categorization Flows

Let’s remind ourselves of the classes of data involved in the category flows:

Category Flows

Provider	Consumer	Use Case	Seller API	Webhooks
Marketplacer	Seller	Get brands	`brands`	N/a
Marketplacer	Seller	Get taxons	`taxons`	N/a
Marketplacer	Seller	Get option types	`node (prototype)`	N/a
Marketplacer	Seller	Get option values	`node (prototype)`	N/a

Further Viewing

🎥 Categorization Flow Videos

Remittance Flows

Let’s remind ourselves of the classes of data involved in the remittance flows:

Remittance Flows

Provider	Consumer	Use Case	Seller API	Webhooks
Marketplacer	Seller	Get remittances	`remittances` `remittanceAdvices`	N/a

What’s Next

Next we look at the Design Decisions that should be considered when building your integration.