Getting Started with the Marketplace Labs GraphQL API

Welcome to the Marketplace Labs API! This guide will walk you through everything you need to know to start integrating with our GraphQL API.

What is GraphQL?

GraphQL is a query language for APIs that allows you to request exactly the data you need. Unlike REST APIs, where you might need multiple endpoints to get related data, GraphQL lets you fetch everything in a single request.

Prerequisites

Before you begin, make sure you have:

A Marketplace Labs account with an active subscription
Your API key (available in your account dashboard)
Basic knowledge of HTTP requests

Authentication

All API requests require authentication using your API key. Include it in the Authorization header:

curl -X POST https://api.mplabs.co.uk/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"query": "{ products(first: 10) { edges { node { id name } } } }"}'

Your First Query

Let's start with a simple query to fetch your products:

query GetProducts {
  products(first: 10) {
    edges {
      node {
        id
        name
        sku
        price
        inventoryQuantity
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

This query will return the first 10 products with their ID, name, SKU, price, and inventory quantity.

Understanding Pagination

The Marketplace Labs API uses cursor-based pagination. This means:

first/last: Specify how many items you want
after/before: Use cursors to navigate pages
pageInfo: Contains pagination metadata

query GetNextPage {
  products(first: 10, after: "cursor_from_previous_page") {
    edges {
      node {
        id
        name
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Working with Mutations

Mutations are used to create, update, or delete data. Here's an example of updating a product's inventory:

mutation UpdateInventory {
  updateProductInventory(
    input: {
      productId: "prod_123"
      quantity: 100
      adjustmentType: SET
    }
  ) {
    product {
      id
      inventoryQuantity
    }
    userErrors {
      field
      message
    }
  }
}

Error Handling

The API uses a userErrors pattern for validation errors. Always check this field in mutation responses:

{
  "data": {
    "updateProductInventory": {
      "product": null,
      "userErrors": [
        {
          "field": "quantity",
          "message": "Quantity must be a positive number"
        }
      ]
    }
  }
}

Rate Limiting

The API has rate limits to ensure fair usage:

Standard plans: 100 requests per minute
Pro plans: 500 requests per minute
Enterprise plans: Custom limits

Rate limit headers are included in every response.

Next Steps

Now that you understand the basics, explore these topics:

Webhooks: Real-time notifications for events
Inventory Sync: Keep your inventory in sync across channels
Order Management: Create and manage orders programmatically

Check out our full API documentation for detailed schema information and more examples.