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.

Make the tax and company endpoints reachable from the typed client

Łukasz Adamczykd89eeace52f3
diff --git a/packages/admin-sdk/examples/companies/create.ts b/packages/admin-sdk/examples/companies/create.ts
new file mode 100644
index 0000000000..9baaadf39e
--- /dev/null
+++ b/packages/admin-sdk/examples/companies/create.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 company = await client.companies.create({
+ name: 'Globex Corporation',
+ external_id: 'GLBX-42',
+})
+
+// endregion:example
+
+export { company }
diff --git a/packages/admin-sdk/examples/companies/list.ts b/packages/admin-sdk/examples/companies/list.ts
new file mode 100644
index 0000000000..8ca8cc3817
--- /dev/null
+++ b/packages/admin-sdk/examples/companies/list.ts
@@ -0,0 +1,13 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+const { data: companies } = await client.companies.list({ name_cont: 'Acme' })
+
+// endregion:example
+
+export { companies }
diff --git a/packages/admin-sdk/examples/companies/locations-create.ts b/packages/admin-sdk/examples/companies/locations-create.ts
new file mode 100644
index 0000000000..eec70fb221
--- /dev/null
+++ b/packages/admin-sdk/examples/companies/locations-create.ts
@@ -0,0 +1,23 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+const location = await client.companies.locations.create('comp_UkLWZg9DAJ', {
+ name: 'Hamburg warehouse',
+ billing_address: {
+ first_name: 'Anna',
+ last_name: 'Muller',
+ address1: 'Hafenstr 1',
+ city: 'Hamburg',
+ postal_code: '20095',
+ country_iso: 'DE',
+ },
+})
+
+// endregion:example
+
+export { location }
diff --git a/packages/admin-sdk/examples/companies/locations-list.ts b/packages/admin-sdk/examples/companies/locations-list.ts
new file mode 100644
index 0000000000..fa6256ed12
--- /dev/null
+++ b/packages/admin-sdk/examples/companies/locations-list.ts
@@ -0,0 +1,13 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+const { data: locations } = await client.companies.locations.list('comp_UkLWZg9DAJ')
+
+// endregion:example
+
+export { locations }
diff --git a/packages/admin-sdk/examples/company-contacts/delete.ts b/packages/admin-sdk/examples/company-contacts/delete.ts
new file mode 100644
index 0000000000..57cb9d7dd1
--- /dev/null
+++ b/packages/admin-sdk/examples/company-contacts/delete.ts
@@ -0,0 +1,11 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+// Withdraws the buyer's authority; the customer account is untouched.
+await client.companyContacts.delete('cc_UkLWZg9DAJ')
+// endregion:example
diff --git a/packages/admin-sdk/examples/company-contacts/get.ts b/packages/admin-sdk/examples/company-contacts/get.ts
new file mode 100644
index 0000000000..f656adbcbc
--- /dev/null
+++ b/packages/admin-sdk/examples/company-contacts/get.ts
@@ -0,0 +1,13 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+const contact = await client.companyContacts.get('cc_UkLWZg9DAJ')
+
+// endregion:example
+
+export { contact }
diff --git a/packages/admin-sdk/examples/company-locations/contacts-create.ts b/packages/admin-sdk/examples/company-locations/contacts-create.ts
new file mode 100644
index 0000000000..96cadcda57
--- /dev/null
+++ b/packages/admin-sdk/examples/company-locations/contacts-create.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 contact = await client.companyLocations.contacts.create('cloc_UkLWZg9DAJ', {
+ customer_id: 'cus_UkLWZg9DAJ',
+ role: 'buyer',
+})
+
+// endregion:example
+
+export { contact }
diff --git a/packages/admin-sdk/examples/company-locations/contacts-list.ts b/packages/admin-sdk/examples/company-locations/contacts-list.ts
new file mode 100644
index 0000000000..599ce62c1a
--- /dev/null
+++ b/packages/admin-sdk/examples/company-locations/contacts-list.ts
@@ -0,0 +1,13 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+const { data: contacts } = await client.companyLocations.contacts.list('cloc_UkLWZg9DAJ')
+
+// endregion:example
+
+export { contacts }
diff --git a/packages/admin-sdk/examples/company-locations/delete.ts b/packages/admin-sdk/examples/company-locations/delete.ts
new file mode 100644
index 0000000000..d1b817c296
--- /dev/null
+++ b/packages/admin-sdk/examples/company-locations/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.companyLocations.delete('cloc_UkLWZg9DAJ')
+// endregion:example
diff --git a/packages/admin-sdk/examples/company-locations/get.ts b/packages/admin-sdk/examples/company-locations/get.ts
new file mode 100644
index 0000000000..6aca3269a4
--- /dev/null
+++ b/packages/admin-sdk/examples/company-locations/get.ts
@@ -0,0 +1,13 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+const location = await client.companyLocations.get('cloc_UkLWZg9DAJ')
+
+// endregion:example
+
+export { location }
diff --git a/packages/admin-sdk/examples/company-locations/update.ts b/packages/admin-sdk/examples/company-locations/update.ts
new file mode 100644
index 0000000000..f032a41ad0
--- /dev/null
+++ b/packages/admin-sdk/examples/company-locations/update.ts
@@ -0,0 +1,17 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+// Address fields edit the branch's existing address in place.
+const location = await client.companyLocations.update('cloc_UkLWZg9DAJ', {
+ name: 'Berlin Mitte',
+ billing_address: { city: 'Berlin' },
+})
+
+// endregion:example
+
+export { location }
diff --git a/packages/admin-sdk/examples/company-tax-identifiers/create.ts b/packages/admin-sdk/examples/company-tax-identifiers/create.ts
new file mode 100644
index 0000000000..35501c2c47
--- /dev/null
+++ b/packages/admin-sdk/examples/company-tax-identifiers/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
+// A business registration outranks the buyer's own when the sale is for that business.
+const registration = await client.companies.taxIdentifiers.create('comp_UkLWZg9DAJ', {
+ kind: 'eu_vat',
+ value: 'DE123456789',
+})
+
+// endregion:example
+
+export { registration }
diff --git a/packages/admin-sdk/examples/company-tax-identifiers/list.ts b/packages/admin-sdk/examples/company-tax-identifiers/list.ts
new file mode 100644
index 0000000000..aa8c947f53
--- /dev/null
+++ b/packages/admin-sdk/examples/company-tax-identifiers/list.ts
@@ -0,0 +1,13 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+const { data: registrations } = await client.companies.taxIdentifiers.list('comp_UkLWZg9DAJ')
+
+// endregion:example
+
+export { registrations }
diff --git a/packages/admin-sdk/examples/company-tax-identifiers/validate.ts b/packages/admin-sdk/examples/company-tax-identifiers/validate.ts
new file mode 100644
index 0000000000..94328ef354
--- /dev/null
+++ b/packages/admin-sdk/examples/company-tax-identifiers/validate.ts
@@ -0,0 +1,18 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+// A registry answers only "valid now", so a number verified last year may
+// have been deregistered since. The check is queued; poll for the verdict.
+const registration = await client.companies.taxIdentifiers.validate(
+ 'comp_UkLWZg9DAJ',
+ 'txi_UkLWZg9DAJ',
+)
+
+// endregion:example
+
+export { registration }
diff --git a/packages/admin-sdk/examples/tax-exemption-certificates/create.ts b/packages/admin-sdk/examples/tax-exemption-certificates/create.ts
new file mode 100644
index 0000000000..3f4b5505f6
--- /dev/null
+++ b/packages/admin-sdk/examples/tax-exemption-certificates/create.ts
@@ -0,0 +1,28 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+// Upload the document first, then pass the signed id.
+const { signed_id } = await client.directUploads.create({
+ blob: {
+ filename: 'resale.pdf',
+ byte_size: 18_345,
+ checksum: 'Base64EncodedMD5==',
+ content_type: 'application/pdf',
+ },
+})
+
+const certificate = await client.companies.taxExemptionCertificates.create('comp_UkLWZg9DAJ', {
+ certificate_number: 'DE-RESALE-7',
+ reason_code: 'resale',
+ country_iso: 'DE',
+ document: signed_id,
+})
+
+// endregion:example
+
+export { certificate }
diff --git a/packages/admin-sdk/examples/tax-exemption-certificates/list.ts b/packages/admin-sdk/examples/tax-exemption-certificates/list.ts
new file mode 100644
index 0000000000..12993cc27a
--- /dev/null
+++ b/packages/admin-sdk/examples/tax-exemption-certificates/list.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 { data: certificates } =
+ await client.companies.taxExemptionCertificates.list('comp_UkLWZg9DAJ')
+
+// `active` — not `status` — answers whether one exempts a sale: a verified
+// certificate stops counting once its expiry date passes.
+const applying = certificates.filter((certificate) => certificate.active)
+
+// endregion:example
+
+export { applying, certificates }
diff --git a/packages/admin-sdk/examples/tax-exemption-certificates/revoke.ts b/packages/admin-sdk/examples/tax-exemption-certificates/revoke.ts
new file mode 100644
index 0000000000..f8278e7a90
--- /dev/null
+++ b/packages/admin-sdk/examples/tax-exemption-certificates/revoke.ts
@@ -0,0 +1,18 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+// A verified certificate cannot be deleted — how a sale was taxed has to stay
+// explainable — so revoking is the way out.
+const certificate = await client.companies.taxExemptionCertificates.revoke(
+ 'comp_UkLWZg9DAJ',
+ 'cert_UkLWZg9DAJ',
+)
+
+// endregion:example
+
+export { certificate }
diff --git a/packages/admin-sdk/examples/tax-exemption-certificates/verify.ts b/packages/admin-sdk/examples/tax-exemption-certificates/verify.ts
new file mode 100644
index 0000000000..46e0ec929a
--- /dev/null
+++ b/packages/admin-sdk/examples/tax-exemption-certificates/verify.ts
@@ -0,0 +1,18 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+// Accepting is what makes a certificate exempt sales. Only a pending one can
+// be accepted, and an installation's own checks can refuse here.
+const certificate = await client.companies.taxExemptionCertificates.verify(
+ 'comp_UkLWZg9DAJ',
+ 'cert_UkLWZg9DAJ',
+)
+
+// endregion:example
+
+export { certificate }
diff --git a/packages/admin-sdk/examples/tax-rates/create.ts b/packages/admin-sdk/examples/tax-rates/create.ts
new file mode 100644
index 0000000000..ac17926886
--- /dev/null
+++ b/packages/admin-sdk/examples/tax-rates/create.ts
@@ -0,0 +1,20 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+// A rate names the jurisdiction it applies to; one naming no country taxes everywhere.
+const taxRate = await client.taxRates.create({
+ name: 'German VAT',
+ amount: 0.19,
+ country_iso: 'DE',
+ tax_category_id: 'txc_UkLWZg9DAJ',
+ included_in_price: true,
+})
+
+// endregion:example
+
+export { taxRate }
diff --git a/packages/admin-sdk/examples/tax-rates/list.ts b/packages/admin-sdk/examples/tax-rates/list.ts
new file mode 100644
index 0000000000..9cf50ef6cd
--- /dev/null
+++ b/packages/admin-sdk/examples/tax-rates/list.ts
@@ -0,0 +1,13 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+const { data: taxRates } = await client.taxRates.list({ country_iso_eq: 'DE' })
+
+// endregion:example
+
+export { taxRates }
diff --git a/packages/admin-sdk/src/admin-client.ts b/packages/admin-sdk/src/admin-client.ts
index 2030a8eb53..e0c382d5de 100644
--- a/packages/admin-sdk/src/admin-client.ts
+++ b/packages/admin-sdk/src/admin-client.ts
@@ -107,6 +107,9 @@ import type {
CollectionCreateParams,
CollectionProductRepositionParams,
CollectionUpdateParams,
+ CompanyContactParams,
+ CompanyLocationParams,
+ CompanyParams,
CustomerAddressParams,
CustomerCreateParams,
CustomerGroupCreateParams,
@@ -192,6 +195,9 @@ import type {
StoreUpdateParams,
TaxCategoryCreateParams,
TaxCategoryUpdateParams,
+ TaxExemptionCertificateParams,
+ TaxIdentifierParams,
+ TaxRateParams,
VariantCreateParams,
VariantUpdateParams,
WebhookEndpointCreateParams,
@@ -208,6 +214,9 @@ import type {
Claim,
ClaimReason,
Collection,
+ Company,
+ CompanyContact,
+ CompanyLocation,
Country,
CouponCode,
CreditCard,
@@ -259,7 +268,10 @@ import type {
StoreCredit,
StoreCreditCategory,
TaxCategory,
+ TaxExemptionCertificate,
+ TaxIdentifier,
TaxLine,
+ TaxRate,
TranslatableResource,
TranslationBatchEntry,
Variant,
@@ -2207,6 +2219,349 @@ export class AdminClient {
this.request<GiftCardBatch>('POST', '/gift_card_batches', { ...options, body: params }),
}
+ // ============================================
+ // Tax configuration
+ // ============================================
+
+ /**
+ * Tax rates for the built-in engine. A rate names the jurisdiction it
+ * applies to — a country and optionally one of its states — rather than a
+ * zone; one naming no country taxes everywhere.
+ */
+ readonly taxRates = {
+ list: (
+ params?: ListParams & Record<string, unknown>,
+ options?: RequestOptions,
+ ): Promise<PaginatedResponse<TaxRate>> =>
+ this.request<PaginatedResponse<TaxRate>>('GET', '/tax_rates', {
+ ...options,
+ params: params ? transformListParams(params) : undefined,
+ }),
+
+ get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<TaxRate> =>
+ this.request<TaxRate>('GET', `/tax_rates/${id}`, { ...options, params: getParams(params) }),
+
+ create: (params: TaxRateParams, options?: RequestOptions): Promise<TaxRate> =>
+ this.request<TaxRate>('POST', '/tax_rates', { ...options, body: params }),
+
+ update: (id: string, params: TaxRateParams, options?: RequestOptions): Promise<TaxRate> =>
+ this.request<TaxRate>('PATCH', `/tax_rates/${id}`, { ...options, body: params }),
+
+ delete: (id: string, options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', `/tax_rates/${id}`, options),
+ }
+
+ /**
+ * The tax engines this installation has available, each declaring the
+ * domains it cannot handle — so a dashboard can warn that pairing the
+ * built-in engine with a US market means no local sales tax, rather than
+ * letting a merchant discover it at checkout.
+ */
+ readonly taxProviders = {
+ list: (options?: RequestOptions): Promise<PaginatedResponse<Record<string, unknown>>> =>
+ this.request<PaginatedResponse<Record<string, unknown>>>('GET', '/tax_providers', options),
+ }
+
+ // ============================================
+ // Companies (business customers)
+ // ============================================
+
+ /**
+ * Business customers, their branches and the buyers authorised to purchase
+ * for each. A company holds the tax registration that goes on its invoices
+ * and the exemption certificates that decide whether its purchases are
+ * taxed; a sale points at a branch, and the company follows from it.
+ *
+ * Branches and buyers are listed and created under their parent, then read
+ * and written by their own id via `companyLocations` and `companyContacts` —
+ * nesting a buyer under both a company and a branch would exceed the API's
+ * two-level limit.
+ */
+ readonly companies = {
+ list: (
+ params?: ListParams & Record<string, unknown>,
+ options?: RequestOptions,
+ ): Promise<PaginatedResponse<Company>> =>
+ this.request<PaginatedResponse<Company>>('GET', '/companies', {
+ ...options,
+ params: params ? transformListParams(params) : undefined,
+ }),
+
+ get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Company> =>
+ this.request<Company>('GET', `/companies/${id}`, { ...options, params: getParams(params) }),
+
+ create: (params: CompanyParams, options?: RequestOptions): Promise<Company> =>
+ this.request<Company>('POST', '/companies', { ...options, body: params }),
+
+ update: (id: string, params: CompanyParams, options?: RequestOptions): Promise<Company> =>
+ this.request<Company>('PATCH', `/companies/${id}`, { ...options, body: params }),
+
+ delete: (id: string, options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', `/companies/${id}`, options),
+
+ locations: {
+ list: (
+ companyId: string,
+ params?: ListParams & Record<string, unknown>,
+ options?: RequestOptions,
+ ): Promise<PaginatedResponse<CompanyLocation>> =>
+ this.request<PaginatedResponse<CompanyLocation>>(
+ 'GET',
+ `/companies/${companyId}/locations`,
+ {
+ ...options,
+ params: params ? transformListParams(params) : undefined,
+ },
+ ),
+
+ create: (
+ companyId: string,
+ params: CompanyLocationParams,
+ options?: RequestOptions,
+ ): Promise<CompanyLocation> =>
+ this.request<CompanyLocation>('POST', `/companies/${companyId}/locations`, {
+ ...options,
+ body: params,
+ }),
+ },
+
+ /**
+ * The business's own tax registrations, one per kind. A company
+ * registration takes precedence over the buyer's own when a sale is for
+ * that business, because the invoice is addressed to the entity rather
+ * than the person who placed the order.
+ */
+ taxIdentifiers: {
+ list: (
+ companyId: string,
+ params?: ListParams & Record<string, unknown>,
+ options?: RequestOptions,
+ ): Promise<PaginatedResponse<TaxIdentifier>> =>
+ this.request<PaginatedResponse<TaxIdentifier>>(
+ 'GET',
+ `/companies/${companyId}/tax_identifiers`,
+ {
+ ...options,
+ params: params ? transformListParams(params) : undefined,
+ },
+ ),
+
+ get: (companyId: string, id: string, options?: RequestOptions): Promise<TaxIdentifier> =>
+ this.request<TaxIdentifier>(
+ 'GET',
+ `/companies/${companyId}/tax_identifiers/${id}`,
+ options,
+ ),
+
+ create: (
+ companyId: string,
+ params: TaxIdentifierParams,
+ options?: RequestOptions,
+ ): Promise<TaxIdentifier> =>
+ this.request<TaxIdentifier>('POST', `/companies/${companyId}/tax_identifiers`, {
+ ...options,
+ body: params,
+ }),
+
+ update: (
+ companyId: string,
+ id: string,
+ params: TaxIdentifierParams,
+ options?: RequestOptions,
+ ): Promise<TaxIdentifier> =>
+ this.request<TaxIdentifier>('PATCH', `/companies/${companyId}/tax_identifiers/${id}`, {
+ ...options,
+ body: params,
+ }),
+
+ delete: (companyId: string, id: string, options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', `/companies/${companyId}/tax_identifiers/${id}`, options),
+
+ /**
+ * Asks the registry again. A registry answers only "valid now", so a
+ * number verified last year may have been deregistered since. Returns
+ * `202` with the check queued.
+ */
+ validate: (companyId: string, id: string, options?: RequestOptions): Promise<TaxIdentifier> =>
+ this.request<TaxIdentifier>(
+ 'POST',
+ `/companies/${companyId}/tax_identifiers/${id}/validate`,
+ options,
+ ),
+ },
+
+ /**
+ * Exemption evidence. Certificates start `pending` and exempt nothing
+ * until verified; `active` — not `status` — answers whether one exempts a
+ * sale, since a verified certificate stops counting once its expiry date
+ * passes.
+ *
+ * Upload the document via `directUploads.create()` first and pass the
+ * returned `signed_id` as `document`. To read it back, fetch
+ * `document_url` with the `Authorization` header and drive the browser
+ * download from a Blob — the bytes are streamed through the API rather
+ * than served from storage, so a top-level navigation carrying no JWT
+ * will not work.
+ */
+ taxExemptionCertificates: {
+ list: (
+ companyId: string,
+ params?: ListParams & Record<string, unknown>,
+ options?: RequestOptions,
+ ): Promise<PaginatedResponse<TaxExemptionCertificate>> =>
+ this.request<PaginatedResponse<TaxExemptionCertificate>>(
+ 'GET',
+ `/companies/${companyId}/tax_exemption_certificates`,
+ { ...options, params: params ? transformListParams(params) : undefined },
+ ),
+
+ get: (
+ companyId: string,
+ id: string,
+ params?: { expand?: string[] },
+ options?: RequestOptions,
+ ): Promise<TaxExemptionCertificate> =>
+ this.request<TaxExemptionCertificate>(
+ 'GET',
+ `/companies/${companyId}/tax_exemption_certificates/${id}`,
+ { ...options, params: getParams(params) },
+ ),
+
+ create: (
+ companyId: string,
+ params: TaxExemptionCertificateParams,
+ options?: RequestOptions,
+ ): Promise<TaxExemptionCertificate> =>
+ this.request<TaxExemptionCertificate>(
+ 'POST',
+ `/companies/${companyId}/tax_exemption_certificates`,
+ { ...options, body: params },
+ ),
+
+ update: (
+ companyId: string,
+ id: string,
+ params: TaxExemptionCertificateParams,
+ options?: RequestOptions,
+ ): Promise<TaxExemptionCertificate> =>
+ this.request<TaxExemptionCertificate>(
+ 'PATCH',
+ `/companies/${companyId}/tax_exemption_certificates/${id}`,
+ { ...options, body: params },
+ ),
+
+ /**
+ * Accepts the certificate, which is what makes it exempt sales. Only a
+ * pending certificate can be accepted. An installation that checks
+ * numbers against a registry, or requires a second approval, can refuse
+ * here — the refusal arrives as a validation error.
+ */
+ verify: (
+ companyId: string,
+ id: string,
+ options?: RequestOptions,
+ ): Promise<TaxExemptionCertificate> =>
+ this.request<TaxExemptionCertificate>(
+ 'PATCH',
+ `/companies/${companyId}/tax_exemption_certificates/${id}/verify`,
+ options,
+ ),
+
+ /**
+ * Withdraws accepted evidence. A verified certificate cannot be deleted
+ * — how a sale was taxed has to stay explainable — so this is the way
+ * out.
+ */
+ revoke: (
+ companyId: string,
+ id: string,
+ options?: RequestOptions,
+ ): Promise<TaxExemptionCertificate> =>
+ this.request<TaxExemptionCertificate>(
+ 'PATCH',
+ `/companies/${companyId}/tax_exemption_certificates/${id}/revoke`,
+ options,
+ ),
+
+ /** Only a certificate still awaiting a decision can be deleted. */
+ delete: (companyId: string, id: string, options?: RequestOptions): Promise<void> =>
+ this.request<void>(
+ 'DELETE',
+ `/companies/${companyId}/tax_exemption_certificates/${id}`,
+ options,
+ ),
+ },
+ }
+
+ /** Branches addressed by their own id, with the buyers who purchase for them. */
+ readonly companyLocations = {
+ get: (
+ id: string,
+ params?: { expand?: string[] },
+ options?: RequestOptions,
+ ): Promise<CompanyLocation> =>
+ this.request<CompanyLocation>('GET', `/company_locations/${id}`, {
+ ...options,
+ params: getParams(params),
+ }),
+
+ /**
+ * Address fields sent here edit the branch's existing address in place, so
+ * send only what changes.
+ */
+ update: (
+ id: string,
+ params: CompanyLocationParams,
+ options?: RequestOptions,
+ ): Promise<CompanyLocation> =>
+ this.request<CompanyLocation>('PATCH', `/company_locations/${id}`, {
+ ...options,
+ body: params,
+ }),
+
+ /** Removes the branch, its buyers and the addresses it owned. */
+ delete: (id: string, options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', `/company_locations/${id}`, options),
+
+ contacts: {
+ list: (
+ companyLocationId: string,
+ params?: ListParams & Record<string, unknown>,
+ options?: RequestOptions,
+ ): Promise<PaginatedResponse<CompanyContact>> =>
+ this.request<PaginatedResponse<CompanyContact>>(
+ 'GET',
+ `/company_locations/${companyLocationId}/contacts`,
+ { ...options, params: params ? transformListParams(params) : undefined },
+ ),
+
+ /**
+ * Authorises a customer to purchase for a branch. A customer acting for
+ * exactly one branch has their orders attributed to it automatically;
+ * one acting for several needs the branch set on the order, because
+ * guessing would invoice the wrong business.
+ */
+ create: (
+ companyLocationId: string,
+ params: CompanyContactParams,
+ options?: RequestOptions,
+ ): Promise<CompanyContact> =>
+ this.request<CompanyContact>('POST', `/company_locations/${companyLocationId}/contacts`, {
+ ...options,
+ body: params,
+ }),
+ },
+ }
+
+ readonly companyContacts = {
+ get: (id: string, options?: RequestOptions): Promise<CompanyContact> =>
+ this.request<CompanyContact>('GET', `/company_contacts/${id}`, options),
+
+ /** Withdraws the buyer's authority. The customer account is untouched. */
+ delete: (id: string, options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', `/company_contacts/${id}`, options),
+ }
+
// ============================================
// Exports (CSV: products, orders, customers, …)
// ============================================
diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.ts
index ac6a6d08f6..ea8285ea79 100644
--- a/packages/admin-sdk/src/params.ts
+++ b/packages/admin-sdk/src/params.ts
@@ -1682,3 +1682,74 @@ export interface DeliveryZoneParams {
/** Replaces the zone's full member set atomically. */
members?: DeliveryZoneMemberParams[]
}
+
+export interface CompanyParams {
+ name?: string
+ /** Your own reference for this business, unique within the store. */
+ external_id?: string | null
+ metadata?: Record<string, unknown>
+}
+
+/** Addresses are created inline and owned by the branch. */
+export interface CompanyLocationAddressParams {
+ first_name?: string
+ last_name?: string
+ company?: string
+ address1?: string
+ address2?: string
+ city?: string
+ postal_code?: string
+ zipcode?: string
+ phone?: string
+ country_iso?: string
+ state_abbr?: string
+ state_name?: string
+ label?: string
+}
+
+export interface CompanyLocationParams {
+ name?: string
+ external_id?: string | null
+ billing_address?: CompanyLocationAddressParams
+ shipping_address?: CompanyLocationAddressParams
+ metadata?: Record<string, unknown>
+}
+
+export interface CompanyContactParams {
+ customer_id?: string
+ /** Free-form label; carries no permissions. */
+ role?: string
+}
+
+export interface TaxIdentifierParams {
+ /** The regime the number belongs to, e.g. `eu_vat`, `gb_vat`. */
+ kind?: string
+ value?: string
+}
+
+export interface TaxExemptionCertificateParams {
+ certificate_number?: string
+ /** Becomes the tax provider's entity use code, e.g. `resale`. */
+ reason_code?: string
+ /** Where the certificate holds. Omit both for one valid everywhere. */
+ country_iso?: string | null
+ state_code?: string | null
+ issued_at?: string | null
+ expires_at?: string | null
+ issuing_authority?: string | null
+ /** ActiveStorage signed blob id from `directUploads.create()`. */
+ document?: string
+ metadata?: Record<string, unknown>
+}
+
+export interface TaxRateParams {
+ name?: string
+ amount?: number | string
+ /** Where the rate applies. A rate naming no country taxes everywhere. */
+ country_iso?: string | null
+ state_code?: string | null
+ tax_category_id?: string
+ included_in_price?: boolean
+ show_rate_in_label?: boolean
+ calculator_type?: string
+}
diff --git a/packages/admin-sdk/src/types/generated/Order.ts b/packages/admin-sdk/src/types/generated/Order.ts
index 99b2103f13..d2822bdbca 100644
--- a/packages/admin-sdk/src/types/generated/Order.ts
+++ b/packages/admin-sdk/src/types/generated/Order.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 2367359de0e1fef1d82e130df6c964a9
+// Typelizer digest 8774fcb5d4c850b70bcaa90661e0bd01
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {LineItem, Fulfillment, Payment, Address, GiftCard, Market, AppliedPromotion, Cart, Channel, StockLocation, PaymentMethod, Customer, Return, Exchange, Claim} from '@/types'
@@ -61,6 +61,8 @@ interface Order {
created_at: string;
updated_at: string;
preferred_stock_location_id: string | null;
+ company_location_id: string | null;
+ company_id: string | null;
tags: Array<string>;
internal_note: string | null;
approver_id: string | null;
diff --git a/packages/admin-sdk/src/types/index.ts b/packages/admin-sdk/src/types/index.ts
index 6a0760facf..2b1773808a 100644
--- a/packages/admin-sdk/src/types/index.ts
+++ b/packages/admin-sdk/src/types/index.ts
@@ -22,6 +22,9 @@ export type { default as ClaimLineItem } from './generated/ClaimLineItem'
export type { default as ClaimReason } from './generated/ClaimReason'
export type { default as Collection } from './generated/Collection'
export type { default as CollectionRule } from './generated/CollectionRule'
+export type { default as Company } from './generated/Company'
+export type { default as CompanyContact } from './generated/CompanyContact'
+export type { default as CompanyLocation } from './generated/CompanyLocation'
export type { default as Country } from './generated/Country'
export type { default as CouponCode } from './generated/CouponCode'
export type { default as CreditCard } from './generated/CreditCard'
@@ -84,7 +87,10 @@ export type { default as Store } from './generated/Store'
export type { default as StoreCredit } from './generated/StoreCredit'
export type { default as StoreCreditCategory } from './generated/StoreCreditCategory'
export type { default as TaxCategory } from './generated/TaxCategory'
+export type { default as TaxExemptionCertificate } from './generated/TaxExemptionCertificate'
+export type { default as TaxIdentifier } from './generated/TaxIdentifier'
export type { default as TaxLine } from './generated/TaxLine'
+export type { default as TaxRate } from './generated/TaxRate'
export type { default as Variant } from './generated/Variant'
export type { default as WebhookDelivery } from './generated/WebhookDelivery'
export type { default as WebhookEndpoint } from './generated/WebhookEndpoint'
diff --git a/packages/admin-sdk/tests/companies.test.ts b/packages/admin-sdk/tests/companies.test.ts
new file mode 100644
index 0000000000..255d0fe9b1
--- /dev/null
+++ b/packages/admin-sdk/tests/companies.test.ts
@@ -0,0 +1,272 @@
+import { HttpResponse, http } from 'msw'
+import { describe, expect, it } from 'vitest'
+import { API_PREFIX, createTestClient, paginated } from './helpers'
+import { server } from './mocks/server'
+
+const sampleCompany = {
+ id: 'comp_abc123',
+ name: 'Acme Industrial',
+ external_id: 'ACME-1',
+ locations_count: 2,
+ metadata: {},
+ created_at: '2026-08-01T00:00:00Z',
+ updated_at: '2026-08-01T00:00:00Z',
+}
+
+const sampleLocation = {
+ id: 'cloc_abc123',
+ company_id: 'comp_abc123',
+ name: 'Berlin',
+ external_id: null,
+ contacts_count: 1,
+ billing_address: null,
+ shipping_address: null,
+ metadata: {},
+ created_at: '2026-08-01T00:00:00Z',
+ updated_at: '2026-08-01T00:00:00Z',
+}
+
+const sampleCertificate = {
+ id: 'cert_abc123',
+ company_id: 'comp_abc123',
+ certificate_number: 'DE-RESALE-1',
+ reason_code: 'resale',
+ status: 'pending',
+ country_iso: 'DE',
+ state_code: null,
+ active: false,
+ lapsed: false,
+ can_be_deleted: true,
+ document_filename: null,
+ document_byte_size: null,
+ document_url: null,
+ metadata: {},
+ created_at: '2026-08-01T00:00:00Z',
+ updated_at: '2026-08-01T00:00:00Z',
+}
+
+describe('companies', () => {
+ it('lists companies and wraps Ransack predicates', async () => {
+ let url: URL | null = null
+ server.use(
+ http.get(`${API_PREFIX}/companies`, ({ request }) => {
+ url = new URL(request.url)
+ return HttpResponse.json(paginated([sampleCompany]))
+ }),
+ )
+
+ const res = await createTestClient().companies.list({ name_cont: 'Acme' })
+
+ expect(res.data[0]?.id).toBe('comp_abc123')
+ expect(url!.searchParams.get('q[name_cont]')).toBe('Acme')
+ })
+
+ it('creates, updates and deletes a company', async () => {
+ let created: Record<string, unknown> | null = null
+ let patched: Record<string, unknown> | null = null
+ let deleted = false
+ server.use(
+ http.post(`${API_PREFIX}/companies`, async ({ request }) => {
+ created = (await request.json()) as Record<string, unknown>
+ return HttpResponse.json(sampleCompany, { status: 201 })
+ }),
+ http.patch(`${API_PREFIX}/companies/comp_abc123`, async ({ request }) => {
+ patched = (await request.json()) as Record<string, unknown>
+ return HttpResponse.json(sampleCompany)
+ }),
+ http.delete(`${API_PREFIX}/companies/comp_abc123`, () => {
+ deleted = true
+ return new HttpResponse(null, { status: 204 })
+ }),
+ )
+
+ const client = createTestClient()
+ await client.companies.create({ name: 'Globex Corporation', external_id: 'GLBX' })
+ await client.companies.update('comp_abc123', { name: 'Acme Global' })
+ await client.companies.delete('comp_abc123')
+
+ expect(created).toEqual({ name: 'Globex Corporation', external_id: 'GLBX' })
+ expect(patched).toEqual({ name: 'Acme Global' })
+ expect(deleted).toBe(true)
+ })
+
+ describe('locations', () => {
+ it('lists and creates under the company', async () => {
+ let body: Record<string, unknown> | null = null
+ server.use(
+ http.get(`${API_PREFIX}/companies/comp_abc123/locations`, () =>
+ HttpResponse.json(paginated([sampleLocation])),
+ ),
+ http.post(`${API_PREFIX}/companies/comp_abc123/locations`, async ({ request }) => {
+ body = (await request.json()) as Record<string, unknown>
+ return HttpResponse.json(sampleLocation, { status: 201 })
+ }),
+ )
+
+ const client = createTestClient()
+ const listed = await client.companies.locations.list('comp_abc123')
+ await client.companies.locations.create('comp_abc123', {
+ name: 'Hamburg',
+ billing_address: { city: 'Hamburg', country_iso: 'DE' },
+ })
+
+ expect(listed.data[0]?.id).toBe('cloc_abc123')
+ expect(body).toEqual({
+ name: 'Hamburg',
+ billing_address: { city: 'Hamburg', country_iso: 'DE' },
+ })
+ })
+
+ // Reads and member writes go by the branch's own id, not through the company.
+ it('reads, updates and deletes by its own id', async () => {
+ let patched: Record<string, unknown> | null = null
+ server.use(
+ http.get(`${API_PREFIX}/company_locations/cloc_abc123`, () =>
+ HttpResponse.json(sampleLocation),
+ ),
+ http.patch(`${API_PREFIX}/company_locations/cloc_abc123`, async ({ request }) => {
+ patched = (await request.json()) as Record<string, unknown>
+ return HttpResponse.json(sampleLocation)
+ }),
+ http.delete(
+ `${API_PREFIX}/company_locations/cloc_abc123`,
+ () => new HttpResponse(null, { status: 204 }),
+ ),
+ )
+
+ const client = createTestClient()
+ expect((await client.companyLocations.get('cloc_abc123')).name).toBe('Berlin')
+ await client.companyLocations.update('cloc_abc123', { billing_address: { city: 'Berlin' } })
+ await expect(client.companyLocations.delete('cloc_abc123')).resolves.toBeUndefined()
+
+ expect(patched).toEqual({ billing_address: { city: 'Berlin' } })
+ })
+ })
+
+ describe('contacts', () => {
+ it('lists and creates under the branch, deletes by its own id', async () => {
+ let body: Record<string, unknown> | null = null
+ const contact = {
+ id: 'cc_abc123',
+ company_location_id: 'cloc_abc123',
+ customer_id: 'cus_1',
+ role: 'buyer',
+ email: '[email protected]',
+ created_at: '',
+ updated_at: '',
+ }
+ server.use(
+ http.get(`${API_PREFIX}/company_locations/cloc_abc123/contacts`, () =>
+ HttpResponse.json(paginated([contact])),
+ ),
+ http.post(`${API_PREFIX}/company_locations/cloc_abc123/contacts`, async ({ request }) => {
+ body = (await request.json()) as Record<string, unknown>
+ return HttpResponse.json(contact, { status: 201 })
+ }),
+ http.delete(
+ `${API_PREFIX}/company_contacts/cc_abc123`,
+ () => new HttpResponse(null, { status: 204 }),
+ ),
+ )
+
+ const client = createTestClient()
+ const listed = await client.companyLocations.contacts.list('cloc_abc123')
+ await client.companyLocations.contacts.create('cloc_abc123', { customer_id: 'cus_1' })
+ await expect(client.companyContacts.delete('cc_abc123')).resolves.toBeUndefined()
+
+ expect(listed.data[0]?.email).toBe('[email protected]')
+ expect(body).toEqual({ customer_id: 'cus_1' })
+ })
+ })
+
+ describe('taxIdentifiers', () => {
+ it('registers a number and re-checks it', async () => {
+ let body: Record<string, unknown> | null = null
+ let validated = false
+ const identifier = {
+ id: 'txi_abc123',
+ kind: 'eu_vat',
+ value: 'DE123456789',
+ validation_status: null,
+ created_at: '',
+ updated_at: '',
+ }
+ server.use(
+ http.post(`${API_PREFIX}/companies/comp_abc123/tax_identifiers`, async ({ request }) => {
+ body = (await request.json()) as Record<string, unknown>
+ return HttpResponse.json(identifier, { status: 201 })
+ }),
+ http.post(`${API_PREFIX}/companies/comp_abc123/tax_identifiers/txi_abc123/validate`, () => {
+ validated = true
+ return HttpResponse.json({ ...identifier, validation_status: 'pending' }, { status: 202 })
+ }),
+ )
+
+ const client = createTestClient()
+ await client.companies.taxIdentifiers.create('comp_abc123', {
+ kind: 'eu_vat',
+ value: 'DE123456789',
+ })
+ const rechecked = await client.companies.taxIdentifiers.validate('comp_abc123', 'txi_abc123')
+
+ expect(body).toEqual({ kind: 'eu_vat', value: 'DE123456789' })
+ expect(validated).toBe(true)
+ expect(rechecked.validation_status).toBe('pending')
+ })
+ })
+
+ describe('taxExemptionCertificates', () => {
+ it('creates with a signed document id', async () => {
+ let body: Record<string, unknown> | null = null
+ server.use(
+ http.post(
+ `${API_PREFIX}/companies/comp_abc123/tax_exemption_certificates`,
+ async ({ request }) => {
+ body = (await request.json()) as Record<string, unknown>
+ return HttpResponse.json(sampleCertificate, { status: 201 })
+ },
+ ),
+ )
+
+ await createTestClient().companies.taxExemptionCertificates.create('comp_abc123', {
+ certificate_number: 'DE-RESALE-7',
+ reason_code: 'resale',
+ document: 'signed-blob-id',
+ })
+
+ expect(body).toEqual({
+ certificate_number: 'DE-RESALE-7',
+ reason_code: 'resale',
+ document: 'signed-blob-id',
+ })
+ })
+
+ // Accepting and withdrawing are their own actions, never mass assignment.
+ it('verifies and revokes through member actions', async () => {
+ server.use(
+ http.patch(
+ `${API_PREFIX}/companies/comp_abc123/tax_exemption_certificates/cert_abc123/verify`,
+ () => HttpResponse.json({ ...sampleCertificate, status: 'verified', active: true }),
+ ),
+ http.patch(
+ `${API_PREFIX}/companies/comp_abc123/tax_exemption_certificates/cert_abc123/revoke`,
+ () => HttpResponse.json({ ...sampleCertificate, status: 'revoked' }),
+ ),
+ )
+
+ const client = createTestClient()
+ const verified = await client.companies.taxExemptionCertificates.verify(
+ 'comp_abc123',
+ 'cert_abc123',
+ )
+ const revoked = await client.companies.taxExemptionCertificates.revoke(
+ 'comp_abc123',
+ 'cert_abc123',
+ )
+
+ expect(verified.status).toBe('verified')
+ expect(verified.active).toBe(true)
+ expect(revoked.status).toBe('revoked')
+ })
+ })
+})
diff --git a/packages/admin-sdk/tests/tax-rates.test.ts b/packages/admin-sdk/tests/tax-rates.test.ts
new file mode 100644
index 0000000000..aef3a6644f
--- /dev/null
+++ b/packages/admin-sdk/tests/tax-rates.test.ts
@@ -0,0 +1,80 @@
+import { HttpResponse, http } from 'msw'
+import { describe, expect, it } from 'vitest'
+import { API_PREFIX, createTestClient, paginated } from './helpers'
+import { server } from './mocks/server'
+
+const sampleTaxRate = {
+ id: 'txr_abc123',
+ name: 'German VAT',
+ amount: 0.19,
+ country_iso: 'DE',
+ state_code: null,
+ included_in_price: true,
+ show_rate_in_label: true,
+ created_at: '2026-08-01T00:00:00Z',
+ updated_at: '2026-08-01T00:00:00Z',
+}
+
+describe('taxRates', () => {
+ it('lists rates and wraps Ransack predicates', async () => {
+ let url: URL | null = null
+ server.use(
+ http.get(`${API_PREFIX}/tax_rates`, ({ request }) => {
+ url = new URL(request.url)
+ return HttpResponse.json(paginated([sampleTaxRate]))
+ }),
+ )
+
+ const res = await createTestClient().taxRates.list({ country_iso_eq: 'DE' })
+
+ expect(res.data[0]?.id).toBe('txr_abc123')
+ expect(url!.searchParams.get('q[country_iso_eq]')).toBe('DE')
+ })
+
+ // A rate names its jurisdiction directly rather than pointing at a zone.
+ it('creates a rate against a country and state', async () => {
+ let body: Record<string, unknown> | null = null
+ server.use(
+ http.post(`${API_PREFIX}/tax_rates`, async ({ request }) => {
+ body = (await request.json()) as Record<string, unknown>
+ return HttpResponse.json(sampleTaxRate, { status: 201 })
+ }),
+ )
+
+ await createTestClient().taxRates.create({
+ name: 'California Sales Tax',
+ amount: 0.0825,
+ country_iso: 'US',
+ state_code: 'CA',
+ tax_category_id: 'txc_1',
+ })
+
+ expect(body).toEqual({
+ name: 'California Sales Tax',
+ amount: 0.0825,
+ country_iso: 'US',
+ state_code: 'CA',
+ tax_category_id: 'txc_1',
+ })
+ })
+
+ it('updates and deletes a rate', async () => {
+ let deleted = false
+ server.use(
+ http.patch(`${API_PREFIX}/tax_rates/txr_abc123`, () =>
+ HttpResponse.json({ ...sampleTaxRate, amount: 0.2 }),
+ ),
+ http.delete(`${API_PREFIX}/tax_rates/txr_abc123`, () => {
+ deleted = true
+ return new HttpResponse(null, { status: 204 })
+ }),
+ )
+
+ const client = createTestClient()
+ const updated = await client.taxRates.update('txr_abc123', { amount: 0.2 })
+ await client.taxRates.delete('txr_abc123')
+
+ expect(updated.amount).toBe(0.2)
+ expect(deleted).toBe(true)
+ })
+})
diff --git a/spree/api/spec/integration/spree/api/v3/admin/companies/locations_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/companies/locations_spec.rb
index 74232b1d25..b3b891e343 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/companies/locations_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/companies/locations_spec.rb
@@ -20,6 +20,8 @@ RSpec.describe 'Admin Company Locations API', type: :request, swagger_doc: 'api-
description 'Returns the branches of a business customer. Each branch owns its own addresses and the buyers authorised to purchase for it.'
admin_scope :read, :customers
+ admin_sdk_example 'companies/locations-list'
+
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true
parameter name: :company_id, in: :path, type: :string, required: true
@@ -42,6 +44,8 @@ RSpec.describe 'Admin Company Locations API', type: :request, swagger_doc: 'api-
description 'Creates a branch. Addresses are supplied inline and belong to the branch, so editing one later changes the branch\'s own record rather than an address the buyer also uses.'
admin_scope :write, :customers
+ admin_sdk_example 'companies/locations-create'
+
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true
parameter name: :company_id, in: :path, type: :string, required: true
@@ -104,6 +108,8 @@ RSpec.describe 'Admin Company Locations API', type: :request, swagger_doc: 'api-
description 'Branches are addressed by their own id once you hold one — the company id is not needed.'
admin_scope :read, :customers
+ admin_sdk_example 'company-locations/get'
+
response '200', 'location found' do
run_test! do |response|
expect(JSON.parse(response.body)['name']).to eq('Berlin')
@@ -119,6 +125,8 @@ RSpec.describe 'Admin Company Locations API', type: :request, swagger_doc: 'api-
description 'Address fields sent here edit the branch\'s existing address in place; send only what changes.'
admin_scope :write, :customers
+ admin_sdk_example 'company-locations/update'
+
parameter name: :body, in: :body, schema: {
type: :object,
properties: {
@@ -143,6 +151,8 @@ RSpec.describe 'Admin Company Locations API', type: :request, swagger_doc: 'api-
description 'Removes the branch, its buyers and the addresses it owned.'
admin_scope :write, :customers
+ admin_sdk_example 'company-locations/delete'
+
response '204', 'location deleted' do
run_test!
end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/companies/tax_exemption_certificates_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/companies/tax_exemption_certificates_spec.rb
index 30174b58c6..bd11ae765b 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/companies/tax_exemption_certificates_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/companies/tax_exemption_certificates_spec.rb
@@ -40,6 +40,8 @@ RSpec.describe 'Admin Tax Exemption Certificates API', type: :request, swagger_d
DESC
admin_scope :read, :customers
+ admin_sdk_example 'tax-exemption-certificates/list'
+
response '200', 'certificates found' do
run_test! do |response|
data = JSON.parse(response.body)
@@ -63,6 +65,8 @@ RSpec.describe 'Admin Tax Exemption Certificates API', type: :request, swagger_d
DESC
admin_scope :write, :customers
+ admin_sdk_example 'tax-exemption-certificates/create'
+
parameter name: :body, in: :body, schema: {
type: :object,
properties: {
@@ -128,6 +132,8 @@ RSpec.describe 'Admin Tax Exemption Certificates API', type: :request, swagger_d
DESC
admin_scope :write, :customers
+ admin_sdk_example 'tax-exemption-certificates/verify'
+
response '200', 'certificate verified' do
run_test! do |response|
expect(JSON.parse(response.body)['status']).to eq('verified')
@@ -153,6 +159,8 @@ RSpec.describe 'Admin Tax Exemption Certificates API', type: :request, swagger_d
description 'Withdraws accepted evidence. A verified certificate cannot be deleted — how a sale was taxed has to remain explainable — so revoking is the way out.'
admin_scope :write, :customers
+ admin_sdk_example 'tax-exemption-certificates/revoke'
+
response '200', 'certificate revoked' do
run_test! do |response|
expect(JSON.parse(response.body)['status']).to eq('revoked')
diff --git a/spree/api/spec/integration/spree/api/v3/admin/companies/tax_identifiers_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/companies/tax_identifiers_spec.rb
index 19e9b22c5d..83619d9a31 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/companies/tax_identifiers_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/companies/tax_identifiers_spec.rb
@@ -30,6 +30,8 @@ RSpec.describe 'Admin Company Tax Identifiers API', type: :request, swagger_doc:
DESC
admin_scope :read, :customers
+ admin_sdk_example 'company-tax-identifiers/list'
+
response '200', 'registrations found' do
run_test! do |response|
data = JSON.parse(response.body)
@@ -50,6 +52,8 @@ RSpec.describe 'Admin Company Tax Identifiers API', type: :request, swagger_doc:
DESC
admin_scope :write, :customers
+ admin_sdk_example 'company-tax-identifiers/create'
+
parameter name: :body, in: :body, schema: {
type: :object,
properties: {
@@ -97,6 +101,8 @@ RSpec.describe 'Admin Company Tax Identifiers API', type: :request, swagger_doc:
DESC
admin_scope :write, :customers
+ admin_sdk_example 'company-tax-identifiers/validate'
+
response '422', 'no validator installed for this kind' do
run_test! do |response|
expect(JSON.parse(response.body)['error']['code']).to eq('tax_id_not_validatable')
diff --git a/spree/api/spec/integration/spree/api/v3/admin/companies_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/companies_spec.rb
index e4ed3026fd..553924c22c 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/companies_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/companies_spec.rb
@@ -17,6 +17,8 @@ RSpec.describe 'Admin Companies API', type: :request, swagger_doc: 'api-referenc
description 'Returns the business customers of the current store.'
admin_scope :read, :customers
+ admin_sdk_example 'companies/list'
+
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true
@@ -38,6 +40,8 @@ RSpec.describe 'Admin Companies API', type: :request, swagger_doc: 'api-referenc
description 'Creates a business customer. Exemption certificates and tax registrations hang off it.'
admin_scope :write, :customers
+ admin_sdk_example 'companies/create'
+
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true
parameter name: :body, in: :body, schema: {
diff --git a/spree/api/spec/integration/spree/api/v3/admin/company_locations/contacts_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/company_locations/contacts_spec.rb
index 3af1e89336..8c451b4a6e 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/company_locations/contacts_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/company_locations/contacts_spec.rb
@@ -26,6 +26,8 @@ RSpec.describe 'Admin Company Contacts API', type: :request, swagger_doc: 'api-r
description 'Returns the customers authorised to purchase for a branch. A customer may act for more than one branch.'
admin_scope :read, :customers
+ admin_sdk_example 'company-locations/contacts-list'
+
response '200', 'contacts found' do
run_test! do |response|
data = JSON.parse(response.body)
@@ -46,6 +48,8 @@ RSpec.describe 'Admin Company Contacts API', type: :request, swagger_doc: 'api-r
DESC
admin_scope :write, :customers
+ admin_sdk_example 'company-locations/contacts-create'
+
parameter name: :body, in: :body, schema: {
type: :object,
properties: {
@@ -86,6 +90,8 @@ RSpec.describe 'Admin Company Contacts API', type: :request, swagger_doc: 'api-r
security [api_key: [], bearer_auth: []]
admin_scope :read, :customers
+ admin_sdk_example 'company-contacts/get'
+
response '200', 'contact found' do
run_test! do |response|
expect(JSON.parse(response.body)['email']).to eq('[email protected]')
@@ -100,6 +106,8 @@ RSpec.describe 'Admin Company Contacts API', type: :request, swagger_doc: 'api-r
description 'Withdraws the customer\'s authority to purchase for the branch. The customer account itself is untouched.'
admin_scope :write, :customers
+ admin_sdk_example 'company-contacts/delete'
+
response '204', 'contact deleted' do
run_test!
end