Overview

What is the Marketplacer Seller API and why would you use it.

What is the Seller API

The Marketplacer Seller API can be used by sellers to automate the processes required for selling their products on a Marketplacer marketplace:

Seller API


The range of operations that you can perform with this API include but are not limited to the following domains:

  • Product (aka Adverts)
  • Orders
  • Shipping
  • Refunds

What is the Legacy Seller API?

The Legacy Seller API was the previous way Sellers could integrate into Marketplacer. The Legacy Seller API is a REST based API, whereas the current Seller API (i.e. the one you’re reading about now!) is a GraphQL based API.

A Feature Matrix comparing the 2 Seller APIs can be found here.

GraphQL

This API complies with the graphql specification. If you’ve not worked with GraphQL before, then we strongly recommend taking a look at these docs as they give you a good grounding on the general concepts you’ll need if you want to get the most out of working with the API.

This video also gives a brief introduction to general GraphQL concepts:


Additionally, while you work with our GraphQL API, you may also find the following resources useful, both of which are auto generated from the Marketplacer GraphQL schema, and are therefore fully up to date:

Relay Specification

In addition to implementing the GraphQL specification, this API also follows the Relay Specification. This is a set of guidelines and conventions developed by Facebook for building GraphQL APIs in a consistent and efficient way.

It provides an opinionated view on things such as:

  • The structure of GraphQL queries & mutations
  • Interfaces for object types
  • Pagination & Caching

Page Sizes

Paging result sets should be employed as a matter of best practice irrespective of the expected result set size.

A maximum page size of 500 is recommended for all GraphQL APIs.

This article explains how to use pagination with GraphQL queries.

API Collections

We have provided API collections for both Postman and Insomnia to get you started, please visit the Seller API Collections page to download and get started.

HTML Sanitization

We do not currently perform any type of HTML sanitization on object fields that could contain HTML or Script fragments. It is the responsibility of the consuming endpoint to perform such checks.

Content Type

API clients must supply a Content-Type header of application/json when sending request data:

Content Type Header

Authentication

To authenticate to the API, use an Authorization header to pass your API Key:

Bearer Auth

If your Marketplacer instance is password protected via Basic Authentication, you will not be able to supply an API key and a username/password using an Authorization header.

In this case, set the username/password using the Authorization header (select the Basic Authentication scheme) and set the API key using the MARKETPLACER-API-KEY header:

Basic Auth

Information on how to get your API key can be found in Getting Started

API Key Rotation

For more information on our API Key Rotation recommendations, please refer to this playbook.