Getting Started with the Commercives GraphQL API

Our GraphQL API gives you full access to the Commercives platform. This guide covers everything you need to get started.

Authentication

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

curl -X POST https://api.commerciv.es/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ viewer { id } }"}'

Getting Your API Key

1. Go to Settings → API Keys in Studio
2. Click Create API Key
3. Give it a descriptive name
4. Copy the key (it won't be shown again)

Your First Query

Let's fetch some products:

query GetProducts {
  products(first: 10) {
    edges {
      node {
        id
        name
        sku
        price {
          amount
          currency
        }
      }
    }
  }
}

Creating Resources

Use mutations to create and update data:

mutation CreateProduct($input: CreateProductInput!) {
  createProduct(input: $input) {
    product {
      id
      name
      sku
    }
    errors {
      field
      message
    }
  }
}

Pagination

We use cursor-based pagination. Use first, after, last, and before arguments:

query GetProducts($cursor: String) {
  products(first: 20, after: $cursor) {
    edges {
      node {
        id
        name
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Error Handling

Mutations return errors in a structured format:

{
  "data": {
    "createProduct": {
      "product": null,
      "errors": [
        {
          "field": "sku",
          "message": "SKU already exists"
        }
      ]
    }
  }
}

Rate Limits

• Standard: 100 requests per minute
• Bulk operations: 10 per minute

Headers indicate your current usage:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1625097600

SDK Options

We provide official SDKs:

• React: @commercives/sdk-react
• React Native: @commercives/sdk-react-native

Install and use:

import { useProducts } from '@commercives/sdk-react';

function ProductList() {
  const products = useProducts();
  const { data, loading, error } = products.list({ first: 10 });

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <ul>
      {data.products.edges.map(({ node }) => (
        <li key={node.id}>{node.name}</li>
      ))}
    </ul>
  );
}

Next Steps

• Explore the API Reference
• Set up Webhooks for real-time updates
• Contact us if you need help

Questions? Reach out to our developer support team.