Overview

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

3 minute read

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

Language

A great way to familiarize yourself with the different terms and concepts used by Marketplacer would be to quickly review our Glossary of Terms.

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.

IMPORTANT

Sellers building integrations into Marketplacer should only use the current GraphQL-based Seller API, and not the legacy REST based API.

All future developments, including new features will be added to the the GraphQL-based Seller API only

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:

Full Documentation
GraphQL Voyager An interactive visualization of our schema

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. The following defaults apply to all Marketplacer APIs:

Default Page Size: 50 (you can specify your own page size up to the maximum page size value)
Maximum Page Size: 500

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: Bearer Auth

If your site is currently password protected, you will not be able to supply a username/password AND an API key. If this is the case, set the username/password using basic authentication and send 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.