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.

Added Gift Cards and Gift Cards Batches support to Admin SDK

Damian Legawiec34792e4ea67c
diff --git a/packages/admin-sdk/examples/gift-card-batches/create.ts b/packages/admin-sdk/examples/gift-card-batches/create.ts
new file mode 100644
index 0000000000..cebf517b5a
--- /dev/null
+++ b/packages/admin-sdk/examples/gift-card-batches/create.ts
@@ -0,0 +1,18 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+const batch = await client.giftCardBatches.create({
+ prefix: 'WELCOME',
+ amount: '25.00',
+ currency: 'USD',
+ codes_count: 100,
+ expires_at: '2030-12-31',
+})
+// endregion:example
+
+export { batch }
diff --git a/packages/admin-sdk/examples/gift-card-batches/get.ts b/packages/admin-sdk/examples/gift-card-batches/get.ts
new file mode 100644
index 0000000000..13f612f233
--- /dev/null
+++ b/packages/admin-sdk/examples/gift-card-batches/get.ts
@@ -0,0 +1,12 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+const batch = await client.giftCardBatches.get('gcb_K3zr8x')
+// endregion:example
+
+export { batch }
diff --git a/packages/admin-sdk/examples/gift-card-batches/list.ts b/packages/admin-sdk/examples/gift-card-batches/list.ts
new file mode 100644
index 0000000000..ac190f7b6c
--- /dev/null
+++ b/packages/admin-sdk/examples/gift-card-batches/list.ts
@@ -0,0 +1,12 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+const { data: batches } = await client.giftCardBatches.list({ page: 1, limit: 25 })
+// endregion:example
+
+export { batches }
diff --git a/packages/admin-sdk/examples/gift-cards/create.ts b/packages/admin-sdk/examples/gift-cards/create.ts
new file mode 100644
index 0000000000..913d66263e
--- /dev/null
+++ b/packages/admin-sdk/examples/gift-cards/create.ts
@@ -0,0 +1,17 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+const giftCard = await client.giftCards.create({
+ amount: '25.00',
+ currency: 'USD',
+ expires_at: '2030-12-31',
+ user_id: 'cus_UkLWZg9DAJ',
+})
+// endregion:example
+
+export { giftCard }
diff --git a/packages/admin-sdk/examples/gift-cards/delete.ts b/packages/admin-sdk/examples/gift-cards/delete.ts
new file mode 100644
index 0000000000..7b828216ba
--- /dev/null
+++ b/packages/admin-sdk/examples/gift-cards/delete.ts
@@ -0,0 +1,10 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+await client.giftCards.delete('gc_K3zr8x')
+// endregion:example
diff --git a/packages/admin-sdk/examples/gift-cards/get.ts b/packages/admin-sdk/examples/gift-cards/get.ts
new file mode 100644
index 0000000000..ba5c87141e
--- /dev/null
+++ b/packages/admin-sdk/examples/gift-cards/get.ts
@@ -0,0 +1,14 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+const giftCard = await client.giftCards.get('gc_K3zr8x', {
+ expand: ['customer', 'created_by', 'orders'],
+})
+// endregion:example
+
+export { giftCard }
diff --git a/packages/admin-sdk/examples/gift-cards/list.ts b/packages/admin-sdk/examples/gift-cards/list.ts
new file mode 100644
index 0000000000..dda37b10dd
--- /dev/null
+++ b/packages/admin-sdk/examples/gift-cards/list.ts
@@ -0,0 +1,16 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+const { data: giftCards } = await client.giftCards.list({
+ page: 1,
+ limit: 25,
+ expand: ['customer', 'created_by'],
+})
+// endregion:example
+
+export { giftCards }
diff --git a/packages/admin-sdk/examples/gift-cards/update.ts b/packages/admin-sdk/examples/gift-cards/update.ts
new file mode 100644
index 0000000000..4699ec2641
--- /dev/null
+++ b/packages/admin-sdk/examples/gift-cards/update.ts
@@ -0,0 +1,14 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+const giftCard = await client.giftCards.update('gc_K3zr8x', {
+ amount: '75.00',
+})
+// endregion:example
+
+export { giftCard }
diff --git a/packages/admin-sdk/src/admin-client.ts b/packages/admin-sdk/src/admin-client.ts
index fca9476f60..0aa57f8eb9 100644
--- a/packages/admin-sdk/src/admin-client.ts
+++ b/packages/admin-sdk/src/admin-client.ts
@@ -102,6 +102,9 @@ import type {
ExportCreateParams,
FulfillmentUpdateParams,
GiftCardApplyParams,
+ GiftCardBatchCreateParams,
+ GiftCardCreateParams,
+ GiftCardUpdateParams,
InvitationAcceptParams,
InvitationCreateParams,
LineItemCreateParams,
@@ -155,6 +158,8 @@ import type {
CustomFieldDefinition,
Export,
Fulfillment,
+ GiftCard,
+ GiftCardBatch,
Invitation,
LineItem,
Media,
@@ -1145,6 +1150,78 @@ export class AdminClient {
this.request<void>('DELETE', `/customer_groups/${id}`, options),
}
+ // ============================================
+ // Gift cards (admin-issued)
+ // ============================================
+
+ /**
+ * CRUD for `Spree::GiftCard`. The list endpoint never embeds `customer`,
+ * `created_by`, or `orders` by default — pass `expand=customer,created_by`
+ * to populate row chips, or `expand=orders` on a detail read to surface
+ * the consuming orders.
+ */
+ readonly giftCards = {
+ list: (
+ params?: ListParams & Record<string, unknown>,
+ options?: RequestOptions,
+ ): Promise<PaginatedResponse<GiftCard>> =>
+ this.request<PaginatedResponse<GiftCard>>('GET', '/gift_cards', {
+ ...options,
+ params: params ? transformListParams(params) : undefined,
+ }),
+
+ get: (
+ id: string,
+ params?: { expand?: string[] },
+ options?: RequestOptions,
+ ): Promise<GiftCard> =>
+ this.request<GiftCard>('GET', `/gift_cards/${id}`, {
+ ...options,
+ params: getParams(params),
+ }),
+
+ create: (params: GiftCardCreateParams, options?: RequestOptions): Promise<GiftCard> =>
+ this.request<GiftCard>('POST', '/gift_cards', { ...options, body: params }),
+
+ update: (
+ id: string,
+ params: GiftCardUpdateParams,
+ options?: RequestOptions,
+ ): Promise<GiftCard> =>
+ this.request<GiftCard>('PATCH', `/gift_cards/${id}`, { ...options, body: params }),
+
+ delete: (id: string, options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', `/gift_cards/${id}`, options),
+ }
+
+ // ============================================
+ // Gift card batches (bulk issuance)
+ // ============================================
+
+ /**
+ * Bulk-issue gift cards in groups of `codes_count`. The server generates
+ * codes inline for batches up to `Spree.config.gift_card_batch_web_limit`
+ * (default 500); larger batches enqueue a background job. The
+ * SPA-facing list view filters cards by batch through
+ * `/gift_cards?q[gift_card_batch_id_eq]=…`.
+ */
+ readonly giftCardBatches = {
+ list: (
+ params?: ListParams & Record<string, unknown>,
+ options?: RequestOptions,
+ ): Promise<PaginatedResponse<GiftCardBatch>> =>
+ this.request<PaginatedResponse<GiftCardBatch>>('GET', '/gift_card_batches', {
+ ...options,
+ params: params ? transformListParams(params) : undefined,
+ }),
+
+ get: (id: string, options?: RequestOptions): Promise<GiftCardBatch> =>
+ this.request<GiftCardBatch>('GET', `/gift_card_batches/${id}`, options),
+
+ create: (params: GiftCardBatchCreateParams, options?: RequestOptions): Promise<GiftCardBatch> =>
+ this.request<GiftCardBatch>('POST', '/gift_card_batches', { ...options, body: params }),
+ }
+
// ============================================
// Exports (CSV: products, orders, customers, …)
// ============================================
diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.ts
index b1c1a83e60..356d66d8d3 100644
--- a/packages/admin-sdk/src/params.ts
+++ b/packages/admin-sdk/src/params.ts
@@ -152,6 +152,39 @@ export interface GiftCardApplyParams {
code: string
}
+/**
+ * Admin-issued gift card. `code` is optional — the server auto-generates
+ * a unique code when omitted. `currency` defaults to the store's currency.
+ * `user_id` (customer prefixed ID) attaches the card to a specific customer.
+ */
+export interface GiftCardCreateParams {
+ amount: string | number
+ currency?: string
+ code?: string
+ expires_at?: string | null
+ user_id?: string | null
+}
+
+export interface GiftCardUpdateParams {
+ amount?: string | number
+ expires_at?: string | null
+ user_id?: string | null
+}
+
+/**
+ * Bulk-issue a `codes_count`-sized batch of gift cards. The server generates
+ * codes by suffixing random hex onto `prefix`. Small batches generate inline;
+ * large ones (over `gift_card_batch_web_limit`, default 500) enqueue a
+ * background job.
+ */
+export interface GiftCardBatchCreateParams {
+ prefix: string
+ amount: string | number
+ codes_count: number
+ currency?: string
+ expires_at?: string | null
+}
+
export interface StoreCreditApplyParams {
amount?: number
}