Getting Started

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:

1. Select Extensions
2. Select API Access

On the API Access screen, enter the following details:

1. Your name
2. The organization that you work for
3. Accept the API License agreement

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

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

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

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://https://bestfriendbazaar.com/graphql

Step 3: Set up an API Client

How you choose to call the Marketplacer API’s 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. Follow these steps to set up Insomnia:

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

• Right click anywhere in the left hand plane and select: New 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

• Further configure your request as shown below:

Some points to note:

1. Ensure you have selected a POST request
2. Ensure you have the correct endpoint - don’t forget the graphql path!
3. Your Key should be added as a header with a name of MARKETPLACER-API-KEY
4. [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 GraphQL tab in the request you have configured in Insomnia, and enter the following GraphQL query:

query {
  invoices	
  {
    nodes{
      id
      legacyId
      updatedAt
      buyerEmailAddress
      seller{git 
        businessName
        id
        legacyId
      }
      statusFlags			
    }
  }    
}

As shown below:

• Click send, and all being well you should get a JSON payload response (assuming you have invoices of course!):

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