Getting Started

How to get up and running with the Marketplacer Seller API

5 minute read

This guide outlines how Sellers can get up and running with the GraphQL API using the Insomnia API client.

If you don’t like reading you can watch this video instead!

Step 1: Get an API Key

Login to your Seller Portal, in the following example we are a Seller called ACME Corp that wants to sell products on the Best Friend Bazaar marketplace. Once logged in:

Select Extensions
Select API Access

seller Portal

User Accounts & Logging In

Contact your marketplace operator if you need assistance logging into the Marketplacer Seller Portal.

On the API Access screen, enter the following details:

Your name
The organization that you work for
Accept the API License agreement

When you are happy, select Create API Key (4):

Enter API Details

All being well, you will be presented with your API key:

API Key

Copy the key and keep it safe as we’ll need this in the next step.

Note

Once you navigate away from the API Key screen, you will not be able to retrieve your key again. If you find yourself in this situation, you’ll need to generate a new key, and delete the old.

Basic Authentication

If you are working with a non production environment, in addition to an API key, you may also need to supply Basic Authentication credentials. These can be supplied to you by your Seller Onboarding team.

Step 2: Know your endpoint

Unlike REST endpoints which will change depending on the resources you are working with, there is only 1 GraphQL endpoint. In the case of the Marketplacer GraphQL API this will always take the form: https://YOURINSTANCENAME.COM/graphql e.g.:

https://bestfriendbazaar.com/graphql

Step 3: Set up an API Client

How you choose to call the Marketplacer APIs is your choice, however for a quick and easy way to test connectivity and functionality, an API client like Postman or Insomnia is always useful. We’ve provided steps for Insomnia and Postman below.

Seller API Collections

The steps below show you how to quickly set up a test query without using more advanced features of both Postman and Insomnia like Environments and Variables (which are recommended). Our API Collections for Postman and Insomnia have these features and can be found here.

Create Request

Download Postman here

To create a new GraphQL request:

Select “New”
Select “GraphQL”
Enter your instance endpoint url
Click Save
Name your collection (if you want) & save

Create Request

Set API Key Header

Select the “query” pane
Select “Headers”
Enter “marketplacer-api-key” for the header Key
Paste in your API Key to the header Value

Add Headers

[OPTIONAL] Set Up Basic Auth

Some instances may also require Basic Authentication credentials (usually non production instances), check with your Seller Onboarding team if this is required.

If Basic Authentication is required:

Select “Authorization”
Select “Basic Auth” from the drop down
Enter the User Id and Password

Basic Auth

Postman is now set up and ready for you to run your first query - see Step 4.

Get a free copy of Insomnia here
Open Insomnia and select: Create -> Request Collection as shown in steps 1 & 2 below:

Insomnia Request Collection

Right click anywhere in the left hand plane and select: New Request:

Insomnia Add Request

Enter a name for the request - See #1 below
Select a POST request type - See #2 below (note all GraphQL requests to the Marketplacer GraphQL API are POST requests)
Select GraphQL for the request body - See #3 below

Insomnia Add Request

Further configure your request as shown below:

Insomnia Set Up

Some points to note:

Ensure you have selected a POST request
Ensure you have the correct endpoint - don’t forget the graphql path!
Your Key should be added as a header with a name of MARKETPLACER-API-KEY
[Optional] If you are accessing on a Staging environment you may need to add Basic Authentication credentials

Step 4: Running your 1st GraphQL Query

Select the Query tab in Postman
- (you may also need to select “Query Editor” panel)
Paste in the following query:

query {
  invoices(first: 10)	
  {
    totalCount
    nodes{
      id
      legacyId
      updatedAt
      seller{
        businessName
        id
        legacyId
      }
      statusFlags			
    }
  }    
}

Expand the “Response” Panel
Click “Query”

Execute Query

If this is the first time you are working with Marketplacer it could be likely that you do not have any Invoices (aka Orders), however the query should still return successfully with a total count of 0.

Select the GraphQL tab in the request you have configured in Insomnia, and enter the following GraphQL query:

query {
  invoices(first: 10)	
  {
    totalCount
    nodes{
      id
      legacyId
      updatedAt
      seller{
        businessName
        id
        legacyId
      }
      statusFlags			
    }
  }    
}

As shown below:

Invoice Query

Click send, and all being well you should get a JSON payload response.

If this is the first time you are working with Marketplacer it could be likely that you do not have any Invoices (aka Orders), however the query should still return successfully with a total count of 0.

Next Steps

This was just a quick getting started guide, we have outlined some further resources below:

Seller API feature Matrix (details which features are available for Sellers in both our APIs)
Official GraphQL Docs
GraphQL Voyager Note: this is the full documentation for the Marketplacer GraphQL API, so many of the endpoints will not be available to Sellers
GraphQL Docs Note: this is the full documentation for the Marketplacer GraphQL API, so many of the endpoints will not be available to Sellers