> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gamecart.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Verified seller-facing API contracts for Gamecart integrations

Gamecart exposes a narrow seller API for external integrations, plus signed webhooks and custom gateway contracts.

These pages are verified against the current backend REST resources and DTOs. Do not rely on older drafts or examples from support conversations.

## Base URLs

Use the production API origin for external calls:

```text theme={"dark"}
https://api.gamecart.gg
```

Storefront checkout helpers use this scoped base:

```text theme={"dark"}
https://api.gamecart.gg/v1/stores
```

API tokens, webhook endpoints, and gateway settings are created from the Gamecart dashboard. The public docs explain those dashboard workflows and only show raw HTTP contracts for calls your own integration needs to make or receive.

## Authentication modes

| Surface                 | Auth                                                             | Main use                                                    |
| ----------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------- |
| Seller API              | `Authorization: Bearer <api_token>`                              | Read store orders and payment status from your integration. |
| Outbound webhooks       | `Gamecart-Signature`, `Gamecart-Event-Id`, `Gamecart-Event-Type` | Receive Gamecart order events on your endpoint.             |
| Custom gateway requests | `Gamecart-Signature`, `Gamecart-Event-Id`, `Gamecart-Event-Type` | Verify payment creation requests sent by Gamecart.          |
| Custom gateway callback | `Gamecart-Signature` and `Gamecart-Event-Id`                     | Confirm a custom gateway payment back to Gamecart.          |

## Pagination

Seller API list endpoints return the shared paged response shape:

```json theme={"dark"}
{
  "items": [],
  "totalItems": 0,
  "currentPage": 0,
  "totalPages": 0,
  "pageSize": 20
}
```

Supported query parameters are `page` and `size`. Page indexes start at `0`. Current list endpoints clamp `size` to a maximum of `100`.

## Error format

API errors use Problem Details:

```json theme={"dark"}
{
  "type": "https://gamecart.gg/problems/INVALID_INTEGRATION_TOKEN",
  "title": "Unauthorized",
  "status": 401,
  "detail": "The integration token is invalid or revoked.",
  "code": "INVALID_INTEGRATION_TOKEN",
  "traceId": "..."
}
```

The exact `detail` text is localized by the backend. Integrations should branch on HTTP status and `code`, not on translated text.

## Scopes

API tokens use explicit scopes:

| Scope               | Allows                                                                       |
| ------------------- | ---------------------------------------------------------------------------- |
| `orders:read`       | List orders and read order details.                                          |
| `payments:read`     | Read payment status for an order.                                            |
| `orders:buyer:read` | Include buyer name, email, and account identifier in order detail responses. |

<CardGroup cols={2}>
  <Card title="API tokens" icon="key-round" href="/api-reference/api-tokens">
    Create tokens from the dashboard, choose scopes, and copy the token safely.
  </Card>

  <Card title="Orders API" icon="shopping-bag" href="/api-reference/orders">
    Read orders and payment status with a seller API token.
  </Card>

  <Card title="Webhooks" icon="radio-tower" href="/webhooks/overview">
    Configure webhook endpoints in the dashboard and receive signed order events.
  </Card>

  <Card title="Custom gateways" icon="credit-card" href="/guides/custom-gateways">
    Connect a store-owned payment gateway to checkout.
  </Card>
</CardGroup>