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.

Add guide how to extend Admin SDK

Damian Legawieca2b5bada107b
diff --git a/docs/developer/sdk/admin/extending.mdx b/docs/developer/sdk/admin/extending.mdx
new file mode 100644
index 0000000000..ace7f9d208
--- /dev/null
+++ b/docs/developer/sdk/admin/extending.mdx
@@ -0,0 +1,70 @@
+---
+title: Custom Admin Endpoints
+sidebarTitle: Custom Endpoints
+description: Call custom Admin API endpoints using the SDK's built-in request method
+---
+
+The Admin SDK client exposes a `request` method — the same function that powers `client.products.list()`, `client.orders.get()`, and every other built-in resource. Use it to call any Admin API endpoint, including ones added by an extension gem that doesn't ship its own client.
+
+```typescript
+import { createAdminClient } from '@spree/admin-sdk'
+import type { PaginatedResponse } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://api.mystore.com',
+ token: 'sk_YOUR_SECRET_KEY', // or a JWT from /auth/login
+})
+
+interface Brand {
+ id: string
+ name: string
+ slug: string | null
+ description: string | null
+ logo_url: string | null
+}
+
+// Paths are relative to /api/v3/admin
+const brands = await client.request<PaginatedResponse<Brand>>('GET', '/brands')
+const nike = await client.request<Brand>('GET', '/brands/nike')
+```
+
+`client.request` uses the same auth headers (secret API key *or* JWT, whichever was configured at client creation), retry logic, and base URL as every other resource on the client. The 401 → refresh → retry handshake that's wired up for the dashboard's user session applies to your custom endpoint too.
+
+## Mutations
+
+POST/PATCH/DELETE work the same way — pass `{ body }` for the request payload:
+
+```typescript
+const created = await client.request<Brand>('POST', '/brands', {
+ body: { name: 'Acme', slug: 'acme', description: 'Quality goods since 1953' },
+})
+
+const updated = await client.request<Brand>('PATCH', `/brands/${created.id}`, {
+ body: { description: 'New tagline' },
+})
+
+await client.request<void>('DELETE', `/brands/${created.id}`)
+```
+
+## Ransack filters and pagination
+
+Standard list params work — pass them as the third argument's `params`:
+
+```typescript
+const result = await client.request<PaginatedResponse<Brand>>('GET', '/brands', {
+ params: {
+ page: 2,
+ per_page: 25,
+ filter: { name_cont: 'nike' },
+ sort: '-created_at',
+ },
+})
+```
+
+The SDK transforms `filter`/`sort` into the Ransack-flavored query string the Admin API expects (`q[name_cont]=nike&q[s]=created_at%20desc`) automatically — same behavior as `client.products.list({ filter: ... })`.
+
+## See also
+
+- The [Store SDK extending guide](/developer/sdk/extending) covers the same pattern for storefront endpoints — the API is identical, only the base path (`/api/v3/store`) and auth header differ.
+- The [Store API](/developer/tutorial/store-api) and [SDK](/developer/tutorial/sdk) tutorials walk through creating new Spree endpoints end-to-end (Rails controller, serializer, TypeScript types). Everything they show for the Store API applies equivalently for the Admin API.
+- For building dashboard UI on top of your custom endpoint, see the [Dashboard Plugins](/developer/customization/dashboard-plugins) guide.
diff --git a/docs/docs.json b/docs/docs.json
index 17a1222a78..838cadeb08 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -506,7 +506,8 @@
"developer/sdk/admin/quickstart",
"developer/sdk/admin/authentication",
"developer/sdk/admin/resources",
- "developer/sdk/admin/querying-and-errors"
+ "developer/sdk/admin/querying-and-errors",
+ "developer/sdk/admin/extending"
]
}
]
diff --git a/packages/admin-sdk/src/admin-client.ts b/packages/admin-sdk/src/admin-client.ts
index e5895febb5..219cc758f5 100644
--- a/packages/admin-sdk/src/admin-client.ts
+++ b/packages/admin-sdk/src/admin-client.ts
@@ -229,7 +229,28 @@ const CUSTOM_FIELD_OWNER_PATHS = {
} as const satisfies Record<Exclude<CustomFieldOwnerType, string & {}>, string>
export class AdminClient {
- /** @internal */
+ /**
+ * Low-level request function for calling custom Admin API endpoints —
+ * e.g. ones added by a Spree extension gem that doesn't ship its own
+ * client.
+ *
+ * Uses the same auth headers (secret API key or JWT, whichever was
+ * configured), retry logic, and base URL as the built-in resources.
+ * Paths are relative to `/api/v3/admin`.
+ *
+ * @example
+ * ```ts
+ * import { createAdminClient } from '@spree/admin-sdk'
+ * import type { PaginatedResponse } from '@spree/admin-sdk'
+ *
+ * interface Brand { id: string; name: string; slug: string }
+ *
+ * const client = createAdminClient({ baseUrl: 'https://api.shop.com', token: '...' })
+ *
+ * const brands = await client.request<PaginatedResponse<Brand>>('GET', '/brands')
+ * const nike = await client.request<Brand>('GET', '/brands/nike')
+ * ```
+ */
readonly request: RequestFn
constructor(request: RequestFn) {