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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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:examplediff --git a/packages/admin-sdk/examples/gift-cards/get.ts b/packages/admin-sdk/examples/gift-cards/get.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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}