Skip to main content

SDK services

Package: @propeller-commerce/propeller-sdk-v2

The SDK is the data layer of the Storefront SDK. It is a typed GraphQL client with a service for every supported query and mutation, and the GraphQL documents come bundled per operation, so you never write or maintain GraphQL yourself. It runs in any JavaScript or TypeScript project (Node.js, React, Vue, Angular, Svelte, server scripts) and has no runtime dependency on the graphql package.

Checked against propeller-sdk-v2 0.18.0 on 28 October 2026.

npm install @propeller-commerce/propeller-sdk-v2

Create a client​

createClient() is the entry point. It defaults to proxy mode, in which the client posts to your own server route and sends no API key.

import { createClient } from '@propeller-commerce/propeller-sdk-v2';

export const graphqlClient = createClient({
  endpoint: '/api/graphql',     // your server route
  securityMode: 'proxy',        // the default: no API key in the browser
  defaultLanguage: 'NL',        // fallback for calls that pass no language
  getAccessToken: () => readMyToken(),   // the signed-in user's token, sync or async
});

The main configuration fields:

FieldPurpose
endpointRequired. Your GraphQL route, or the API URL on a server.
securityMode'proxy' (default, for browser code) or 'direct' (server code that holds the keys).
getAccessTokenReturns the current bearer token for signed-in requests.
defaultLanguageFallback language for calls that do not pass one.
headersExtra headers merged into every request.
timeoutRequest timeout in milliseconds (default 30000).

For every option, including apiKey, orderEditorApiKey, clientId, caching and how partial errors are reported, see client configuration on the SDK docs site.

Call a service​

Each service is a factory that takes the client and returns typed methods. Import only the services you use; bundlers drop the rest.

import { productService } from '@propeller-commerce/propeller-sdk-v2';

const products = productService(graphqlClient);
const product = await products.getProduct({ productId: 42, language: 'NL' });

product.sku;
product.price?.gross;   // read with optional chaining (see the note below)

The SDK has more than 50 services across catalog, cart, order, user, B2B, media and admin domains, among them productService, categoryService, clusterService, cartService, orderService, userService, loginService, companyService, addressService, favoriteListService, orderlistService and paymentService. For the full list and every method, see services on the SDK docs site, or the types in your editor.

A service method returns the operation's named type (for example getProduct returns Product), but only the fields the operation selects are filled in. Treat any field outside the selection as possibly absent and use optional chaining. Operation variables on the SDK docs site explains the defaults the SDK fills in.

Localized fields​

Many fields are lists of localized strings (for example product.names). Resolve them with getLocalized:

import { getLocalized } from '@propeller-commerce/propeller-sdk-v2';

const name = getLocalized(product.names, 'EN', 'NL'); // EN, then NL, then the first

The GraphQL route​

In proxy mode the client posts to a route on your server (for example /api/graphql) instead of calling Propeller directly. The route adds the API key and forwards the user's token, so no key reaches the browser:

Browser                         Your server route           Propeller API
───────                         ─────────────────           ─────────────
productService.getProduct()
  → POST /api/graphql           → adds the API key
                                → forwards the request   → returns data
                                ← passes the response back
  ← receives the typed result

The Accelerator boilerplates ship this route. In your own app you add it yourself: see Add the SDK to your app, and Keys and security for which key it should hold.

Server code that holds the keys itself, such as a payment webhook, uses securityMode: 'direct' with the API URL as the endpoint. See Payment providers.

Error handling​

Service methods throw a GraphQLOperationError only on a hard failure: the server returned errors and no data. On a partial response they return the data and report the errors through the client's debug log. Call client.execute() directly if you need the raw data and errors.

See also​

Last updated on