AI Commerce GraphQL API for partners

This article explains how partners and integration teams use the AI Commerce GraphQL API. It covers where to find the public API documentation, how requests are sent, which headers are required, and how rate limiting works.

Public API documentation

The public GraphQL schema reference is available at https://docs.aicommerce.cloud. Use it to browse available queries, mutations, types, examples, and authentication headers.

The documentation site and the live API endpoint are intentionally separate. Use docs.aicommerce.cloud as the schema reference, and send production API requests to https://api.aicommerce.fi/graphql.

How GraphQL requests work in AI Commerce

GraphQL requests are sent as HTTP POST requests with a JSON request body. The request body contains a query field and, when needed, a variables field.

• The client asks only for the fields it needs.
• The API returns data in the same shape as the requested GraphQL selection.
• Each request must include the required tenant and GraphQL authentication headers.

Required request headers

Every GraphQL request must include the following headers.

Example request

The following example requests a small page of products.

query Products($limit: Int, $offset: Int) {
  products(limit: $limit, offset: $offset) {
    id
    name
    price
  }
}

Example request with variables:

curl -X POST https://api.aicommerce.fi/graphql \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "X-Tenant-Secret: <your-tenant-secret>" \
  -H "X-GraphQL-Secret: <your-graphql-secret>" \
  --data '{
    "query": "query Products($limit: Int, $offset: Int) { products(limit: $limit, offset: $offset) { id name price } }",
    "variables": {
      "limit": 5,
      "offset": 0
    }
  }'

Example response shape:

{
  "data": {
    "products": [
      {
        "id": "632",
        "name": "Example product",
        "price": 89.9
      }
    ]
  }
}

Rate limiting and errors

The production GraphQL API is rate limited to protect service stability. The current limit is 100 requests per 5 minutes per tenant.

• If the limit is exceeded, the API returns 429 Too Many Requests.
• If authentication fails, verify the tenant identifier, tenant secret, and GraphQL access token.
• If the request body is invalid, verify that the request is valid JSON and that the GraphQL query matches the public schema.

{
  "error": "Too many requests, please try again later."
}

GraphQL compared with REST

GraphQL is useful when an integration needs a specific set of fields or needs to combine related data in one request.

Security and onboarding

• Keep tenant and GraphQL secrets on the server side. Do not expose them in browser-side code or public repositories.
• Use the public documentation to validate query names, field names, argument names, and response types before implementation.
• For API credentials or onboarding questions, contact info@petrosoft.fi.

Summary

• Public GraphQL documentation is available at https://docs.aicommerce.cloud.
• Production API requests are sent to https://api.aicommerce.fi/graphql.
• Every request requires Content-Type, X-Tenant-ID, X-Tenant-Secret, and X-GraphQL-Secret.
• The API is rate limited per tenant, so integrations should handle 429 Too Many Requests responses cleanly.