Overview

What is the Operator API

The Marketplacer Operator API is predominantly used to build integrations into existing eCommerce platforms where products hosted on Markerplacer are surfaced for sale on the eCommerce frontend.

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

• Product (aka Adverts)
• Orders
• Categorization (aka Taxonomy)
• Shipping
• Remittances

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 A text-based representation of our API schema
• 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 Operator 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:

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:

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.

Issues

If you encounter any issues with using this API, please contact our support team here with:

1. an example of what request you’re making
2. What headers + body are being returned from the server
3. What you expect to happen