Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

3.2 KB
Raw Blame
---
title: "Admin SDK quickstart for @spree/admin-sdk"
sidebarTitle: Quickstart
description: "Install and configure @spree/admin-sdk, the official TypeScript client for the Spree Admin API v3, to manage products, orders, customers, and stock."
---

[`@spree/admin-sdk`](https://www.npmjs.com/package/@spree/admin-sdk) is the official TypeScript SDK for the [Admin API v3](/api-reference/admin-api/introduction) — the back-office counterpart to [`@spree/sdk`](/developer/sdk/quickstart). Use it to build integrations, automations, internal tools, and custom admin UIs: manage products, orders, customers, stock, promotions, webhooks, and more.

<Note>
  `@spree/admin-sdk` 1.x works with the Spree 6.0 Admin API. Check the [changelog](https://github.com/spree/spree/blob/main/packages/admin-sdk/CHANGELOG.md) when updating.
</Note>

## Installation

```bash
npm install @spree/admin-sdk
```

## Quick start

Create a client with a [secret API key](/developer/sdk/admin/authentication) (server-to-server) and start calling resources:

```typescript
import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://your-store.com',
  secretKey: process.env.SPREE_SECRET_KEY, // sk_xxx — server-side only
})

// List recently placed orders
const { data: orders, meta } = await client.orders.list({
  status_eq: 'placed',
  sort: '-completed_at',
  limit: 25,
})

// Create a purchasable product — pricing lives on variants
const product = await client.products.create({
  name: 'Aero Hoodie',
  status: 'active',
  tags: ['new-arrivals'],
  variants: [
    {
      sku: 'AERO-HOODIE',
      prices: [{ currency: 'USD', amount: '59.00' }],
    },
  ],
})
```

Every method is fully typed — responses use types generated from the API serializers:

```typescript
import type { Order, PaginatedResponse } from '@spree/admin-sdk'

const page: PaginatedResponse<Order> = await client.orders.list()
```

<Note>
  Secret keys grant back-office access — never ship them in browser code. For browser-based admin apps, use [JWT cookie authentication](/developer/sdk/admin/authentication#jwt--cookie-authentication-browser-apps) instead.
</Note>

## Learn more

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/developer/sdk/admin/authentication">
    Secret keys with scopes for servers, JWT + httpOnly refresh cookie for browser apps.
  </Card>
  <Card title="Resources" icon="boxes" href="/developer/sdk/admin/resources">
    The full resource map — products, orders, customers, stock, promotions, webhooks, and more.
  </Card>
  <Card title="Querying & Errors" icon="filter" href="/developer/sdk/admin/querying-and-errors">
    Filtering, sorting, pagination, prefixed IDs, and structured error handling.
  </Card>
  <Card title="Admin API Reference" icon="book" href="/api-reference/admin-api/introduction">
    The underlying REST API the SDK wraps — every endpoint, parameter, and response shape.
  </Card>
</CardGroup>

<Tip>
  Adding your own resources? The [`spree generate api_resource`](/developer/tutorial/model-and-api) generator scaffolds Admin API endpoints (model, serializers, controllers, specs) in one command, and the [extending guide](/developer/sdk/extending) shows how to call custom endpoints from the SDK.
</Tip>