Skip to main content
The Hey Chocolate API is a GraphQL API that provides a single endpoint for all operations. GraphQL allows you to request exactly the data you need and combine multiple resources in a single request.

​
Endpoint

POST https://api.heychocolate.com/graphql
Sandbox environment: 
POST https://sandbox.heychocolate.com/graphql

​
Making requests

All requests are POST requests with a JSON body containing the GraphQL query: 
curl -X POST https://api.heychocolate.com/graphql \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_your_key_here" \
  -d '{
    "query": "query { products(first: 10) { edges { node { id name } } } }",
    "variables": {}
  }'

​
Request format

FieldTypeRequiredDescription
queryStringYesThe GraphQL query or mutation
variablesObjectNoVariables referenced in the query
operationNameStringNoName of the operation (when sending multiple)

​
Response format

Every response follows the standard GraphQL response format: 
{
  "data": { ... },
  "errors": [ ... ],
  "extensions": {
    "requestId": "req_abc123",
    "cost": 12,
    "rateLimit": {
      "remaining": 588,
      "resetAt": "2025-09-01T12:01:00Z"
    }
  }
}

​
Pagination

The API uses cursor-based pagination following the Relay Connection specification: 
query {
  products(first: 20, after: "cursor_abc") {
    edges {
      node { id name }
      cursor
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}

​
Introspection

The GraphQL schema is fully introspectable. Use your favorite GraphQL client (GraphiQL, Apollo Studio, Insomnia) to explore the schema: 
query {
  __schema {
    types {
      name
      description
    }
  }
}

​
Schema overview

Queries

Read data: products, customers, orders, supply chains, search, and DPPs.

Mutations

Write data and trigger actions: calculations, scenarios, orders, and asset generation.

Types

Core data types: Customer, Product, Order, SupplyChain, Transaction, ShoppingCart, DPP.

Enums

Sector tags, transport methods, energy sources, lifecycle phases, and more.