The Afosto API: orders, stock and customers in one GraphQL endpoint
Send queries and mutations to afosto.app/graphql with an API key, or let retailers connect your app with OAuth 2.0. Webhooks tell your app when an order changes or a delivery is on its way, signed with HMAC-SHA256.
How does the Afosto API work?
The Afosto API is a GraphQL API for commerce, fulfilment and CRM. Every request is an HTTP POST to afosto.app/graphql with a JSON body and your key as a Bearer token. You read and change the same orders, products, stock and customers that the retailer's team works with in afosto.app.
New to GraphQL? Read what GraphQL is and how it compares to REST or the official introduction on graphql.org, then explore the schema in the GraphQL playground.
Queries and mutations
Queries read data and mutations change it. Pass input as variables instead of pasting values into the query string.
Cursor pagination
Lists use Relay-style cursors. Ask for a page with first and after, then read pageInfo to fetch the next one.
Readable errors
The HTTP status is always 200. Check the errors array: each error has a message and extensions, such as status 401 when your key is missing or invalid, or a code such as VALIDATION_ERROR or RATE_LIMITED.
Idempotency keys
Send an Idempotency-Key header with confirmCart and payment calls, so a retried request is recognised as the same request.
At a glance
What the Afosto API gives you
1 endpoint
POST afosto.app/graphql for every query and mutation
7 events
Webhook events for orders and deliveries, from ORDER_CREATED to DELIVERY_IN_TRANSIT
HMAC-SHA256
Signature on every webhook, in the X-Afosto-Hmac-Sha256 header
MIT
License of the open-source Storefront and Instant Search clients
How do you make your first Afosto API request?
1. Create an API key. In afosto.app, go to Settings, then API, and create a key. You see it only once, so store it in a secrets manager or an environment variable. Use one key per integration, so you can revoke access for one integration without touching the others.
2. Check that the key works. This query returns the user behind the key:
curl -X POST https://afosto.app/graphql \
-H "Authorization: Bearer $AFOSTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "query { me { id email } }"}'3. Create an order and add items. The example below has no dependencies. It creates an order in a sales channel, adds a SKU and stops on the first error code:
const gql = async (query, variables) => {
const res = await fetch('https://afosto.app/graphql', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.AFOSTO_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ query, variables }),
});
const { data, errors } = await res.json();
if (errors) throw new Error(errors[0].extensions?.code ?? errors[0].message);
return data;
};
const { createOrder } = await gql(
`mutation ($input: CreateOrderInput!) {
createOrder(input: $input) { order { id number status } }
}`,
{ input: { channel_id: CHANNEL_ID, currency: 'EUR', country_code: 'NL' } },
);
await gql(
`mutation ($input: AddItemsToOrderInput!) {
addItemsToOrder(input: $input) { order { id number } }
}`,
{ input: { order_id: createOrder.order.id, items: [{ sku: 'SKU-001', quantity: 2 }] } },
);Every query, mutation and type is in the API reference, along with pagination and error handling.
Build a custom storefront with the Storefront JavaScript Client
For a headless webshop or your own frontend, the Storefront JavaScript Client wraps the storefront part of the API in ready-made calls. You create the client with the storefront token of your sales channel. Carts, checkout and orders then run on Afosto.
- Cart calls: addCartItems puts products in the cart and addCouponToCart applies a discount code.
- Cart to order: confirmCart turns the cart into an order, which lands in Afosto order management like any other webshop order.
- Hosted or custom checkout: Send shoppers to the hosted checkout, or build your own flow with the shipping and payment methods of the channel.
- Open source: The client is MIT-licensed and lives on GitHub and on npm as @afosto/storefront.
The Storefront JavaScript Client docs cover setup, carts, coupons and both checkout types. The headless webshop page shows what the retailer gets on the other side.
Webhooks and access for your integration
Webhooks for orders and deliveries
Subscribe an endpoint to order and delivery events, such as ORDER_CREATED, ORDER_UPDATED or DELIVERY_IN_TRANSIT. Each event arrives as a JSON POST with the event name, the entity ID and the time it happened.
Signed, so you can trust them
Afosto generates a signing secret for every endpoint. Each webhook carries an HMAC-SHA256 signature of the request body in the X-Afosto-Hmac-Sha256 header, so you can check that the message came from Afosto.
Retries and a delivery log
When your endpoint does not reply with a 2xx status, Afosto tries again within the retry limit of that endpoint. Per endpoint you see each message with its status, delivery attempts, HTTP response and payload.
The right token for each call
Server-side integrations use an API key. Calls on behalf of a shopper, such as logging in or registering a customer, use a storefront token. Account operations, such as reordering, use a user token.
OAuth 2.0 for apps that retailers connect
Building an app for several retailers? afosto.app supports the OAuth 2.0 authorization code flow with PKCE, with read and write scopes per area, such as orders or inventory. The retailer never shares a password with you.
Open-source building blocks
The Storefront client, the Instant Search client and the Instant Search widget are open source under the MIT license. You find them on GitHub and npm under the afosto name.
FAQ
Questions about the Afosto API
What is the Afosto API?
The Afosto API is the GraphQL API of the Afosto platform for commerce, fulfilment and CRM. You send queries and mutations as POST requests to https://afosto.app/graphql, with an API key as Bearer token, to read and change orders, products, stock and customers. Webhooks tell your app when orders or deliveries change. The developer docs list every query, mutation and type.
Does Afosto have a REST API?
On afosto.app, the documented public API is GraphQL, on one endpoint. A REST API (v2, at api.afosto.com) belongs to the older Afosto 2.0 platform on app.afosto.com and is documented on docs.afosto.com. Building something new? Use the GraphQL API.
How do I authenticate with the Afosto API?
For your own integration, create an API key in afosto.app under Settings, then API, and send it as a Bearer token in the Authorization header. Calls for shoppers, such as customer login, use a storefront token.
For an app that other retailers connect, afosto.app supports OAuth 2.0 with the authorization code flow and PKCE (RFC 7636). Endpoints and scopes are in the public discovery document at afosto.app/api/.well-known/oauth-authorization-server. Afosto approves a new OAuth client before retailers can connect it, so contact us when your app is ready.
Which webhook events does Afosto send?
Afosto sends webhooks for seven events: ORDER_CREATED, ORDER_RELEASED, ORDER_OPENED, ORDER_UPDATED, ORDER_CLOSED, ORDER_KEYSET_UPDATED and DELIVERY_IN_TRANSIT. Each message holds the event, the entity type and ID, a message ID, the time it was triggered and the data. Check the X-Afosto-Hmac-Sha256 header against the secret of your endpoint before you process the message.
Does the Afosto API have a rate limit?
Yes. When you send too many requests, the API returns an error with the code RATE_LIMITED. Back off exponentially, retry, and cache data you read often. Because the HTTP status is always 200, check the errors array in every response.
Is Afosto open source?
Afosto itself is a hosted platform, so you do not run or change its code. Several client libraries are open source: the Storefront JavaScript Client, the Instant Search client and the Instant Search widget are published under the MIT license on GitHub and npm.
Do I need to build an integration myself?
Not always. Afosto has ready-made integrations with webshops, marketplaces, accounting software and carriers. Check the integrations overview first, and use the API for what it does not cover or for your own systems.
Start building on the Afosto API
Create an account to get your API key and try your first query. Want to see first how your integration fits a retailer's orders, stock and channels? Book a demo.