Overview
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:
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.
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:
Authentication
To authenticate to the API, use an Authorization header to pass your API Key:
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:
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.