Overview

This describes the official Marketplacer GraphQL API.

Issues

If you encounter any issues with using this API, please contact our suppport team at support@marketplacer.com 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

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.

We will of course provide you with the documentation you need to understand the specifics of how Marketplacer has implemented GraphQL!

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:

Tooling

When developing against the API you can use either:

Both of which will read the GraphQL schema document, allowing for things like auto-completion and error detection. At the time of writing these features are better supported by Insomnia, although support in Postman appears to be improving.

The example collection of queries that we provide to help you get started, (see section below for more detail), are currently provided as a Postman collection.

Content Type

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

Content Type Header

Relay Specification

This API follows the Relay Specification for connections when returning data. This specification supports pagination using a cursor and allows traversal of data returned by the API.

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

Postman Collection

Postman is a tool for developing and testing API integrations. It provides an interface for exploring APIs and executing requests against them. A postman collection is a document describing a series of API requests that can be imported into Postman to speed up this process. We have published a Postman collection for the Marketplacer GraphQL API. It contains example query and mutation requests.

To import into Postman, download the .json file and go to the import menu in Postman:

Postman Import

Choose the .json file you downloaded and confirm that you wish to import it:

Postman Confirmation

Edit the collection to fill in the variables required to access your site (see the Postman documentation for more information)):

Postman Variable Configuration

You will now see a series of requests in Postman which you can study and execute:

Postman Request List


Collections Overview

While the queries and mutations in the collection are quite self-explanatory, we have provided some additional detail on what each does along with a few other hints and tips.

It is also worth remembering that the queries and mutations provided in the collection are just a sample of what the GraphQL API can provide. For the full documentation, please refer to:

Note: Both of the above are based off the same GraphQL Schema, they just represent the information in different ways.


Sellers

We have 2, (very similar!), example queries in the collection that allow you to return all, or some of the Sellers on the Marketplace.

  • Get all Sellers
  • Get all Sellers based on Business Name

It’s worth noting that you can search for Sellers based on more than just businessName, e.g. you can filter by:

  • updatedSince
  • State
  • Distance (Geographic radius in which to look for Sellers, e.g. within 10KM)

(These are just a sample of some of the filter criteria that can be used.)

Why would I use these?

You would use these queries to allow you to obtain the SellerId, which you can then use as part of your other queries, e.g. advertSearch (by SellerId), to obtain all Adverts for a given Seller (or Sellers)


Adverts

Adverts represent the Products or Services that a Seller may sell on a Marketplace. Going a little further an Advert, (e.g. for a Ski Jacket), may have multiple Variants, e.g.:

  • Small / White
  • Small / Black
  • Large / White
  • Large /Black

(You get the picture!)

The queries in this section all relate to how you can query the Adverts on the Marketplace, and further still, retrieve “child” objects of the Advert, e.g. the “Variants” of the Advert. We have provided the following 3 example queries:

  • Get all Adverts by Keyword
  • Get all Adverts for a Seller (using the “SellerId”)
  • Get all Adverts “updated since”

Looking more closely at the collection, you’ll notice we actually make use of 2 different “queries”:

  • advertSearch
  • allAdverts

We have summarised their differences below, and why you’d use 1 over another

Query What it does Why You’d Use
advertSearch Returns only published adverts Use this if you want to perform detailed filtering across a number of attributes, .e.g.: Brand, Country, maxPrice etc. Again, this query only returns Adverts that are published on the marketplace, i.e. those adverts that are viewable and represent items for sale.
allAdverts Returns Published, Unpublished and Deleted Adverts You would use this query when you need access to every advert on the platform irrespective of whether it’s published or not. You can only query by the time the advert was last updated.

Cart

A Cart represents a collection of items, (in this case Variants), that a consumer wishes to purchase. The collection has 3 mutations and 1 query related to the Cart:

  • Add a Variant, (a “purchasable item”), to a new Cart
  • Add a Variant to an existing Cart
  • Checkout the Cart (and create and Order)
  • Search for a Cart, (based on the CartID)

Up until this point we have only discussed reading data, (via queries). Anytime we need to add, change or delete data via GraphQL, we use Mutations. For more information on the differences between queries and mutations, refer to the official GraphQL Documentation.

Creating a new Cart, will result in a CartID being returned as part of the response payload. You can then use this id to work with the other mutations and queries.

Note: Again, this is just a sample selection of what you can do with a Cart, for example you can update items in an existing Cart and well as remove items from a Cart.


Order

The final items in our collection relate to an Order, an Order represents the purchase of one or more Variants, (aka Line Items), across 1 or more Sellers. We have 1 mutation and 1 query in our collection:

  • Create a new Order
  • Retrieve an Order

It’s worth noting that you can create an Order using either the orderCreate mutation in this section, or as previously mentioned by using the cartCheckout mutation. It will depend on your own particular use-case which approach you want to use.

Taking a closer look at the orderCreate mutation, you’ll note that you can add multiple Variants to the Order in the LineItems section:

lineItems: [
    {             
        variantId: "VmFyaWFudC0yODE="
        quantity: 1
        totalCents: 22500
        postageCents: 1000 
    },
    {             
        variantId: "VmFyaWFcbC0yEDE="
        quantity: 2
        totalCents: 50000
        postageCents: 1000
    }
]

If these 2 Variants relate to 2 different Adverts, from 2 different Sellers, then 2 Separate Invoices will be created for the Order. (An Invoice is part of an Order that is handled by a particular Seller).

This relationship is shown below:

Order Relationship

It’s also worth noting that separate invoices will be created for the same seller if different delivery methods have been chosen for Line Items, e.g.:

  • Line Item 1 – Delivery Method = “Deliver”
  • Line Item 2 – Delivery Method = “Click and Collect”

This will result in 2 separate Invoices even if the Line Items have been sold by the 1 Seller.

Creating Invoices Manually

In the example above we have shown how you can add Line Items (Variants) directly on the Order, (and that Invoices will be auto-generated), you can however take an alternative approach and create an Order with Invoices and then add Line items to the Invoice. So, we in effect we have 2 approaches:

  • Create Line Items directly on the Order as per the example, and Invoices will be created for you.
  • Create Invoices “manually” on the Order and add Line Items to the Invoices

Note: these approaches are mutually exclusive, you can use one or the other, but not both in the same mutation.

Order Query

Using the Order query, you can return the child objects of the Order, including:

  • Invoices
  • Line Items
  • Shipments