Introduction#

Welcome to the Afosto Developer Documentation. This guide will help you integrate with the Afosto platform using our GraphQL API.

What is the Afosto API?#

The Afosto API is a GraphQL API that gives you full programmatic access to your Afosto data. You can use it to manage products, orders, customers, inventory, payments, and more — all through a single, flexible endpoint.

https://afosto.app/graphql

GraphQL lets you request exactly the data you need — no more, no less. That means faster responses and simpler client code than the typical REST round-trip-per-resource shape.

How to use this site#

These docs are split into four parts, listed in the left sidebar:

• Getting Started — what you're reading now, plus authentication, request format, and rate limits.
• How-to Guides — step-by-step recipes for common flows (creating a cart, taking a PIN payment, attaching a track & trace number, …).
• GraphQL API — the full reference: every query, mutation, type, and enum, generated from the live schema.
• Webhooks — how to receive event payloads and verify their HMAC signatures.

Each reference page has hover popovers on type badges so you can drill into nested types without leaving the page, and a sparkle "copy for LLM" button that copies a plain-text version of the page (or the full reference) into your clipboard for pasting into an AI tool.

The query runner#

Every code block on the right of the screen has a ▶ play button. Clicking it loads that query (and its example variables) into the query runner — the panel pinned to the right side of the docs.

From there you can:

• Edit the query freely; the editor has GraphQL syntax highlighting and field-level autocomplete (the same schema we use to build this site).
• Run it against the live API. You'll need to authenticate first (see below) — the panel will tell you if you haven't.
• Tab between the GraphQL, cURL and JavaScript exports. The cURL and JavaScript snippets always reflect the current query and variables.
• Share a link. Press the Share button in the panel header to copy a URL that pre-fills the runner with your exact query and variables (handy for support tickets and pair-programming).
• Resize the panel by dragging its left edge.

A history of your last 5 runs sits at the bottom of the panel — click any entry to restore that query.

Logging in to Afosto#

To run live queries you need a token. There are two ways to get one:

1. Login with Afosto (recommended). Open the token pill in the top-right of the header, then click Login with Afosto. You'll be redirected to the Afosto authorize page; after approving you'll be sent back here with a token attached for the rest of the session. Tokens are stored in your browser's localStorage only — they never leave your machine.
2. Paste a token manually. Generate an API token from your Afosto account settings, copy it, and paste it into the same popover.

Queries vs. mutations#

GraphQL has two operation types you'll use here:

Queries — read data#

Queries are read-only. They never change anything on the server. You can request multiple resources in a single query and shape the response to the exact fields you need.

query {
  account {
    email
    given_name
  }
  orders(first: 5) {
    orders {
      id
      number
      total
    }
  }
}

Use queries for: fetching a cart, listing orders, looking up a product, reading an account, paginating through inventory.

Mutations — write data#

Mutations create, update, or delete resources. They follow a strict shape: each mutation takes a single argument named input, and the payload returns the affected resource (or a small wrapper around it).

mutation AddItems($input: AddItemsToCartInput!) {
  addItemsToCart(input: $input) {
    cart {
      id
      total
    }
  }
}

Use mutations for: creating a cart, adding items, attaching addresses, executing payments, generating invoices, creating parcels.

Things to know#

• Variables, not string concatenation. Pass values via the variables part of the request body. The query runner's lower textarea is the JSON variables block; the docs auto-populate it from the example. Inlining values into the query string works, but using variables avoids escaping bugs and lets you cache the parsed query.
• Pagination is per-connection. Paginated lists return a connection with pageInfo { hasNextPage endCursor } and a list field whose name varies per type — orders returns OrderConnection.orders, products returns ProductConnection.nodes, paymentMethods returns PaymentMethodConnection.methods. The reference page for each query shows the exact shape.
• Errors are returned as errors[], not HTTP status codes. Even successful mutations can return partial data with field-level errors. Always check both data and errors in the response. See Error Handling for codes and recovery patterns.
• Two token types exist. Most operations use a regular API token. A few customer-facing flows (logInCustomer, registerCustomer, password reset) require a storefront token instead. The mutation-reference pages mark which is which.

Next steps#

• Authentication — get a token and pass it as a Bearer header.
• Making Requests — anatomy of a request and response.
• Rate Limits — quotas, headers, and a TypeScript backoff snippet.
• How-to Guides → Examples — copy-pasteable recipes for the most common flows.