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
import type {
AuthProvidersResponse,
EmailPasswordLogin,
FileUploadCreateParams,
ListParams,
LoginCredentials,
PaginatedResponse,
PaginationMeta,
PreferenceSchema,
ProviderLogin,
RequestFn,
RequestOptions,
UploadFileOptions,
} from '@spree/sdk-core'
import { getParams, transformListParams, uploadFile } from '@spree/sdk-core'
import type {
AddressFilters,
AddressSort,
AdminUserFilters,
AdminUserSort,
AllowedOriginFilters,
AllowedOriginSort,
ApiKeyFilters,
ApiKeySort,
CatalogFilters,
CatalogOrderMinimumFilters,
CatalogOrderMinimumSort,
CatalogSort,
CategoryFilters,
CategorySort,
ChannelFilters,
ChannelSort,
ClaimFilters,
ClaimReasonFilters,
ClaimReasonSort,
ClaimSort,
CollectionFilters,
CollectionSort,
CommissionLineFilters,
CommissionLineSort,
CommissionRateFilters,
CommissionRateSort,
CompanyFilters,
CompanyInvitationFilters,
CompanyInvitationSort,
CompanyMembershipFilters,
CompanyMembershipSort,
CompanySort,
ConsentRecordFilters,
ConsentRecordSort,
CouponCodeFilters,
CouponCodeSort,
CreditCardFilters,
CreditCardSort,
CustomerFilters,
CustomerGroupFilters,
CustomerGroupSort,
CustomerSort,
CustomFieldDefinitionFilters,
CustomFieldDefinitionSort,
CustomFieldFilters,
CustomFieldSort,
DataRequestFilters,
DataRequestSort,
DeliveryMethodFilters,
DeliveryMethodSort,
DeliveryProfileFilters,
DeliveryProfileSort,
DeliveryZoneFilters,
DeliveryZoneSort,
DigitalAssetFilters,
DigitalAssetSort,
DigitalLinkFilters,
DigitalLinkSort,
DiscountFilters,
DiscountSort,
ExchangeFilters,
ExchangeSort,
ExportFilters,
ExportSort,
FeeFilters,
FeeSort,
FulfillmentFilters,
FulfillmentSort,
GiftCardBatchFilters,
GiftCardBatchSort,
GiftCardFilters,
GiftCardSort,
ImportFilters,
ImportRowFilters,
ImportRowSort,
ImportSort,
IntegrationFilters,
IntegrationSort,
InvitationFilters,
InvitationSort,
LineItemFilters,
LineItemSort,
MarketFilters,
MarketSort,
MediaFilters,
MediaSort,
OptionTypeFilters,
OptionTypeSort,
OrderCancellationReasonFilters,
OrderCancellationReasonSort,
OrderFilters,
OrderGroupFilters,
OrderGroupSort,
OrderRoutingRuleFilters,
OrderRoutingRuleSort,
OrderSort,
PackageTypeFilters,
PackageTypeSort,
PaymentFilters,
PaymentMethodFilters,
PaymentMethodSort,
PaymentSort,
PolicyFilters,
PolicySort,
PriceFilters,
PriceListFilters,
PriceListSort,
PriceSort,
ProductFilters,
ProductSearchFilters,
ProductSearchSort,
ProductSort,
ProductTypeFilters,
ProductTypeSort,
PromotionActionFilters,
PromotionActionSort,
PromotionFilters,
PromotionRuleFilters,
PromotionRuleSort,
PromotionSort,
PurchaseOrderFilters,
PurchaseOrderSort,
RefundFilters,
RefundReasonFilters,
RefundReasonSort,
RefundSort,
ReturnFilters,
ReturnReasonFilters,
ReturnReasonSort,
ReturnSort,
RoleFilters,
RoleSort,
SavedReportFilters,
SavedReportSort,
SellerFilters,
SellerPayoutFilters,
SellerPayoutSort,
SellerRequirementFilters,
SellerRequirementSort,
SellerRequirementSubmissionFilters,
SellerRequirementSubmissionSort,
SellerSort,
SellerTransferFilters,
SellerTransferSort,
StockLevelFilters,
StockLevelSort,
StockLocationFilters,
StockLocationSort,
StockMovementFilters,
StockMovementSort,
StockReservationFilters,
StockReservationSort,
StockTransferFilters,
StockTransferSort,
StoreCreditEventFilters,
StoreCreditEventSort,
StoreCreditFilters,
StoreCreditSort,
SupplierFilters,
SupplierSort,
TaxCategoryFilters,
TaxCategorySort,
TaxExemptionCertificateFilters,
TaxExemptionCertificateSort,
TaxExemptionReasonFilters,
TaxExemptionReasonSort,
TaxIdentifierFilters,
TaxIdentifierSort,
TaxLineFilters,
TaxLineSort,
TaxRateFilters,
TaxRateSort,
VariantFilters,
VariantSort,
WebhookDeliveryFilters,
WebhookDeliverySort,
WebhookEndpointFilters,
WebhookEndpointSort,
} from './types/filters.generated'
// ============================================
// Semantic reporting contract (docs/plans/6.0-analytics-semantic-layer.md)
// ============================================
// Every sales context field, so adding one to `VariantSalesContextParams`
// fails to compile until it is listed here too.
const VARIANT_SALES_CONTEXT_FIELDS: Record<keyof VariantSalesContextParams, true> = {
order_id: true,
market_id: true,
channel_id: true,
customer_id: true,
company_id: true,
currency: true,
}
// The sales context scopes and prices the list, so it stays out of the Ransack filters.
function variantListQuery(
params: ListParams<VariantFilters, VariantSort> & VariantSalesContextParams,
): ReturnType<typeof transformListParams> {
const filters: Record<string, unknown> = { ...params }
const context: Record<string, string> = {}
for (const field of Object.keys(VARIANT_SALES_CONTEXT_FIELDS)) {
const value = filters[field]
if (typeof value === 'string' && value) context[field] = value
delete filters[field]
}
return { ...transformListParams(filters), ...context }
}
export type ReportingGrain = 'hour' | 'day' | 'week' | 'month'
export type ReportingCompare = 'previous_period' | 'previous_year'
export type ReportingMetricFilterOp = 'eq' | 'gt' | 'gte' | 'lt' | 'lte'
export type ReportingQuery = {
/** Registered metric names — discover via `reporting.schema()`. */
metrics: string[]
dimensions?: Array<
| string
| {
name: string
grain?: ReportingGrain
/**
* Include members with no matching rows, so a breakdown lists what had
* no activity ("which products never sold"). One dimension only, and
* only where `supports_include_empty` is set on the schema entry.
*/
include_empty?: boolean
}
>
filters?: Array<{ dimension: string; op: 'eq' | 'in'; value: string | string[] }>
/**
* Filter on an aggregate (a HAVING clause), e.g. `units_sold = 0`. Narrows
* the rows only — the totals stay the period's real figure. The metric must
* also appear in `metrics`, and cannot be a derived one.
*/
metric_filters?: Array<{ metric: string; op: ReportingMetricFilterOp; value: number }>
/**
* A named preset (`last_month`, `week_to_date`, `last_4_weeks`, any
* `last_<n>_<days|weeks|months>`), or ISO 8601 dates/datetimes in
* since/until (a bare date covers the store's whole day); defaults to the
* last 30 days. Everything resolves in the store timezone.
*/
time_range?: { preset?: string; since?: string; until?: string }
compare?: ReportingCompare
/** Metric name, `-` prefix for descending. */
sort?: string
limit?: number
currency?: string
}
export interface ReportingMetricValue {
value: number
/** Formatted money string — present on money metrics only. */
display?: string
/** Present when the query requested a comparison. */
previous?: number
/** Percentage change vs the previous period; null when there is no baseline. */
growth?: number | null
}
/** Hydrated display payload for lookup-backed dimensions. */
export interface ReportingDimensionValue {
/** Prefixed id (e.g. `cust_…`); null when the underlying record is gone (e.g. guest customers). */
id: string | null
label: string
meta: Record<string, unknown>
}
export interface ReportingRow {
/** Raw values for plain dimensions (time buckets, statuses); display payloads for lookups. */
dimensions: Record<string, string | ReportingDimensionValue>
metrics: Record<string, ReportingMetricValue>
}
export interface ReportingResult {
meta: {
currency: string
time_range: { since: string; until: string }
previous_time_range: { since: string; until: string } | null
metrics: string[]
dimensions: Array<{ name: string; grain?: string }>
}
totals: Record<string, ReportingMetricValue>
rows: ReportingRow[]
}
export interface ReportingSchemaMetric {
name: string
/** Metrics from different families cannot be combined in one query. */
family?: string
label: string
description?: string
format: 'money' | 'integer' | 'decimal' | 'percent' | string
currency?: string
derived: boolean
/** Derived metrics are computed after aggregation, so they cannot be sorted or filtered in SQL. */
filterable?: boolean
}
export interface ReportingSchemaDimension {
name: string
label: string
description?: string
type: 'value' | 'time' | string
grains?: ReportingGrain[]
/** Set when rows carry hydrated `{ id, label, meta }` payloads for this dimension. */
lookup?: string
filter_ops: Array<'eq' | 'in'>
/** Whether this dimension can lead a query with `include_empty`. */
supports_include_empty?: boolean
/** Enumerated raw values for status-like dimensions. */
values?: Array<{ name: string; label: string }>
/** Metrics this dimension can break down without double counting. */
compatible_metrics: string[]
}
/** Members that can be queried together: sales, payments, inventory, carts. */
export interface ReportingSchemaFamily {
name: string
label: string
metrics: string[]
dimensions: string[]
}
/** The self-describing contract, filtered to what the caller may reference. */
export interface ReportingSchema {
meta: { currency: string; timezone: string; supported_currencies: string[] }
families: ReportingSchemaFamily[]
metrics: ReportingSchemaMetric[]
dimensions: ReportingSchemaDimension[]
time_range: {
presets: Array<{ name: string; label: string }>
relative: string[]
absolute: string
}
/** Ranking defaults the server applies (`limit` when omitted, and its ceiling). */
limits: { default: number; max: number; max_buckets?: number }
/** Ops accepted by `metric_filters`. */
metric_filter_ops?: ReportingMetricFilterOp[]
compare_modes?: ReportingCompare[]
}
export interface DashboardCounters {
/** Prefixed channel id the order-based counts are scoped to; null means all channels. Stock counts are always store-wide. */
channel_id: string | null
/**
* The counters registered on `Spree.reporting` that this caller may read,
* in registration order. Labels, links and the sidebar entry each one
* badges all come from the server, so a counter an extension registers
* renders without a dashboard change.
*/
counters: DashboardCounter[]
}
export interface AuthTokens {
/** Short-lived JWT access token. Goes in `Authorization: Bearer`. Keep in memory only. */
token: string
user: AdminUser
}
export interface PermissionRule {
/** true for `can`, false for `cannot` */
allow: boolean
/** Action names, e.g. ["read", "update"] or ["manage"] */
actions: string[]
/** Subject short names, e.g. ["product"] or ["all"] */
subjects: string[]
/** Whether the server rule has per-record conditions. If true, the action may be denied at the record level and the SPA should expect possible 403. */
has_conditions: boolean
}
export interface MeResponse {
/**
* The signed-in admin, serialized exactly like every other admin user — so a
* profile save can be merged straight into the auth context without dropping
* the fields the top bar reads (`full_name`, `avatar_url`).
*/
user: AdminUser
permissions: PermissionRule[]
/**
* The flat expanded catalog permission keys the user holds on the current
* store (`read_orders`, `write_products`, …) — the same vocabulary as API
* key scopes and the role editor. `write_x` is always accompanied by its
* implied `read_x`.
*/
permission_keys: string[]
}
import type {
AdminUserUpdateParams,
AllowedOriginCreateParams,
AllowedOriginUpdateParams,
ApiKeyCreateParams,
ApiKeyUpdateParams,
BulkTagsParams,
CatalogAssignParams,
CatalogCreateParams,
CatalogOrderMinimumParams,
CatalogProductTermsParams,
CatalogUpdateParams,
CategoryCreateParams,
CategoryRepositionParams,
CategoryUpdateParams,
ChannelAddProductsParams,
ChannelCreateParams,
ChannelRemoveProductsParams,
ChannelUpdateParams,
ClaimCancelParams,
ClaimCreateParams,
ClaimDenyParams,
ClaimResolveParams,
ClaimUpdateParams,
CollectionCreateParams,
CollectionUpdateParams,
CommissionRateCreateParams,
CommissionRateUpdateParams,
CommissionRuleType,
CompanyAddressCreateParams,
CompanyAddressUpdateParams,
CompanyCreateParams,
CompanyMembershipCreateParams,
CompanyUpdateParams,
CustomerAddressCreateParams,
CustomerAddressUpdateParams,
CustomerBulkGroupsParams,
CustomerCreateParams,
CustomerGroupCreateParams,
CustomerGroupUpdateParams,
CustomerStoreCreditCreateParams,
CustomerStoreCreditUpdateParams,
CustomerUpdateParams,
CustomFieldCreateParams,
CustomFieldDefinitionCreateParams,
CustomFieldDefinitionUpdateParams,
CustomFieldOwnerType,
CustomFieldResourceType,
CustomFieldUpdateParams,
DataRequestCreateParams,
DeliveryCreateParams,
DeliveryMarkDeliveredParams,
DeliveryMethodCreateParams,
DeliveryMethodRuleCreateParams,
DeliveryMethodRuleUpdateParams,
DeliveryMethodUpdateParams,
DeliveryOriginGroupParams,
DeliveryProfileCreateParams,
DeliveryProfileUpdateParams,
DeliveryUpdateParams,
DeliveryZoneCreateParams,
DeliveryZoneUpdateParams,
DigitalAssetCreateParams,
DigitalAssetProvider,
DigitalAssetUpdateParams,
DiscountCodeApplyParams,
DiscountCreateParams,
DiscountUpdateParams,
EmailTemplateDraftParams,
EmailTemplateLanguageParams,
EmailTemplatePreviewParams,
EmailTemplateRestoreParams,
EmailTemplateVersionParams,
ExchangeCancelParams,
ExchangeCreateParams,
ExchangeFulfillParams,
ExchangeReceiveParams,
ExchangeUpdateParams,
ExportCreateParams,
FeeCreateParams,
FeeUpdateParams,
FulfillmentCreateParams,
FulfillmentFulfillParams,
FulfillmentMarkDeliveredParams,
FulfillmentSplitParams,
FulfillmentUpdateParams,
GiftCardApplyParams,
GiftCardBatchCreateParams,
GiftCardCreateParams,
GiftCardUpdateParams,
ImportCompleteMappingParams,
ImportCreateParams,
IntegrationCreateParams,
IntegrationTypeDefinition,
IntegrationUpdateParams,
InvitationAcceptParams,
InvitationCreateParams,
LineItemCreateParams,
LineItemUpdateParams,
MaintenanceTaskRunCreateParams,
MarketCreateParams,
MarketUpdateParams,
MediaCreateParams,
MediaLibraryCreateParams,
MediaLibraryUpdateParams,
MediaUpdateParams,
MediaUsageReference,
MeUpdateParams,
OauthAuthorizationParams,
OptionTypeCreateParams,
OptionTypeUpdateParams,
OrderCancelParams,
OrderCompleteParams,
OrderCreateParams,
OrderRoutingRuleCreateParams,
OrderRoutingRuleUpdateParams,
OrderUpdateParams,
PackageTypeCreateParams,
PackageTypeUpdateParams,
PasswordResetParams,
PasswordResetRequestParams,
PaymentCaptureParams,
PaymentCreateParams,
PaymentMethodCreateParams,
PaymentMethodType,
PaymentMethodUpdateParams,
PolicyCreateParams,
PolicyUpdateParams,
PriceBulkDestroyParams,
PriceBulkUpsertParams,
PriceCreateParams,
PriceListCreateParams,
PriceListUpdateParams,
PriceUpdateParams,
ProductBulkCategoriesParams,
ProductBulkChannelsParams,
ProductBulkCollectionsParams,
ProductBulkDestroyParams,
ProductBulkStatusParams,
ProductCreateParams,
ProductMembershipRepositionParams,
ProductRejectParams,
ProductTypeApplyToProductsResponse,
ProductTypeCreateParams,
ProductTypeUpdateParams,
ProductUpdateParams,
PromotionActionCalculator,
PromotionActionCreateParams,
PromotionActionUpdateParams,
PromotionCreateParams,
PromotionRuleCreateParams,
PromotionRuleUpdateParams,
PromotionUpdateParams,
PurchaseOrderCancelParams,
PurchaseOrderCreateParams,
PurchaseOrderUpdateParams,
ReasonCreateParams,
ReasonUpdateParams,
ReceivableCloseParams,
RefundCreateParams,
ResourceTypeDefinition,
ReturnCancelParams,
ReturnCreateParams,
ReturnReceiveParams,
ReturnRefundParams,
ReturnUpdateParams,
RoleCreateParams,
RoleUpdateParams,
SavedReportCreateParams,
SavedReportUpdateParams,
SellerApproveParams,
SellerCreateParams,
SellerInviteParams,
SellerOnboarding,
SellerPayoutCompleteParams,
SellerRejectParams,
SellerReopenOnboardingParams,
SellerRequirementCreateParams,
SellerRequirementReviewParams,
SellerRequirementType,
SellerRequirementUpdateParams,
SellerRequirementWaiveParams,
SellerSuspendParams,
SellerUpdateParams,
SetupCountries,
SetupParams,
SetupStatus,
ShippingLabelCreateParams,
StockLevelBulkUpsertParams,
StockLevelUpdateParams,
StockLocationCreateParams,
StockLocationUpdateParams,
StockReceiptCreateParams,
StockTransferCancelParams,
StockTransferCreateParams,
StockTransferMarkInTransitParams,
StockTransferUpdateParams,
StoreCreditApplyParams,
StoreCreditListResponse,
StoreDataSources,
StorePayoutProvider,
StoreUpdateParams,
SupplierCreateParams,
SupplierUpdateParams,
TaxCategoryCreateParams,
TaxCategoryUpdateParams,
TaxExemptionCertificateCreateParams,
TaxExemptionCertificateUpdateParams,
TaxExemptionReasonCreateParams,
TaxExemptionReasonUpdateParams,
TaxIdentifierCreateParams,
TaxIdentifierUpdateParams,
TaxProviderOption,
TaxRateCreateParams,
TaxRateUpdateParams,
TrackingCarrierOption,
VariantCreateParams,
VariantSalesContextParams,
VariantUpdateParams,
WebhookEndpointCreateParams,
WebhookEndpointDisableParams,
WebhookEndpointUpdateParams,
} from './params'
import type {
Address,
AdminUser,
AllowedOrigin,
ApiKey,
Catalog,
CatalogAssignment,
CatalogOrderMinimum,
CatalogProduct,
Category,
Channel,
Claim,
ClaimReason,
Collection,
CommissionLine,
CommissionRate,
Company,
CompanyInvitation,
CompanyMembership,
ConsentRecord,
Country,
CouponCode,
CreditCard,
Customer,
CustomerGroup,
CustomField,
CustomFieldDefinition,
DashboardCounter,
DataRequest,
Delivery,
DeliveryMethod,
DeliveryMethodRule,
DeliveryOriginGroup,
DeliveryProfile,
DeliveryRateProviderOption,
DeliveryZone,
DigitalAsset,
DigitalLink,
Discount,
EmailTemplate,
EmailTemplatePreview,
EmailTemplateRevision,
EmailTemplateSampleRecord,
Exchange,
Export,
Fee,
FileUpload,
Fulfillment,
FulfillmentProviderOption,
GiftCard,
GiftCardBatch,
Import,
ImportRow,
Integration,
Invitation,
InvitationAcceptanceLink,
LineItem,
Locale,
MaintenanceTaskRun,
Market,
Media,
OauthAccessToken,
OauthApplication,
OauthConsentRequest,
OauthRedirect,
OptionType,
Order,
OrderCancellationReason,
OrderGroup,
OrderRoutingRule,
PackageType,
Payment,
PaymentMethod,
Permission,
Policy,
Price,
PriceList,
PriceListProduct,
Product,
ProductType,
Promotion,
PromotionAction,
PromotionRule,
PurchaseOrder,
Refund,
RefundReason,
ResourceTranslations,
ResourceTranslationsNode,
Return,
ReturnReason,
Role,
SavedReport,
Seller,
SellerBalance,
SellerPayout,
SellerRequirement,
SellerRequirementSubmission,
SellerTeamMember,
SellerTransfer,
ShippingLabel,
StockLevel,
StockLocation,
StockMovement,
StockReceipt,
StockReservation,
StockTransfer,
Store,
StoreCredit,
StoreCreditEvent,
Supplier,
TaxCategory,
TaxExemptionCertificate,
TaxExemptionReason,
TaxIdentifier,
TaxLine,
TaxRate,
TranslatableResource,
TranslationBatchEntry,
TranslationCoverage,
UpdateStatus,
UpgradeStep,
UpgradeStepsMeta,
Variant,
WebhookDelivery,
WebhookEndpoint,
WebhookEvent,
} from './types'
/**
* Maps a built-in CustomField owner type (e.g. `product`) to its admin
* route segment. The generic `client.customFields(ownerType, ownerId)` escape
* hatch reads this map; plugin owners that aren't registered here hit the
* runtime "Unknown owner type" error and should use the first-class accessor
* exposed by their plugin.
*
* `satisfies` here keeps the map keys as a subset of the strict-literal arm of
* `CustomFieldOwnerType`. Adding a built-in owner means updating both this map
* and the union in `params.ts`; the type system flags the map side.
*/
const CUSTOM_FIELD_OWNER_PATHS = {
product: '/products',
variant: '/variants',
order: '/orders',
customer: '/customers',
category: '/categories',
collection: '/collections',
option_type: '/option_types',
seller: '/sellers',
promotion: '/promotions',
gift_card: '/gift_cards',
store_credit: '/store_credits',
stock_transfer: '/stock_transfers',
purchase_order: '/purchase_orders',
company: '/companies',
payment_method: '/payment_methods',
delivery_method: '/delivery_methods',
tax_rate: '/tax_rates',
product_type: '/product_types',
media: '/media',
store: '/stores',
} as const satisfies Record<Exclude<CustomFieldOwnerType, string & {}>, string>
export class AdminClient {
/**
* 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 brand = await client.request<Brand>('GET', '/brands/brand_2X9aQf7kEw')
* ```
*/
readonly request: RequestFn
constructor(request: RequestFn) {
this.request = request
}
/**
* Builds a `customFields` accessor whose methods expect the parent ID as
* their first argument. Inlined by each first-class resource (`products`,
* `orders`, …) so callers can write `client.products.customFields.list(id)`.
* The generic `customFields(ownerType, ownerId)` escape hatch curries the
* parent ID up front and returns the same shape minus the leading `parentId`.
* @internal
*/
private parentScopedCustomFields(basePath: string) {
return {
list: (
parentId: string,
params?: ListParams<CustomFieldFilters, CustomFieldSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<CustomField>> =>
this.request<PaginatedResponse<CustomField>>(
'GET',
`${basePath}/${parentId}/custom_fields`,
{ ...options, params: params ? transformListParams(params) : undefined },
),
get: (parentId: string, id: string, options?: RequestOptions): Promise<CustomField> =>
this.request<CustomField>('GET', `${basePath}/${parentId}/custom_fields/${id}`, options),
create: (
parentId: string,
params: CustomFieldCreateParams,
options?: RequestOptions,
): Promise<CustomField> =>
this.request<CustomField>('POST', `${basePath}/${parentId}/custom_fields`, {
...options,
body: params,
}),
update: (
parentId: string,
id: string,
params: CustomFieldUpdateParams,
options?: RequestOptions,
): Promise<CustomField> =>
this.request<CustomField>('PATCH', `${basePath}/${parentId}/custom_fields/${id}`, {
...options,
body: params,
}),
delete: (parentId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `${basePath}/${parentId}/custom_fields/${id}`, options),
}
}
/**
* Builds a read-only `translations` accessor for a translatable parent
* resource. `get` returns the full matrix (source values + per-locale
* translations + nested translatable children). Writes go through
* `client.translations.batch(...)`, the single atomic write surface.
* @internal
*/
private parentScopedTranslations(basePath: string) {
return {
get: (parentId: string, options?: RequestOptions): Promise<ResourceTranslations> =>
this.request<{ data: ResourceTranslations }>(
'GET',
`${basePath}/${parentId}/translations`,
options,
).then((r) => r.data),
}
}
/**
* The uniform nested products surface every product-curating parent
* exposes — categories, collections, catalogs and price lists all speak
* the same protocol. Both writes are bulk: one request adds or removes
* any number of products, and the counts report what actually changed
* (already-present ids don't fail an add, non-members don't fail a
* remove).
*/
private productMembership<Row = Product>(basePath: string) {
return {
/**
* A parent whose listing says more about a member than the plain
* product does — a catalog reports what its agreement charges — types
* `Row` accordingly.
*/
list: (
parentId: string,
params?: ListParams<ProductFilters, ProductSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Row>> =>
this.request<PaginatedResponse<Row>>('GET', `${basePath}/${parentId}/products`, {
...options,
params: params ? transformListParams(params) : undefined,
}),
/** Bulk-adds products; already-present rows are skipped. */
create: (
parentId: string,
productIds: string[],
options?: RequestOptions,
): Promise<{ added_count: number }> =>
this.request<{ added_count: number }>('POST', `${basePath}/${parentId}/products`, {
...options,
body: { product_ids: productIds },
}),
/** Bulk-removes products; ids that aren't members are ignored. */
delete: (
parentId: string,
productIds: string[],
options?: RequestOptions,
): Promise<{ removed_count: number }> =>
this.request<{ removed_count: number }>('DELETE', `${basePath}/${parentId}/products`, {
...options,
body: { product_ids: productIds },
}),
}
}
/**
* `productMembership` plus per-member reposition, for the parents whose
* membership carries a manual order (categories, collections).
*/
private positionedProductMembership(basePath: string) {
return {
...this.productMembership(basePath),
/** Persists a drag-to-reorder; `new_position` is a 0-based index. */
reposition: (
parentId: string,
productId: string,
params: ProductMembershipRepositionParams,
options?: RequestOptions,
): Promise<void> =>
this.request<void>('PATCH', `${basePath}/${parentId}/products/${productId}/reposition`, {
...options,
body: params,
}),
}
}
/**
* Generic accessor for any custom-field-bearing resource. Use the
* first-class accessors (`client.products.customFields`, etc.) when
* available — they're more discoverable. Use this when the owner is a
* plugin-registered resource without a dedicated accessor.
*
* ```ts
* await client.customFields('product', 'prod_xxx').list()
* ```
*/
customFields(ownerType: CustomFieldOwnerType, ownerId: string) {
const ownerPath = (CUSTOM_FIELD_OWNER_PATHS as Record<string, string>)[ownerType]
if (!ownerPath) {
throw new Error(
`Unknown custom-field owner type: ${ownerType}. Add it to CUSTOM_FIELD_OWNER_PATHS.`,
)
}
const scoped = this.parentScopedCustomFields(ownerPath)
return {
list: (params?: ListParams<CustomFieldFilters, CustomFieldSort>, options?: RequestOptions) =>
scoped.list(ownerId, params, options),
get: (id: string, options?: RequestOptions) => scoped.get(ownerId, id, options),
create: (params: CustomFieldCreateParams, options?: RequestOptions) =>
scoped.create(ownerId, params, options),
update: (id: string, params: CustomFieldUpdateParams, options?: RequestOptions) =>
scoped.update(ownerId, id, params, options),
delete: (id: string, options?: RequestOptions) => scoped.delete(ownerId, id, options),
}
}
// ============================================
// Custom Field Definitions (per resource type)
// ============================================
readonly customFieldDefinitions = {
list: (
params?: ListParams<CustomFieldDefinitionFilters, CustomFieldDefinitionSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<CustomFieldDefinition>> =>
this.request<PaginatedResponse<CustomFieldDefinition>>('GET', '/custom_field_definitions', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, options?: RequestOptions): Promise<CustomFieldDefinition> =>
this.request<CustomFieldDefinition>('GET', `/custom_field_definitions/${id}`, options),
/**
* What a definition can be attached to. Comes from the server's registry,
* so a resource an extension adds is offered without a dashboard release.
*/
resourceTypes: (options?: RequestOptions): Promise<{ data: CustomFieldResourceType[] }> =>
this.request<{ data: CustomFieldResourceType[] }>(
'GET',
'/custom_field_definitions/resource_types',
options,
),
create: (
params: CustomFieldDefinitionCreateParams,
options?: RequestOptions,
): Promise<CustomFieldDefinition> =>
this.request<CustomFieldDefinition>('POST', '/custom_field_definitions', {
...options,
body: params,
}),
update: (
id: string,
params: CustomFieldDefinitionUpdateParams,
options?: RequestOptions,
): Promise<CustomFieldDefinition> =>
this.request<CustomFieldDefinition>('PATCH', `/custom_field_definitions/${id}`, {
...options,
body: params,
}),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/custom_field_definitions/${id}`, options),
}
// ============================================
// Authentication
// ============================================
readonly auth = {
/**
* Exchange credentials for an access token. The refresh token is delivered as an
* HttpOnly cookie scoped to `/api/v3/admin/auth` — never returned in the response body.
*/
login: (credentials: LoginCredentials, options?: RequestOptions): Promise<AuthTokens> =>
this.request<AuthTokens>('POST', '/auth/login', { ...options, body: credentials }),
/**
* Rotate the refresh cookie and obtain a new access token. Driven entirely by the
* `spree_admin_refresh_token` HttpOnly cookie + `X-CSRF-Token` header (set by the SDK).
*/
refresh: (options?: RequestOptions): Promise<AuthTokens> =>
this.request<AuthTokens>('POST', '/auth/refresh', options),
/**
* Revoke the current refresh token server-side and clear auth cookies.
* Idempotent: succeeds even when no session exists.
*/
logout: (options?: RequestOptions): Promise<void> =>
this.request<void>('POST', '/auth/logout', options),
/**
* List the authentication providers this store accepts. Unauthenticated — it
* is read before a session exists, to decide whether the login page shows the
* password form, SSO buttons, or both.
*/
providers: (options?: RequestOptions): Promise<AuthProvidersResponse> =>
this.request<AuthProvidersResponse>('GET', '/auth/providers', options),
/**
* Public (unauthenticated) lookup of a pending invitation by prefixed ID + token.
* Returns just the safe-to-render context (store, role, inviter, invitee_exists)
* so the SPA acceptance page can decide between sign-in and signup forms.
*/
lookupInvitation: (id: string, token: string, options?: RequestOptions): Promise<Invitation> =>
this.request<Invitation>('GET', `/auth/invitations/${id}/lookup`, {
...options,
params: { token },
}),
/**
* Public (unauthenticated) accept of an invitation. For existing accounts the
* caller passes their password; for new accounts they pass password +
* confirmation + names. Either path issues a JWT + refresh-token cookie
* identical to `login`.
*/
acceptInvitation: (
id: string,
token: string,
params: InvitationAcceptParams,
options?: RequestOptions,
): Promise<AuthTokens> =>
this.request<AuthTokens>('POST', `/auth/invitations/${id}/accept`, {
...options,
params: { token },
body: params,
}),
/**
* Public (unauthenticated) first-run setup availability check. True only
* while the installation has no admin user — the login page uses it to
* offer the setup screen.
*/
setupStatus: (options?: RequestOptions): Promise<SetupStatus> =>
this.request<SetupStatus>('GET', '/auth/setup', options),
/**
* Public (unauthenticated) list of countries the store can be set up in,
* each with the currency and official languages derived from it. Returns
* 404 once any admin user exists.
*/
setupCountries: (options?: RequestOptions): Promise<SetupCountries> =>
this.request<SetupCountries>('GET', '/auth/setup/countries', options),
/**
* Public (unauthenticated) first-run setup: creates the first admin
* account and names the store, authorized by the one-time setup token
* printed at install time. Issues a JWT + refresh-token cookie identical
* to `login`. Returns 404 once any admin user exists.
*/
completeSetup: (params: SetupParams, options?: RequestOptions): Promise<AuthTokens> =>
this.request<AuthTokens>('POST', '/auth/setup', { ...options, body: params }),
/**
* Public (unauthenticated) request for a password reset email. Always
* resolves (202) whether or not the email matches an account, to prevent
* enumeration. The emailed link points at `redirect_url` when it is on the
* dashboard's origin and the account is staff of the store, otherwise at the
* dashboard's reset page, with the reset token appended as `?token=`.
*/
requestPasswordReset: (
params: PasswordResetRequestParams,
options?: RequestOptions,
): Promise<void> =>
this.request<void>('POST', '/auth/password_resets', { ...options, body: params }),
/**
* Public (unauthenticated) consume of a password reset token: sets the new
* password and signs the admin in (JWT + refresh-token cookie, like `login`).
* The token is single-use — it invalidates as soon as the password changes.
*/
resetPassword: (
token: string,
params: PasswordResetParams,
options?: RequestOptions,
): Promise<AuthTokens> =>
this.request<AuthTokens>('PATCH', `/auth/password_resets/${encodeURIComponent(token)}`, {
...options,
body: params,
}),
}
// ============================================
// Current admin user + permissions
// ============================================
readonly me = {
/** Get the current admin user profile and their serialized permissions. */
get: (options?: RequestOptions): Promise<MeResponse> =>
this.request<MeResponse>('GET', '/me', options),
/** Update the current admin's own profile (e.g. their UI language). */
update: (params: MeUpdateParams, options?: RequestOptions): Promise<MeResponse> =>
this.request<MeResponse>('PATCH', '/me', { ...options, body: params }),
}
readonly updates = {
/**
* Whether a newer Spree release exists, from the server's daily update
* check. Needs a client created with `jwtToken` for an admin who can
* manage the store; a secret key gets a 404.
*/
get: (options?: RequestOptions): Promise<UpdateStatus> =>
this.request<UpdateStatus>('GET', '/updates', options),
}
// ============================================
// Dashboard
// ============================================
readonly reporting = {
/** Run a semantic reporting query against the registered metric/dimension vocabulary. */
query: (query: ReportingQuery, options?: RequestOptions): Promise<ReportingResult> =>
this.request<ReportingResult>('POST', '/reporting/query', { ...options, body: query }),
/** Registry introspection — drives pickers and agent tool schemas. */
schema: (options?: RequestOptions): Promise<ReportingSchema> =>
this.request<ReportingSchema>('GET', '/reporting/schema', options),
/** Store-wide saved reports: a contract query plus visualization config. */
savedReports: {
list: (
params?: ListParams<SavedReportFilters, SavedReportSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<SavedReport>> =>
this.request<PaginatedResponse<SavedReport>>('GET', '/reporting/saved_reports', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, options?: RequestOptions): Promise<SavedReport> =>
this.request<SavedReport>('GET', `/reporting/saved_reports/${id}`, options),
create: (params: SavedReportCreateParams, options?: RequestOptions): Promise<SavedReport> =>
this.request<SavedReport>('POST', '/reporting/saved_reports', { ...options, body: params }),
update: (
id: string,
params: SavedReportUpdateParams,
options?: RequestOptions,
): Promise<SavedReport> =>
this.request<SavedReport>('PATCH', `/reporting/saved_reports/${id}`, {
...options,
body: params,
}),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/reporting/saved_reports/${id}`, options),
},
}
readonly dashboard = {
counters: (
params?: { channel_id?: string },
options?: RequestOptions,
): Promise<DashboardCounters> =>
this.request<DashboardCounters>('GET', '/dashboard/counters', { ...options, params }),
}
// ============================================
// Store Settings
// ============================================
readonly store = {
get: (options?: RequestOptions): Promise<Store> =>
this.request<Store>('GET', '/store', options),
update: (params: StoreUpdateParams, options?: RequestOptions): Promise<Store> =>
this.request<Store>('PATCH', '/store', { ...options, body: params }),
/**
* The pricing and inventory engines this store can choose between, and
* whether each is usable — a provider whose integration is not connected
* is listed but not selectable.
*/
dataSources: (options?: RequestOptions): Promise<StoreDataSources> =>
this.request<{ data: StoreDataSources }>('GET', '/store/data_sources', options).then(
(r) => r.data,
),
translations: this.parentScopedTranslations('/stores'),
}
/** The locales a merchant can translate content into for the current store. */
readonly locales = {
list: (options?: RequestOptions): Promise<Locale[]> =>
this.request<{ data: Locale[] }>('GET', '/locales', options).then((r) => r.data),
}
/** Every translatable resource type and its translatable fields (registry). */
readonly translatableResources = {
list: (options?: RequestOptions): Promise<TranslatableResource[]> =>
this.request<{ data: TranslatableResource[] }>(
'GET',
'/translatable_resources',
options,
).then((r) => r.data),
}
/**
* Translation writes that span multiple records (e.g. an option type plus
* all its option values) in one atomic request. Each entry names its own
* resource_type + resource_id; all succeed or none do.
*/
readonly translations = {
/**
* Translation coverage across a whole resource type, for the centralized
* Translations page.
*
* `resource_type` is sent as a plain param rather than through
* `transformListParams`, which would wrap it into `q[resource_type]` and
* leave the server without the one param it requires.
*/
coverage: (
resourceType: string,
params?: ListParams & { search?: string } & Record<string, unknown>,
options?: RequestOptions,
): Promise<{ data: TranslationCoverage; meta: PaginationMeta }> => {
// `resource_type` and `search` are read as plain params by the server;
// routing them through `transformListParams` would wrap both into
// Ransack predicates (`q[resource_type]`) the controller never sees.
const { page, limit, search, ...filters } = params ?? {}
return this.request<{ data: TranslationCoverage; meta: PaginationMeta }>(
'GET',
'/translations',
{
...options,
params: {
resource_type: resourceType,
...(page === undefined ? {} : { page: page as number }),
...(limit === undefined ? {} : { limit: limit as number }),
...(search === undefined ? {} : { search: search as string }),
...transformListParams(filters),
},
},
)
},
batch: (
entries: TranslationBatchEntry[],
options?: RequestOptions,
): Promise<ResourceTranslationsNode[]> =>
this.request<{ data: ResourceTranslationsNode[] }>('POST', '/translations/batch', {
...options,
body: { translations: entries },
}).then((r) => r.data),
}
// ============================================
// Products
// ============================================
readonly products = {
list: (
params?: ListParams<ProductSearchFilters, ProductSearchSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Product>> =>
this.request<PaginatedResponse<Product>>('GET', '/products', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Product> =>
this.request<Product>('GET', `/products/${id}`, {
...options,
params: getParams(params),
}),
create: (params: ProductCreateParams, options?: RequestOptions): Promise<Product> =>
this.request<Product>('POST', '/products', { ...options, body: params }),
update: (id: string, params: ProductUpdateParams, options?: RequestOptions): Promise<Product> =>
this.request<Product>('PATCH', `/products/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/products/${id}`, options),
/**
* Duplicate a product. Returns the freshly-created clone (status `draft`,
* name prefixed "COPY OF"). Media is duplicated by default server-side.
*/
clone: (id: string, options?: RequestOptions): Promise<Product> =>
this.request<Product>('POST', `/products/${id}/clone`, options),
/**
* Accept a product a seller submitted, putting it on sale. Refuses
* anything not awaiting review — reaching `active` from elsewhere is an
* ordinary status write.
*/
approve: (id: string, options?: RequestOptions): Promise<Product> =>
this.request<Product>('PATCH', `/products/${id}/approve`, options),
/**
* Turn a submission down. The reason is shown to the seller, so they know
* what to change before submitting again.
*/
reject: (
id: string,
params?: ProductRejectParams,
options?: RequestOptions,
): Promise<Product> =>
this.request<Product>('PATCH', `/products/${id}/reject`, { ...options, body: params }),
/**
* Put one product on sale, running its status workflow so the
* `product.activated` event fires. Refuses a product awaiting review,
* which is approved or rejected instead.
*/
activate: (id: string, options?: RequestOptions): Promise<Product> =>
this.request<Product>('PATCH', `/products/${id}/activate`, options),
/** Archive one product, taking it off sale. Refuses a product awaiting review. */
archive: (id: string, options?: RequestOptions): Promise<Product> =>
this.request<Product>('PATCH', `/products/${id}/archive`, options),
/** Take one product off sale, back to a draft. Refuses a product awaiting review. */
draft: (id: string, options?: RequestOptions): Promise<Product> =>
this.request<Product>('PATCH', `/products/${id}/draft`, options),
/**
* Bulk-set `status` on a list of products. The server validates `status`
* against the product status enum and reindexes affected products.
*/
bulkStatusUpdate: (
params: ProductBulkStatusParams,
options?: RequestOptions,
): Promise<{ product_count: number; status: string }> =>
this.request('POST', '/products/bulk_status_update', { ...options, body: params }),
/** Attach every product in `ids` to every category in `category_ids`. */
bulkAddToCategories: (
params: ProductBulkCategoriesParams,
options?: RequestOptions,
): Promise<{ product_count: number; category_count: number }> =>
this.request('POST', '/products/bulk_add_to_categories', { ...options, body: params }),
/** Detach every product in `ids` from every category in `category_ids`. */
bulkRemoveFromCategories: (
params: ProductBulkCategoriesParams,
options?: RequestOptions,
): Promise<{ product_count: number; category_count: number }> =>
this.request('POST', '/products/bulk_remove_from_categories', { ...options, body: params }),
/**
* Attach every product in `ids` to every collection in `collection_ids`.
* Automatic collections are skipped (their membership comes from rules), so
* `collection_count` reports how many were actually applied.
*/
bulkAddToCollections: (
params: ProductBulkCollectionsParams,
options?: RequestOptions,
): Promise<{ product_count: number; collection_count: number }> =>
this.request('POST', '/products/bulk_add_to_collections', { ...options, body: params }),
/** Detach every product in `ids` from every collection in `collection_ids`. */
bulkRemoveFromCollections: (
params: ProductBulkCollectionsParams,
options?: RequestOptions,
): Promise<{ product_count: number; collection_count: number }> =>
this.request('POST', '/products/bulk_remove_from_collections', { ...options, body: params }),
/** Publish every product in `ids` on every channel in `channel_ids`. */
bulkAddToChannels: (
params: ProductBulkChannelsParams,
options?: RequestOptions,
): Promise<{ product_count: number; channel_count: number }> =>
this.request('POST', '/products/bulk_add_to_channels', { ...options, body: params }),
/** Unpublish every product in `ids` from every channel in `channel_ids`. */
bulkRemoveFromChannels: (
params: ProductBulkChannelsParams,
options?: RequestOptions,
): Promise<{ product_count: number; channel_count: number; removed: number }> =>
this.request('POST', '/products/bulk_remove_from_channels', { ...options, body: params }),
/** Add each tag name to every product. Tags are upserted by name. */
bulkAddTags: (
params: BulkTagsParams,
options?: RequestOptions,
): Promise<{ product_count: number; tag_count: number }> =>
this.request('POST', '/products/bulk_add_tags', { ...options, body: params }),
/** Remove each tag name from every product. No-op for non-tagged. */
bulkRemoveTags: (
params: BulkTagsParams,
options?: RequestOptions,
): Promise<{ product_count: number; tag_count: number }> =>
this.request('POST', '/products/bulk_remove_tags', { ...options, body: params }),
/** Soft-delete a list of products. */
bulkDestroy: (
params: ProductBulkDestroyParams,
options?: RequestOptions,
): Promise<{ product_count: number }> =>
this.request('DELETE', '/products/bulk_destroy', { ...options, body: params }),
media: {
list: (
productId: string,
params?: ListParams<MediaFilters, MediaSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Media>> =>
this.request<PaginatedResponse<Media>>('GET', `/products/${productId}/media`, {
...options,
params: params ? transformListParams(params) : undefined,
}),
create: (
productId: string,
params: MediaCreateParams,
options?: RequestOptions,
): Promise<Media> =>
this.request<Media>('POST', `/products/${productId}/media`, { ...options, body: params }),
update: (
productId: string,
id: string,
params: MediaUpdateParams,
options?: RequestOptions,
): Promise<Media> =>
this.request<Media>('PATCH', `/products/${productId}/media/${id}`, {
...options,
body: params,
}),
delete: (productId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/products/${productId}/media/${id}`, options),
},
digitalAssets: {
list: (
productId: string,
params?: ListParams<DigitalAssetFilters, DigitalAssetSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<DigitalAsset>> =>
this.request<PaginatedResponse<DigitalAsset>>(
'GET',
`/products/${productId}/digital_assets`,
{
...options,
params: params ? transformListParams(params) : undefined,
},
),
create: (
productId: string,
params: DigitalAssetCreateParams,
options?: RequestOptions,
): Promise<DigitalAsset> =>
this.request<DigitalAsset>('POST', `/products/${productId}/digital_assets`, {
...options,
body: params,
}),
update: (
productId: string,
id: string,
params: DigitalAssetUpdateParams,
options?: RequestOptions,
): Promise<DigitalAsset> =>
this.request<DigitalAsset>('PATCH', `/products/${productId}/digital_assets/${id}`, {
...options,
body: params,
}),
delete: (productId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/products/${productId}/digital_assets/${id}`, options),
/**
* The sources a merchant can pick for a new asset: the uploaded-file
* default plus any host-registered provider. A host with only the default
* gets a single-entry list.
*/
providers: (
productId: string,
options?: RequestOptions,
): Promise<{ data: DigitalAssetProvider[] }> =>
this.request<{ data: DigitalAssetProvider[] }>(
'GET',
`/products/${productId}/digital_assets/providers`,
options,
),
},
variants: {
list: (
productId: string,
params?: ListParams<VariantFilters, VariantSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Variant>> =>
this.request<PaginatedResponse<Variant>>('GET', `/products/${productId}/variants`, {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
productId: string,
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<Variant> =>
this.request<Variant>('GET', `/products/${productId}/variants/${id}`, {
...options,
params: getParams(params),
}),
create: (
productId: string,
params: VariantCreateParams,
options?: RequestOptions,
): Promise<Variant> =>
this.request<Variant>('POST', `/products/${productId}/variants`, {
...options,
body: params,
}),
update: (
productId: string,
id: string,
params: VariantUpdateParams,
options?: RequestOptions,
): Promise<Variant> =>
this.request<Variant>('PATCH', `/products/${productId}/variants/${id}`, {
...options,
body: params,
}),
delete: (productId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/products/${productId}/variants/${id}`, options),
media: {
list: (
productId: string,
variantId: string,
params?: ListParams<MediaFilters, MediaSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Media>> =>
this.request<PaginatedResponse<Media>>(
'GET',
`/products/${productId}/variants/${variantId}/media`,
{
...options,
params: params ? transformListParams(params) : undefined,
},
),
create: (
productId: string,
variantId: string,
params: MediaCreateParams,
options?: RequestOptions,
): Promise<Media> =>
this.request<Media>('POST', `/products/${productId}/variants/${variantId}/media`, {
...options,
body: params,
}),
update: (
productId: string,
variantId: string,
id: string,
params: MediaUpdateParams,
options?: RequestOptions,
): Promise<Media> =>
this.request<Media>('PATCH', `/products/${productId}/variants/${variantId}/media/${id}`, {
...options,
body: params,
}),
delete: (
productId: string,
variantId: string,
id: string,
options?: RequestOptions,
): Promise<void> =>
this.request<void>(
'DELETE',
`/products/${productId}/variants/${variantId}/media/${id}`,
options,
),
},
},
customFields: this.parentScopedCustomFields(CUSTOM_FIELD_OWNER_PATHS.product),
translations: this.parentScopedTranslations('/products'),
}
// ============================================
// Digital links
// ============================================
/**
* Download grants issued to customers when an order is placed. They are never
* created by hand — `reset` gives a customer their allowance back.
*/
readonly digitalLinks = {
list: (
params?: ListParams<DigitalLinkFilters, DigitalLinkSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<DigitalLink>> =>
this.request<PaginatedResponse<DigitalLink>>('GET', '/digital_links', {
...options,
params: params ? transformListParams(params) : undefined,
}),
retrieve: (id: string, options?: RequestOptions): Promise<DigitalLink> =>
this.request<DigitalLink>('GET', `/digital_links/${id}`, options),
reset: (id: string, options?: RequestOptions): Promise<DigitalLink> =>
this.request<DigitalLink>('PATCH', `/digital_links/${id}/reset`, options),
}
// ============================================
// Orders
// ============================================
readonly orders = {
list: (
params?: ListParams<OrderFilters, OrderSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Order>> =>
this.request<PaginatedResponse<Order>>('GET', '/orders', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Order> =>
this.request<Order>('GET', `/orders/${id}`, {
...options,
params: getParams(params),
}),
create: (params: OrderCreateParams, options?: RequestOptions): Promise<Order> =>
this.request<Order>('POST', '/orders', { ...options, body: params }),
update: (id: string, params: OrderUpdateParams, options?: RequestOptions): Promise<Order> =>
this.request<Order>('PATCH', `/orders/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/orders/${id}`, options),
/**
* An order holding several sellers' goods divides into one order per
* seller, and the group it produced is what comes back — narrow the result
* with `isOrderGroup`.
*/
complete: (
id: string,
params?: OrderCompleteParams,
options?: RequestOptions,
): Promise<Order | OrderGroup> =>
this.request<Order | OrderGroup>('PATCH', `/orders/${id}/complete`, {
...options,
body: params,
}),
cancel: (id: string, params?: OrderCancelParams, options?: RequestOptions): Promise<Order> =>
this.request<Order>('PATCH', `/orders/${id}/cancel`, { ...options, body: params }),
approve: (id: string, options?: RequestOptions): Promise<Order> =>
this.request<Order>('PATCH', `/orders/${id}/approve`, options),
resendConfirmation: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('POST', `/orders/${id}/resend_confirmation`, options),
/** Re-sends the "your files are ready" email. No-op when the order has no downloads. */
resendDigitalLinks: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('POST', `/orders/${id}/resend_digital_links`, options),
giftCards: {
apply: (
orderId: string,
params: GiftCardApplyParams,
options?: RequestOptions,
): Promise<unknown> =>
this.request('POST', `/orders/${orderId}/gift_cards`, { ...options, body: params }),
remove: (orderId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/orders/${orderId}/gift_cards/${id}`, options),
},
storeCredits: {
apply: (
orderId: string,
params?: StoreCreditApplyParams,
options?: RequestOptions,
): Promise<Order> =>
this.request<Order>('POST', `/orders/${orderId}/store_credits`, {
...options,
body: params,
}),
remove: (orderId: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/orders/${orderId}/store_credits`, options),
},
items: {
list: (
orderId: string,
params?: ListParams<LineItemFilters, LineItemSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<LineItem>> =>
this.request<PaginatedResponse<LineItem>>('GET', `/orders/${orderId}/items`, {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
orderId: string,
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<LineItem> =>
this.request<LineItem>('GET', `/orders/${orderId}/items/${id}`, {
...options,
params: getParams(params),
}),
create: (
orderId: string,
params: LineItemCreateParams,
options?: RequestOptions,
): Promise<LineItem> =>
this.request<LineItem>('POST', `/orders/${orderId}/items`, { ...options, body: params }),
update: (
orderId: string,
id: string,
params: LineItemUpdateParams,
options?: RequestOptions,
): Promise<LineItem> =>
this.request<LineItem>('PATCH', `/orders/${orderId}/items/${id}`, {
...options,
body: params,
}),
delete: (orderId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/orders/${orderId}/items/${id}`, options),
},
fulfillments: {
list: (
orderId: string,
params?: ListParams<FulfillmentFilters, FulfillmentSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Fulfillment>> =>
this.request<PaginatedResponse<Fulfillment>>('GET', `/orders/${orderId}/fulfillments`, {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
orderId: string,
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<Fulfillment> =>
this.request<Fulfillment>('GET', `/orders/${orderId}/fulfillments/${id}`, {
...options,
params: getParams(params),
}),
create: (
orderId: string,
params: FulfillmentCreateParams,
options?: RequestOptions,
): Promise<Fulfillment> =>
this.request<Fulfillment>('POST', `/orders/${orderId}/fulfillments`, {
...options,
body: params,
}),
update: (
orderId: string,
id: string,
params: FulfillmentUpdateParams,
options?: RequestOptions,
): Promise<Fulfillment> =>
this.request<Fulfillment>('PATCH', `/orders/${orderId}/fulfillments/${id}`, {
...options,
body: params,
}),
// Passing `items` ships only those quantities: they are split into a new
// fulfillment, which is what comes back — the addressed fulfillment keeps
// the remainder and stays open.
fulfill: (
orderId: string,
id: string,
params?: FulfillmentFulfillParams,
options?: RequestOptions,
): Promise<Fulfillment> =>
this.request<Fulfillment>('PATCH', `/orders/${orderId}/fulfillments/${id}/fulfill`, {
...options,
body: params,
}),
// Confirms the customer received the goods. Staff can record this by
// hand — a merchant with no carrier integration still needs a delivered
// state — and carriers reach the same endpoint through their webhooks.
markDelivered: (
orderId: string,
id: string,
params?: FulfillmentMarkDeliveredParams,
options?: RequestOptions,
): Promise<Fulfillment> =>
this.request<Fulfillment>('PATCH', `/orders/${orderId}/fulfillments/${id}/mark_delivered`, {
...options,
body: params,
}),
cancel: (orderId: string, id: string, options?: RequestOptions): Promise<Fulfillment> =>
this.request<Fulfillment>('PATCH', `/orders/${orderId}/fulfillments/${id}/cancel`, options),
/**
* The carrier documents bought or uploaded for a parcel. Creating one
* with no body buys it through the parcel's carrier account; creating it
* with a `file_signed_id` (from `files.upload()`) records
* postage the merchant bought elsewhere. To print one, fetch
* `download_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.
*/
labels: {
list: (
orderId: string,
fulfillmentId: string,
options?: RequestOptions,
): Promise<{ data: ShippingLabel[] }> =>
this.request<{ data: ShippingLabel[] }>(
'GET',
`/orders/${orderId}/fulfillments/${fulfillmentId}/labels`,
options,
),
get: (
orderId: string,
fulfillmentId: string,
id: string,
options?: RequestOptions,
): Promise<ShippingLabel> =>
this.request<ShippingLabel>(
'GET',
`/orders/${orderId}/fulfillments/${fulfillmentId}/labels/${id}`,
options,
),
create: (
orderId: string,
fulfillmentId: string,
params?: ShippingLabelCreateParams,
options?: RequestOptions,
): Promise<ShippingLabel> =>
this.request<ShippingLabel>(
'POST',
`/orders/${orderId}/fulfillments/${fulfillmentId}/labels`,
{ ...options, body: params },
),
/**
* Asks the carrier to refund a purchased label. The answer is
* `refunded` when the carrier settled at once, `refund_requested` when
* it will decide later. Uploaded labels cannot be refunded.
*/
refund: (
orderId: string,
fulfillmentId: string,
id: string,
options?: RequestOptions,
): Promise<ShippingLabel> =>
this.request<ShippingLabel>(
'PATCH',
`/orders/${orderId}/fulfillments/${fulfillmentId}/labels/${id}/refund`,
options,
),
/** Uploaded labels only — a purchased label is refunded instead. */
delete: (
orderId: string,
fulfillmentId: string,
id: string,
options?: RequestOptions,
): Promise<void> =>
this.request<void>(
'DELETE',
`/orders/${orderId}/fulfillments/${fulfillmentId}/labels/${id}`,
options,
),
},
/**
* The tracked consignments of a parcel — one per tracking number, each
* carrying the carrier status last reported. A fulfillment's own
* `tracking` field summarizes the first of them.
*/
deliveries: {
list: (
orderId: string,
fulfillmentId: string,
options?: RequestOptions,
): Promise<{ data: Delivery[] }> =>
this.request<{ data: Delivery[] }>(
'GET',
`/orders/${orderId}/fulfillments/${fulfillmentId}/deliveries`,
options,
),
get: (
orderId: string,
fulfillmentId: string,
id: string,
options?: RequestOptions,
): Promise<Delivery> =>
this.request<Delivery>(
'GET',
`/orders/${orderId}/fulfillments/${fulfillmentId}/deliveries/${id}`,
options,
),
create: (
orderId: string,
fulfillmentId: string,
params: DeliveryCreateParams,
options?: RequestOptions,
): Promise<Delivery> =>
this.request<Delivery>(
'POST',
`/orders/${orderId}/fulfillments/${fulfillmentId}/deliveries`,
{ ...options, body: params },
),
/** A corrected tracking number starts the carrier journey over. */
update: (
orderId: string,
fulfillmentId: string,
id: string,
params: DeliveryUpdateParams,
options?: RequestOptions,
): Promise<Delivery> =>
this.request<Delivery>(
'PATCH',
`/orders/${orderId}/fulfillments/${fulfillmentId}/deliveries/${id}`,
{ ...options, body: params },
),
/** Refused for a consignment a label minted — refund the label. */
delete: (
orderId: string,
fulfillmentId: string,
id: string,
options?: RequestOptions,
): Promise<void> =>
this.request<void>(
'DELETE',
`/orders/${orderId}/fulfillments/${fulfillmentId}/deliveries/${id}`,
options,
),
/**
* Staff confirming one consignment arrived. The parcel becomes
* delivered once every one of its consignments has.
*/
markDelivered: (
orderId: string,
fulfillmentId: string,
id: string,
params?: DeliveryMarkDeliveredParams,
options?: RequestOptions,
): Promise<Delivery> =>
this.request<Delivery>(
'PATCH',
`/orders/${orderId}/fulfillments/${fulfillmentId}/deliveries/${id}/mark_delivered`,
{ ...options, body: params },
),
},
// Returns every fulfillment on the order, since a split re-shapes the
// source as well as creating the new one (and destroys the source when
// it is fully drained).
split: (
orderId: string,
id: string,
params: FulfillmentSplitParams,
options?: RequestOptions,
): Promise<{ data: Fulfillment[] }> =>
this.request<{ data: Fulfillment[] }>(
'PATCH',
`/orders/${orderId}/fulfillments/${id}/split`,
{
...options,
body: params,
},
),
},
returns: {
list: (
orderId: string,
params?: ListParams<ReturnFilters, ReturnSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Return>> =>
this.request<PaginatedResponse<Return>>('GET', `/orders/${orderId}/returns`, {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
orderId: string,
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<Return> =>
this.request<Return>('GET', `/orders/${orderId}/returns/${id}`, {
...options,
params: getParams(params),
}),
create: (
orderId: string,
params: ReturnCreateParams,
options?: RequestOptions,
): Promise<Return> =>
this.request<Return>('POST', `/orders/${orderId}/returns`, {
...options,
body: params,
}),
update: (
orderId: string,
id: string,
params: ReturnUpdateParams,
options?: RequestOptions,
): Promise<Return> =>
this.request<Return>('PATCH', `/orders/${orderId}/returns/${id}`, {
...options,
body: params,
}),
approve: (orderId: string, id: string, options?: RequestOptions): Promise<Return> =>
this.request<Return>('PATCH', `/orders/${orderId}/returns/${id}/approve`, options),
receive: (
orderId: string,
id: string,
params?: ReturnReceiveParams,
options?: RequestOptions,
): Promise<Return> =>
this.request<Return>('PATCH', `/orders/${orderId}/returns/${id}/receive`, {
...options,
body: params,
}),
refund: (
orderId: string,
id: string,
params?: ReturnRefundParams,
options?: RequestOptions,
): Promise<Return> =>
this.request<Return>('PATCH', `/orders/${orderId}/returns/${id}/refund`, {
...options,
body: params,
}),
cancel: (
orderId: string,
id: string,
params?: ReturnCancelParams,
options?: RequestOptions,
): Promise<Return> =>
this.request<Return>('PATCH', `/orders/${orderId}/returns/${id}/cancel`, {
...options,
body: params,
}),
/**
* The prepaid label for the parcel coming back. Bought through the
* carrier that shipped the goods out, or recorded from a file when the
* merchant bought postage elsewhere — the same shape as a fulfillment's
* labels, owned by the return instead.
*
* The customer downloads it from the storefront; this is the merchant's
* side of the same record.
*/
labels: {
list: (
orderId: string,
returnId: string,
options?: RequestOptions,
): Promise<{ data: ShippingLabel[] }> =>
this.request<{ data: ShippingLabel[] }>(
'GET',
`/orders/${orderId}/returns/${returnId}/labels`,
options,
),
get: (
orderId: string,
returnId: string,
id: string,
options?: RequestOptions,
): Promise<ShippingLabel> =>
this.request<ShippingLabel>(
'GET',
`/orders/${orderId}/returns/${returnId}/labels/${id}`,
options,
),
create: (
orderId: string,
returnId: string,
params?: ShippingLabelCreateParams,
options?: RequestOptions,
): Promise<ShippingLabel> =>
this.request<ShippingLabel>('POST', `/orders/${orderId}/returns/${returnId}/labels`, {
...options,
body: params,
}),
refund: (
orderId: string,
returnId: string,
id: string,
options?: RequestOptions,
): Promise<ShippingLabel> =>
this.request<ShippingLabel>(
'PATCH',
`/orders/${orderId}/returns/${returnId}/labels/${id}/refund`,
options,
),
/** Uploaded labels only — a purchased label is refunded instead. */
delete: (
orderId: string,
returnId: string,
id: string,
options?: RequestOptions,
): Promise<void> =>
this.request<void>(
'DELETE',
`/orders/${orderId}/returns/${returnId}/labels/${id}`,
options,
),
},
},
exchanges: {
list: (
orderId: string,
params?: ListParams<ExchangeFilters, ExchangeSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Exchange>> =>
this.request<PaginatedResponse<Exchange>>('GET', `/orders/${orderId}/exchanges`, {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
orderId: string,
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<Exchange> =>
this.request<Exchange>('GET', `/orders/${orderId}/exchanges/${id}`, {
...options,
params: getParams(params),
}),
create: (
orderId: string,
params: ExchangeCreateParams,
options?: RequestOptions,
): Promise<Exchange> =>
this.request<Exchange>('POST', `/orders/${orderId}/exchanges`, {
...options,
body: params,
}),
update: (
orderId: string,
id: string,
params: ExchangeUpdateParams,
options?: RequestOptions,
): Promise<Exchange> =>
this.request<Exchange>('PATCH', `/orders/${orderId}/exchanges/${id}`, {
...options,
body: params,
}),
approve: (orderId: string, id: string, options?: RequestOptions): Promise<Exchange> =>
this.request<Exchange>('PATCH', `/orders/${orderId}/exchanges/${id}/approve`, options),
receive: (
orderId: string,
id: string,
params?: ExchangeReceiveParams,
options?: RequestOptions,
): Promise<Exchange> =>
this.request<Exchange>('PATCH', `/orders/${orderId}/exchanges/${id}/receive`, {
...options,
body: params,
}),
fulfill: (
orderId: string,
id: string,
params?: ExchangeFulfillParams,
options?: RequestOptions,
): Promise<Exchange> =>
this.request<Exchange>('PATCH', `/orders/${orderId}/exchanges/${id}/fulfill`, {
...options,
body: params,
}),
cancel: (
orderId: string,
id: string,
params?: ExchangeCancelParams,
options?: RequestOptions,
): Promise<Exchange> =>
this.request<Exchange>('PATCH', `/orders/${orderId}/exchanges/${id}/cancel`, {
...options,
body: params,
}),
},
claims: {
list: (
orderId: string,
params?: ListParams<ClaimFilters, ClaimSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Claim>> =>
this.request<PaginatedResponse<Claim>>('GET', `/orders/${orderId}/claims`, {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
orderId: string,
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<Claim> =>
this.request<Claim>('GET', `/orders/${orderId}/claims/${id}`, {
...options,
params: getParams(params),
}),
create: (
orderId: string,
params: ClaimCreateParams,
options?: RequestOptions,
): Promise<Claim> =>
this.request<Claim>('POST', `/orders/${orderId}/claims`, {
...options,
body: params,
}),
update: (
orderId: string,
id: string,
params: ClaimUpdateParams,
options?: RequestOptions,
): Promise<Claim> =>
this.request<Claim>('PATCH', `/orders/${orderId}/claims/${id}`, {
...options,
body: params,
}),
approve: (orderId: string, id: string, options?: RequestOptions): Promise<Claim> =>
this.request<Claim>('PATCH', `/orders/${orderId}/claims/${id}/approve`, options),
resolve: (
orderId: string,
id: string,
params: ClaimResolveParams,
options?: RequestOptions,
): Promise<Claim> =>
this.request<Claim>('PATCH', `/orders/${orderId}/claims/${id}/resolve`, {
...options,
body: params,
}),
deny: (
orderId: string,
id: string,
params?: ClaimDenyParams,
options?: RequestOptions,
): Promise<Claim> =>
this.request<Claim>('PATCH', `/orders/${orderId}/claims/${id}/deny`, {
...options,
body: params,
}),
cancel: (
orderId: string,
id: string,
params?: ClaimCancelParams,
options?: RequestOptions,
): Promise<Claim> =>
this.request<Claim>('PATCH', `/orders/${orderId}/claims/${id}/cancel`, {
...options,
body: params,
}),
},
payments: {
list: (
orderId: string,
params?: ListParams<PaymentFilters, PaymentSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Payment>> =>
this.request<PaginatedResponse<Payment>>('GET', `/orders/${orderId}/payments`, {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
orderId: string,
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<Payment> =>
this.request<Payment>('GET', `/orders/${orderId}/payments/${id}`, {
...options,
params: getParams(params),
}),
create: (
orderId: string,
params: PaymentCreateParams,
options?: RequestOptions,
): Promise<Payment> =>
this.request<Payment>('POST', `/orders/${orderId}/payments`, { ...options, body: params }),
/** Captures the payment: the full authorized amount, or `amount` for a partial capture. */
capture: (
orderId: string,
id: string,
params?: PaymentCaptureParams,
options?: RequestOptions,
): Promise<Payment> =>
this.request<Payment>('PATCH', `/orders/${orderId}/payments/${id}/capture`, {
...options,
body: params,
}),
void: (orderId: string, id: string, options?: RequestOptions): Promise<Payment> =>
this.request<Payment>('PATCH', `/orders/${orderId}/payments/${id}/void`, options),
},
refunds: {
list: (
orderId: string,
params?: ListParams<RefundFilters, RefundSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Refund>> =>
this.request<PaginatedResponse<Refund>>('GET', `/orders/${orderId}/refunds`, {
...options,
params: params ? transformListParams(params) : undefined,
}),
create: (
orderId: string,
params: RefundCreateParams,
options?: RequestOptions,
): Promise<Refund> =>
this.request<Refund>('POST', `/orders/${orderId}/refunds`, { ...options, body: params }),
},
taxLines: {
list: (
orderId: string,
params?: ListParams<TaxLineFilters, TaxLineSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<TaxLine>> =>
this.request<PaginatedResponse<TaxLine>>('GET', `/orders/${orderId}/tax_lines`, {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (orderId: string, id: string, options?: RequestOptions): Promise<TaxLine> =>
this.request<TaxLine>('GET', `/orders/${orderId}/tax_lines/${id}`, options),
},
discounts: {
list: (
orderId: string,
params?: ListParams<DiscountFilters, DiscountSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Discount>> =>
this.request<PaginatedResponse<Discount>>('GET', `/orders/${orderId}/discounts`, {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (orderId: string, id: string, options?: RequestOptions): Promise<Discount> =>
this.request<Discount>('GET', `/orders/${orderId}/discounts/${id}`, options),
/**
* Creates a manual discount. With `line_item_id` a single row is
* created; without it the value is distributed across line items
* (largest remainder). Works on completed orders.
*/
create: (
orderId: string,
params: DiscountCreateParams,
options?: RequestOptions,
): Promise<{ data: Discount[] }> =>
this.request<{ data: Discount[] }>('POST', `/orders/${orderId}/discounts`, {
...options,
body: params,
}),
/** Manual rows only — promotion-sourced rows respond 422 (`discount_not_editable`). */
update: (
orderId: string,
id: string,
params: DiscountUpdateParams,
options?: RequestOptions,
): Promise<Discount> =>
this.request<Discount>('PATCH', `/orders/${orderId}/discounts/${id}`, {
...options,
body: params,
}),
/** Manual rows only — promotion-sourced rows respond 422 (`discount_not_editable`). */
delete: (orderId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/orders/${orderId}/discounts/${id}`, options),
},
/**
* Discount codes on a draft order — same pending semantics as the
* storefront cart endpoint (a real-but-not-yet-eligible code is stored
* and activates on recalculation). Completed orders respond 422
* (`discount_not_editable`); use manual discounts instead.
*/
discountCodes: {
create: (
orderId: string,
params: DiscountCodeApplyParams,
options?: RequestOptions,
): Promise<Order> =>
this.request<Order>('POST', `/orders/${orderId}/discount_codes`, {
...options,
body: params,
}),
/** `code` is the discount code string, not an ID. */
delete: (orderId: string, code: string, options?: RequestOptions): Promise<Order> =>
this.request<Order>(
'DELETE',
`/orders/${orderId}/discount_codes/${encodeURIComponent(code)}`,
options,
),
},
fees: {
list: (
orderId: string,
params?: ListParams<FeeFilters, FeeSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Fee>> =>
this.request<PaginatedResponse<Fee>>('GET', `/orders/${orderId}/fees`, {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (orderId: string, id: string, options?: RequestOptions): Promise<Fee> =>
this.request<Fee>('GET', `/orders/${orderId}/fees/${id}`, options),
create: (orderId: string, params: FeeCreateParams, options?: RequestOptions): Promise<Fee> =>
this.request<Fee>('POST', `/orders/${orderId}/fees`, { ...options, body: params }),
update: (
orderId: string,
id: string,
params: FeeUpdateParams,
options?: RequestOptions,
): Promise<Fee> =>
this.request<Fee>('PATCH', `/orders/${orderId}/fees/${id}`, { ...options, body: params }),
delete: (orderId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/orders/${orderId}/fees/${id}`, options),
},
customFields: this.parentScopedCustomFields(CUSTOM_FIELD_OWNER_PATHS.order),
}
// ============================================
// Option Types
// ============================================
readonly optionTypes = {
list: (
params?: ListParams<OptionTypeFilters, OptionTypeSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<OptionType>> =>
this.request<PaginatedResponse<OptionType>>('GET', '/option_types', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<OptionType> =>
this.request<OptionType>('GET', `/option_types/${id}`, {
...options,
params: getParams(params),
}),
create: (params: OptionTypeCreateParams, options?: RequestOptions): Promise<OptionType> =>
this.request<OptionType>('POST', '/option_types', { ...options, body: params }),
update: (
id: string,
params: OptionTypeUpdateParams,
options?: RequestOptions,
): Promise<OptionType> =>
this.request<OptionType>('PATCH', `/option_types/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/option_types/${id}`, options),
customFields: this.parentScopedCustomFields(CUSTOM_FIELD_OWNER_PATHS.option_type),
translations: this.parentScopedTranslations('/option_types'),
}
// ============================================
// Payment Methods
// ============================================
readonly deliveryMethods = {
list: (
params?: ListParams<DeliveryMethodFilters, DeliveryMethodSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<DeliveryMethod>> =>
this.request<PaginatedResponse<DeliveryMethod>>('GET', '/delivery_methods', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, options?: RequestOptions): Promise<DeliveryMethod> =>
this.request<DeliveryMethod>('GET', `/delivery_methods/${id}`, options),
create: (
params: DeliveryMethodCreateParams,
options?: RequestOptions,
): Promise<DeliveryMethod> =>
this.request<DeliveryMethod>('POST', '/delivery_methods', { ...options, body: params }),
update: (
id: string,
params: DeliveryMethodUpdateParams,
options?: RequestOptions,
): Promise<DeliveryMethod> =>
this.request<DeliveryMethod>('PATCH', `/delivery_methods/${id}`, {
...options,
body: params,
}),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/delivery_methods/${id}`, options),
/** Registered delivery calculator classes, each with the JSON Schema of its preferences. */
calculators: (
options?: RequestOptions,
): Promise<{ data: Array<{ type: string; name: string; schema: PreferenceSchema }> }> =>
this.request<{ data: Array<{ type: string; name: string; schema: PreferenceSchema }> }>(
'GET',
'/delivery_methods/calculators',
options,
),
/**
* Registered fulfillment provider strategies plus the registered
* fulfillment-type vocabulary (the strict set delivery methods and
* product types validate against).
*/
fulfillmentProviders: (
options?: RequestOptions,
): Promise<{ data: FulfillmentProviderOption[] }> =>
this.request<{ data: FulfillmentProviderOption[] }>(
'GET',
'/delivery_methods/fulfillment_providers',
options,
),
/** Rate providers available to this store, plus the default when none is chosen. */
rateProviders: (
options?: RequestOptions,
): Promise<{ data: DeliveryRateProviderOption[]; default: string }> =>
this.request<{ data: DeliveryRateProviderOption[]; default: string }>(
'GET',
'/delivery_methods/rate_providers',
options,
),
/** Eligibility rules on a delivery method (item total / weight bounds, …). */
rules: {
list: (
deliveryMethodId: string,
options?: RequestOptions,
): Promise<PaginatedResponse<DeliveryMethodRule>> =>
this.request<PaginatedResponse<DeliveryMethodRule>>(
'GET',
`/delivery_methods/${deliveryMethodId}/rules`,
options,
),
create: (
deliveryMethodId: string,
params: DeliveryMethodRuleCreateParams,
options?: RequestOptions,
): Promise<DeliveryMethodRule> =>
this.request<DeliveryMethodRule>('POST', `/delivery_methods/${deliveryMethodId}/rules`, {
...options,
body: params,
}),
update: (
deliveryMethodId: string,
id: string,
params: DeliveryMethodRuleUpdateParams,
options?: RequestOptions,
): Promise<DeliveryMethodRule> =>
this.request<DeliveryMethodRule>(
'PATCH',
`/delivery_methods/${deliveryMethodId}/rules/${id}`,
{ ...options, body: params },
),
delete: (deliveryMethodId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/delivery_methods/${deliveryMethodId}/rules/${id}`, options),
},
/** Registered rule kinds with preference schemas for building pickers. */
ruleTypes: (
options?: RequestOptions,
): Promise<{
data: Array<{
type: string
name: string
description: string
schema: PreferenceSchema
/** Association-backed config the rule accepts, e.g. `['product_ids']`. */
association_fields: string[]
}>
}> =>
this.request<{
data: Array<{
type: string
name: string
description: string
schema: PreferenceSchema
association_fields: string[]
}>
}>('GET', '/delivery_method_rules/types', options),
}
readonly deliveryProfiles = {
list: (
params?: ListParams<DeliveryProfileFilters, DeliveryProfileSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<DeliveryProfile>> =>
this.request<PaginatedResponse<DeliveryProfile>>('GET', '/delivery_profiles', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, options?: RequestOptions): Promise<DeliveryProfile> =>
this.request<DeliveryProfile>('GET', `/delivery_profiles/${id}`, options),
create: (
params: DeliveryProfileCreateParams,
options?: RequestOptions,
): Promise<DeliveryProfile> =>
this.request<DeliveryProfile>('POST', '/delivery_profiles', {
...options,
body: params,
}),
/** `stock_location_ids` replaces the profile's full location set. */
update: (
id: string,
params: DeliveryProfileUpdateParams,
options?: RequestOptions,
): Promise<DeliveryProfile> =>
this.request<DeliveryProfile>('PATCH', `/delivery_profiles/${id}`, {
...options,
body: params,
}),
/** The default profile and profiles still referenced by products cannot be deleted. */
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/delivery_profiles/${id}`, options),
/** Registered profile kinds (shipping, digital, extension kinds). */
kinds: (options?: RequestOptions): Promise<{ data: Array<{ kind: string }> }> =>
this.request<{ data: Array<{ kind: string }> }>('GET', '/delivery_profiles/kinds', options),
/** Origin groups partition a profile's fulfillment origins; its zones and methods each belong to one. */
originGroups: {
list: (
deliveryProfileId: string,
options?: RequestOptions,
): Promise<PaginatedResponse<DeliveryOriginGroup>> =>
this.request<PaginatedResponse<DeliveryOriginGroup>>(
'GET',
`/delivery_profiles/${deliveryProfileId}/origin_groups`,
options,
),
create: (
deliveryProfileId: string,
params: DeliveryOriginGroupParams,
options?: RequestOptions,
): Promise<DeliveryOriginGroup> =>
this.request<DeliveryOriginGroup>(
'POST',
`/delivery_profiles/${deliveryProfileId}/origin_groups`,
{ ...options, body: params },
),
update: (
deliveryProfileId: string,
id: string,
params: DeliveryOriginGroupParams,
options?: RequestOptions,
): Promise<DeliveryOriginGroup> =>
this.request<DeliveryOriginGroup>(
'PATCH',
`/delivery_profiles/${deliveryProfileId}/origin_groups/${id}`,
{ ...options, body: params },
),
/** The last group, or one still holding zones or methods, cannot be deleted. */
delete: (deliveryProfileId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>(
'DELETE',
`/delivery_profiles/${deliveryProfileId}/origin_groups/${id}`,
options,
),
},
}
readonly trackingCarriers = {
/**
* Registered tracking carriers (Spree.tracking_carriers) a tracking
* number can be pinned to — the source for carrier pickers. Extensions
* that register carriers appear here without a client change.
*/
list: (options?: RequestOptions): Promise<{ data: TrackingCarrierOption[] }> =>
this.request<{ data: TrackingCarrierOption[] }>('GET', '/tracking_carriers', options),
}
readonly deliveryZones = {
list: (
params?: ListParams<DeliveryZoneFilters, DeliveryZoneSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<DeliveryZone>> =>
this.request<PaginatedResponse<DeliveryZone>>('GET', '/delivery_zones', {
...options,
params: params ? transformListParams(params) : undefined,
}),
/** Members are expand-gated; pass `{ expand: ['members'] }` to edit a zone. */
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<DeliveryZone> =>
this.request<DeliveryZone>('GET', `/delivery_zones/${id}`, {
...options,
params: getParams(params),
}),
create: (params: DeliveryZoneCreateParams, options?: RequestOptions): Promise<DeliveryZone> =>
this.request<DeliveryZone>('POST', '/delivery_zones', { ...options, body: params }),
/** `members` replaces the zone's full member set atomically. */
update: (
id: string,
params: DeliveryZoneUpdateParams,
options?: RequestOptions,
): Promise<DeliveryZone> =>
this.request<DeliveryZone>('PATCH', `/delivery_zones/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/delivery_zones/${id}`, options),
}
readonly packageTypes = {
list: (
params?: ListParams<PackageTypeFilters, PackageTypeSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<PackageType>> =>
this.request<PaginatedResponse<PackageType>>('GET', '/package_types', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, options?: RequestOptions): Promise<PackageType> =>
this.request<PackageType>('GET', `/package_types/${id}`, options),
create: (params: PackageTypeCreateParams, options?: RequestOptions): Promise<PackageType> =>
this.request<PackageType>('POST', '/package_types', { ...options, body: params }),
/** Setting `default` demotes whichever row was the store's box before. */
update: (
id: string,
params: PackageTypeUpdateParams,
options?: RequestOptions,
): Promise<PackageType> =>
this.request<PackageType>('PATCH', `/package_types/${id}`, { ...options, body: params }),
/** Refused while a variant is packed into it. */
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/package_types/${id}`, options),
}
readonly paymentMethods = {
list: (
params?: ListParams<PaymentMethodFilters, PaymentMethodSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<PaymentMethod>> =>
this.request<PaginatedResponse<PaymentMethod>>('GET', '/payment_methods', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<PaymentMethod> =>
this.request<PaymentMethod>('GET', `/payment_methods/${id}`, {
...options,
params: getParams(params),
}),
create: (params: PaymentMethodCreateParams, options?: RequestOptions): Promise<PaymentMethod> =>
this.request<PaymentMethod>('POST', '/payment_methods', { ...options, body: params }),
update: (
id: string,
params: PaymentMethodUpdateParams,
options?: RequestOptions,
): Promise<PaymentMethod> =>
this.request<PaymentMethod>('PATCH', `/payment_methods/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/payment_methods/${id}`, options),
types: (options?: RequestOptions): Promise<{ data: PaymentMethodType[] }> =>
this.request<{ data: PaymentMethodType[] }>('GET', '/payment_methods/types', options),
}
// ============================================
// Integrations (admin-only — provider credentials per store)
// ============================================
readonly integrations = {
list: (
params?: ListParams<IntegrationFilters, IntegrationSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Integration>> =>
this.request<PaginatedResponse<Integration>>('GET', '/integrations', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, options?: RequestOptions): Promise<Integration> =>
this.request<Integration>('GET', `/integrations/${id}`, options),
create: (params: IntegrationCreateParams, options?: RequestOptions): Promise<Integration> =>
this.request<Integration>('POST', '/integrations', { ...options, body: params }),
update: (
id: string,
params: IntegrationUpdateParams,
options?: RequestOptions,
): Promise<Integration> =>
this.request<Integration>('PATCH', `/integrations/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/integrations/${id}`, options),
/** Registered integration types with schemas and per-store connected state. */
types: (options?: RequestOptions): Promise<{ data: IntegrationTypeDefinition[] }> =>
this.request<{ data: IntegrationTypeDefinition[] }>('GET', '/integrations/types', options),
/** Live connection check; nothing is persisted. */
test: (
id: string,
options?: RequestOptions,
): Promise<{ connected: boolean; error_message: string | null }> =>
this.request<{ connected: boolean; error_message: string | null }>(
'POST',
`/integrations/${id}/test`,
options,
),
}
// ============================================
// Price Lists (admin-only — wholesale, regional, volume pricing)
// ============================================
/**
* CRUD plus lifecycle (`activate` / `deactivate`) for `Spree::PriceList`.
* Membership (`product_ids: [...]`), rules (`rules: [...]`), and per-row
* price overrides (`prices: [...]`) all ride along on the normal
* `update` payload — one PATCH saves the entire editor. The
* spreadsheet's initial render data is fetched via
* `prices.list({ price_list_id_eq: …, currency_eq: … })`. Price lists
* are admin-only; the storefront only ever sees the resolved price
* (see `PriceSerializer#price_list_id`).
*/
readonly priceLists = {
list: (
params?: ListParams<PriceListFilters, PriceListSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<PriceList>> =>
this.request<PaginatedResponse<PriceList>>('GET', '/price_lists', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<PriceList> =>
this.request<PriceList>('GET', `/price_lists/${id}`, {
...options,
params: getParams(params),
}),
create: (params: PriceListCreateParams, options?: RequestOptions): Promise<PriceList> =>
this.request<PriceList>('POST', '/price_lists', { ...options, body: params }),
update: (
id: string,
params: PriceListUpdateParams,
options?: RequestOptions,
): Promise<PriceList> =>
this.request<PriceList>('PATCH', `/price_lists/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/price_lists/${id}`, options),
/** draft|inactive → active (or → scheduled if `starts_at` is in the future). */
/** Which products the list prices — the same nested surface categories,
* collections and catalogs expose. Adding materializes placeholder
* prices per variant × currency; removing hard-deletes the rows. */
products: this.productMembership<PriceListProduct>('/price_lists'),
activate: (id: string, options?: RequestOptions): Promise<PriceList> =>
this.request<PriceList>('PATCH', `/price_lists/${id}/activate`, options),
/** active|scheduled → inactive. */
deactivate: (id: string, options?: RequestOptions): Promise<PriceList> =>
this.request<PriceList>('PATCH', `/price_lists/${id}/deactivate`, options),
/**
* Returns `[{ type, label, description, schema }]` for
* every registered subclass in `Spree.pricing.rules`. Used to build
* the "Add rule" picker + render a generic preferences form per
* subclass. Rules themselves are not a separate REST resource —
* the SPA ships them inline on the list's `update` payload.
*/
ruleTypes: (options?: RequestOptions): Promise<{ data: ResourceTypeDefinition[] }> =>
this.request<{ data: ResourceTypeDefinition[] }>(
'GET',
'/price_lists/price_rule_types',
options,
),
}
// ============================================
// Prices (generic — base prices AND price-list overrides)
// ============================================
/**
* CRUD + bulk endpoints for `Spree::Price`. One resource covers both
* base prices (`price_list_id: null`) and price-list overrides
* (`price_list_id: pl_…`). The spreadsheet UI for a price list uses
* `list({ price_list_id_eq, currency_eq, page, limit })` for the
* paginated read and `bulkUpsert(...)` for the save.
*/
readonly prices = {
list: (
params?: ListParams<PriceFilters, PriceSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Price>> =>
this.request<PaginatedResponse<Price>>('GET', '/prices', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Price> =>
this.request<Price>('GET', `/prices/${id}`, {
...options,
params: getParams(params),
}),
create: (params: PriceCreateParams, options?: RequestOptions): Promise<Price> =>
this.request<Price>('POST', '/prices', { ...options, body: params }),
update: (id: string, params: PriceUpdateParams, options?: RequestOptions): Promise<Price> =>
this.request<Price>('PATCH', `/prices/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/prices/${id}`, options),
/**
* One SQL round trip via `upsert_all` — model callbacks (PriceHistory,
* after_save hooks) are bypassed for speed. Caller is responsible
* for shipping sane values. Response is just `{ price_count }`: the
* number of rows the DB touched.
*/
bulkUpsert: (
params: PriceBulkUpsertParams,
options?: RequestOptions,
): Promise<{ price_count: number }> =>
this.request('POST', '/prices/bulk_upsert', { ...options, body: params }),
bulkDestroy: (
params: PriceBulkDestroyParams,
options?: RequestOptions,
): Promise<{ price_count: number }> =>
this.request('DELETE', '/prices/bulk_destroy', { ...options, body: params }),
}
// ============================================
// Promotions (with nested actions, rules, coupon codes)
// ============================================
readonly promotions = {
list: (
params?: ListParams<PromotionFilters, PromotionSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Promotion>> =>
this.request<PaginatedResponse<Promotion>>('GET', '/promotions', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<Promotion> =>
this.request<Promotion>('GET', `/promotions/${id}`, {
...options,
params: getParams(params),
}),
create: (params: PromotionCreateParams, options?: RequestOptions): Promise<Promotion> =>
this.request<Promotion>('POST', '/promotions', { ...options, body: params }),
update: (
id: string,
params: PromotionUpdateParams,
options?: RequestOptions,
): Promise<Promotion> =>
this.request<Promotion>('PATCH', `/promotions/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/promotions/${id}`, options),
actions: {
list: (
promotionId: string,
params?: ListParams<PromotionActionFilters, PromotionActionSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<PromotionAction>> =>
this.request<PaginatedResponse<PromotionAction>>(
'GET',
`/promotions/${promotionId}/promotion_actions`,
{ ...options, params: params ? transformListParams(params) : undefined },
),
get: (promotionId: string, id: string, options?: RequestOptions): Promise<PromotionAction> =>
this.request<PromotionAction>(
'GET',
`/promotions/${promotionId}/promotion_actions/${id}`,
options,
),
create: (
promotionId: string,
params: PromotionActionCreateParams,
options?: RequestOptions,
): Promise<PromotionAction> =>
this.request<PromotionAction>('POST', `/promotions/${promotionId}/promotion_actions`, {
...options,
body: params,
}),
update: (
promotionId: string,
id: string,
params: PromotionActionUpdateParams,
options?: RequestOptions,
): Promise<PromotionAction> =>
this.request<PromotionAction>(
'PATCH',
`/promotions/${promotionId}/promotion_actions/${id}`,
{ ...options, body: params },
),
delete: (promotionId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/promotions/${promotionId}/promotion_actions/${id}`, options),
},
rules: {
list: (
promotionId: string,
params?: ListParams<PromotionRuleFilters, PromotionRuleSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<PromotionRule>> =>
this.request<PaginatedResponse<PromotionRule>>(
'GET',
`/promotions/${promotionId}/promotion_rules`,
{ ...options, params: params ? transformListParams(params) : undefined },
),
get: (promotionId: string, id: string, options?: RequestOptions): Promise<PromotionRule> =>
this.request<PromotionRule>(
'GET',
`/promotions/${promotionId}/promotion_rules/${id}`,
options,
),
create: (
promotionId: string,
params: PromotionRuleCreateParams,
options?: RequestOptions,
): Promise<PromotionRule> =>
this.request<PromotionRule>('POST', `/promotions/${promotionId}/promotion_rules`, {
...options,
body: params,
}),
update: (
promotionId: string,
id: string,
params: PromotionRuleUpdateParams,
options?: RequestOptions,
): Promise<PromotionRule> =>
this.request<PromotionRule>('PATCH', `/promotions/${promotionId}/promotion_rules/${id}`, {
...options,
body: params,
}),
delete: (promotionId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/promotions/${promotionId}/promotion_rules/${id}`, options),
},
couponCodes: {
list: (
promotionId: string,
params?: ListParams<CouponCodeFilters, CouponCodeSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<CouponCode>> =>
this.request<PaginatedResponse<CouponCode>>(
'GET',
`/promotions/${promotionId}/coupon_codes`,
{ ...options, params: params ? transformListParams(params) : undefined },
),
get: (promotionId: string, id: string, options?: RequestOptions): Promise<CouponCode> =>
this.request<CouponCode>('GET', `/promotions/${promotionId}/coupon_codes/${id}`, options),
},
}
readonly promotionActions = {
types: (options?: RequestOptions): Promise<{ data: ResourceTypeDefinition[] }> =>
this.request<{ data: ResourceTypeDefinition[] }>('GET', '/promotion_actions/types', options),
calculators: (
type: string,
options?: RequestOptions,
): Promise<{ data: PromotionActionCalculator[] }> =>
this.request<{ data: PromotionActionCalculator[] }>('GET', '/promotion_actions/calculators', {
...options,
params: { type },
}),
}
readonly promotionRules = {
types: (options?: RequestOptions): Promise<{ data: ResourceTypeDefinition[] }> =>
this.request<{ data: ResourceTypeDefinition[] }>('GET', '/promotion_rules/types', options),
}
// ============================================
// Tags
// ============================================
readonly tags = {
list: (
/** `taggable_type` is the tagged resource's shorthand: `product`, `order` or `customer`. */
params: { taggable_type: string; q?: string },
options?: RequestOptions,
): Promise<{ data: Array<{ name: string }> }> =>
this.request<{ data: Array<{ name: string }> }>('GET', '/tags', {
...options,
params,
}),
}
// ============================================
// Customer groups
// ============================================
readonly customerGroups = {
list: (
params?: ListParams<CustomerGroupFilters, CustomerGroupSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<CustomerGroup>> =>
this.request<PaginatedResponse<CustomerGroup>>('GET', '/customer_groups', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<CustomerGroup> =>
this.request<CustomerGroup>('GET', `/customer_groups/${id}`, {
...options,
params: getParams(params),
}),
create: (params: CustomerGroupCreateParams, options?: RequestOptions): Promise<CustomerGroup> =>
this.request<CustomerGroup>('POST', '/customer_groups', { ...options, body: params }),
update: (
id: string,
params: CustomerGroupUpdateParams,
options?: RequestOptions,
): Promise<CustomerGroup> =>
this.request<CustomerGroup>('PATCH', `/customer_groups/${id}`, {
...options,
body: params,
}),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/customer_groups/${id}`, options),
}
// ============================================
// Marketplace sellers
// ============================================
/**
* CRUD for `Spree::Seller`, plus the lifecycle actions. Status is never
* writable through `update` — each transition is a workflow that also
* sends mail and runs extension hooks, so moving a seller by hand would
* skip all of it.
*/
readonly sellers = {
list: (
params?: ListParams<SellerFilters, SellerSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Seller>> =>
this.request<PaginatedResponse<Seller>>('GET', '/sellers', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Seller> =>
this.request<Seller>('GET', `/sellers/${id}`, {
...options,
params: getParams(params),
}),
create: (params: SellerCreateParams, options?: RequestOptions): Promise<Seller> =>
this.request<Seller>('POST', '/sellers', { ...options, body: params }),
update: (id: string, params: SellerUpdateParams, options?: RequestOptions): Promise<Seller> =>
this.request<Seller>('PATCH', `/sellers/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/sellers/${id}`, options),
/** Opens the seller's team to someone; they join when they accept. */
invite: (id: string, params: SellerInviteParams, options?: RequestOptions): Promise<Seller> =>
this.request<Seller>('POST', `/sellers/${id}/invite`, { ...options, body: params }),
/**
* Lets the seller trade — also the way back from suspended or rejected.
* Refused while a required onboarding requirement is unmet, unless
* `override_requirements` says the operator means it anyway.
*/
approve: (
id: string,
params?: SellerApproveParams,
options?: RequestOptions,
): Promise<Seller> =>
this.request<Seller>('PATCH', `/sellers/${id}/approve`, { ...options, body: params }),
/** Where this seller stands against the marketplace's checklist. */
onboarding: (id: string, options?: RequestOptions): Promise<SellerOnboarding> =>
this.request<SellerOnboarding>('GET', `/sellers/${id}/onboarding`, options),
/** Sends a seller awaiting review back to onboarding, with a note. */
reopenOnboarding: (
id: string,
params?: SellerReopenOnboardingParams,
options?: RequestOptions,
): Promise<Seller> =>
this.request<Seller>('PATCH', `/sellers/${id}/reopen_onboarding`, {
...options,
body: params,
}),
/**
* Who runs this seller. The operator's view of what the seller panel
* manages for itself — and the only way to repair a seller whose team has
* locked itself out.
*/
team: {
list: (sellerId: string, options?: RequestOptions): Promise<{ data: SellerTeamMember[] }> =>
this.request<{ data: SellerTeamMember[] }>('GET', `/sellers/${sellerId}/team`, options),
/** Revokes a member's access. */
delete: (sellerId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/sellers/${sellerId}/team/${id}`, options),
},
/** Offers to join this seller that nobody has accepted yet. */
invitations: {
list: (sellerId: string, options?: RequestOptions): Promise<{ data: Invitation[] }> =>
this.request<{ data: Invitation[] }>('GET', `/sellers/${sellerId}/invitations`, options),
/** Withdraws an offer. */
delete: (sellerId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/sellers/${sellerId}/invitations/${id}`, options),
/** Sends the email again; refused once the offer has lapsed. */
resend: (sellerId: string, id: string, options?: RequestOptions): Promise<Invitation> =>
this.request<Invitation>('PATCH', `/sellers/${sellerId}/invitations/${id}/resend`, options),
/** The link that joins the seller's team; needs write access to sellers. */
acceptanceLink: (
sellerId: string,
id: string,
options?: RequestOptions,
): Promise<InvitationAcceptanceLink> =>
this.request<InvitationAcceptanceLink>(
'GET',
`/sellers/${sellerId}/invitations/${id}/acceptance_link`,
options,
),
},
/** What this seller submitted about the requirements, and its decisions. */
requirementSubmissions: {
list: (
sellerId: string,
params?: ListParams<SellerRequirementSubmissionFilters, SellerRequirementSubmissionSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<SellerRequirementSubmission>> =>
this.request<PaginatedResponse<SellerRequirementSubmission>>(
'GET',
`/sellers/${sellerId}/requirement_submissions`,
{ ...options, params: params ? transformListParams(params) : undefined },
),
get: (
sellerId: string,
id: string,
options?: RequestOptions,
): Promise<SellerRequirementSubmission> =>
this.request<SellerRequirementSubmission>(
'GET',
`/sellers/${sellerId}/requirement_submissions/${id}`,
options,
),
accept: (
sellerId: string,
id: string,
params?: SellerRequirementReviewParams,
options?: RequestOptions,
): Promise<SellerRequirementSubmission> =>
this.request<SellerRequirementSubmission>(
'PATCH',
`/sellers/${sellerId}/requirement_submissions/${id}/accept`,
{ ...options, body: params },
),
reject: (
sellerId: string,
id: string,
params?: SellerRequirementReviewParams,
options?: RequestOptions,
): Promise<SellerRequirementSubmission> =>
this.request<SellerRequirementSubmission>(
'PATCH',
`/sellers/${sellerId}/requirement_submissions/${id}/reject`,
{ ...options, body: params },
),
/** Excuses this seller from one requirement the store asks of everyone. */
waive: (
sellerId: string,
params: SellerRequirementWaiveParams,
options?: RequestOptions,
): Promise<SellerRequirementSubmission> =>
this.request<SellerRequirementSubmission>(
'POST',
`/sellers/${sellerId}/requirement_submissions`,
{ ...options, body: params },
),
},
suspend: (
id: string,
params?: SellerSuspendParams,
options?: RequestOptions,
): Promise<Seller> =>
this.request<Seller>('PATCH', `/sellers/${id}/suspend`, { ...options, body: params }),
reject: (id: string, params?: SellerRejectParams, options?: RequestOptions): Promise<Seller> =>
this.request<Seller>('PATCH', `/sellers/${id}/reject`, { ...options, body: params }),
/**
* Where this seller stands, one row per currency: earned, paid, still
* owed, and earnings the payout provider has not yet confirmed.
*/
balances: (id: string, options?: RequestOptions): Promise<{ data: SellerBalance[] }> =>
this.request<{ data: SellerBalance[] }>('GET', `/sellers/${id}/balances`, options),
/**
* Settles this seller now, sweeping everything they are owed into a
* payout per currency.
*
* What the `manual` payout interval means — the scheduled sweep skips
* those sellers, leaving the operator to decide when. Also the way to pay
* any seller early. Answers 422 when there is nothing to settle.
*/
settle: (id: string, options?: RequestOptions): Promise<{ data: SellerPayout[] }> =>
this.request<{ data: SellerPayout[] }>('POST', `/sellers/${id}/payouts`, options),
customFields: this.parentScopedCustomFields(CUSTOM_FIELD_OWNER_PATHS.seller),
}
// ============================================
// Seller onboarding requirements
// ============================================
/**
* What this marketplace asks of a seller before it will let them trade.
* Rows the operator composes from registered kinds — `types()` is what a
* picker renders, and a marketplace's own kinds appear there as soon as
* they are registered server-side.
*/
readonly sellerRequirements = {
list: (
params?: ListParams<SellerRequirementFilters, SellerRequirementSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<SellerRequirement>> =>
this.request<PaginatedResponse<SellerRequirement>>('GET', '/seller_requirements', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, options?: RequestOptions): Promise<SellerRequirement> =>
this.request<SellerRequirement>('GET', `/seller_requirements/${id}`, options),
create: (
params: SellerRequirementCreateParams,
options?: RequestOptions,
): Promise<SellerRequirement> =>
this.request<SellerRequirement>('POST', '/seller_requirements', { ...options, body: params }),
update: (
id: string,
params: SellerRequirementUpdateParams,
options?: RequestOptions,
): Promise<SellerRequirement> =>
this.request<SellerRequirement>('PATCH', `/seller_requirements/${id}`, {
...options,
body: params,
}),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/seller_requirements/${id}`, options),
/** The kinds an operator can add, with each one's configuration shape. */
types: (options?: RequestOptions): Promise<{ data: SellerRequirementType[] }> =>
this.request<{ data: SellerRequirementType[] }>('GET', '/seller_requirements/types', options),
}
// ============================================
// Commissions (what the marketplace charges its sellers)
// ============================================
/**
* CRUD for `Spree::CommissionRate`. Targeting rides the regular payload as
* `rules: [...]` — the whole editor saves in one round-trip, and the server
* replaces the rate's rules with exactly what it is sent.
*/
readonly commissionRates = {
list: (
params?: ListParams<CommissionRateFilters, CommissionRateSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<CommissionRate>> =>
this.request<PaginatedResponse<CommissionRate>>('GET', '/commission_rates', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<CommissionRate> =>
this.request<CommissionRate>('GET', `/commission_rates/${id}`, {
...options,
params: getParams(params),
}),
create: (
params: CommissionRateCreateParams,
options?: RequestOptions,
): Promise<CommissionRate> =>
this.request<CommissionRate>('POST', '/commission_rates', { ...options, body: params }),
update: (
id: string,
params: CommissionRateUpdateParams,
options?: RequestOptions,
): Promise<CommissionRate> =>
this.request<CommissionRate>('PATCH', `/commission_rates/${id}`, {
...options,
body: params,
}),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/commission_rates/${id}`, options),
/**
* Every registered rule kind with the schema describing its configuration,
* so a client builds its editor from what the marketplace actually has
* rather than a list hardcoded to match core's.
*/
ruleTypes: (options?: RequestOptions): Promise<{ data: CommissionRuleType[] }> =>
this.request<{ data: CommissionRuleType[] }>('GET', '/commission_rates/rule_types', options),
}
/**
* Read-only view of `Spree::CommissionLine` — what each sale actually earned
* the marketplace, frozen when the order was placed. There is no write path:
* correcting a charge is a reversal, not an edit.
*/
readonly commissionLines = {
list: (
params?: ListParams<CommissionLineFilters, CommissionLineSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<CommissionLine>> =>
this.request<PaginatedResponse<CommissionLine>>('GET', '/commission_lines', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<CommissionLine> =>
this.request<CommissionLine>('GET', `/commission_lines/${id}`, {
...options,
params: getParams(params),
}),
}
/**
* `Spree::OrderGroup` — the checkout a split basket produced, and the
* payments made against it. An order placed in one has no payments of its
* own: its share of each of these is in its `payment_splits`.
*/
readonly orderGroups = {
list: (
params?: ListParams<OrderGroupFilters, OrderGroupSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<OrderGroup>> =>
this.request<PaginatedResponse<OrderGroup>>('GET', '/order_groups', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[]; fields?: string[] },
options?: RequestOptions,
): Promise<OrderGroup> =>
this.request<OrderGroup>('GET', `/order_groups/${id}`, {
...options,
params: getParams(params),
}),
}
// ============================================
// Seller fund ledger
// ============================================
/**
* Read-only view of `Spree::SellerTransfer` — what one order earned one
* seller, credited when the goods went out. There is no write path: a
* refund writes a reversal, which is another row rather than an edit.
*/
readonly sellerTransfers = {
list: (
params?: ListParams<SellerTransferFilters, SellerTransferSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<SellerTransfer>> =>
this.request<PaginatedResponse<SellerTransfer>>('GET', '/seller_transfers', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<SellerTransfer> =>
this.request<SellerTransfer>('GET', `/seller_transfers/${id}`, {
...options,
params: getParams(params),
}),
}
/**
* `Spree::SellerPayout` — one settlement to one seller. Created by the
* sweep on that seller's own schedule rather than by a caller, so there is
* no create or update. `complete` is what the built-in provider waits for:
* the operator saying the bank transfer went out.
*/
readonly sellerPayouts = {
list: (
params?: ListParams<SellerPayoutFilters, SellerPayoutSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<SellerPayout>> =>
this.request<PaginatedResponse<SellerPayout>>('GET', '/seller_payouts', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<SellerPayout> =>
this.request<SellerPayout>('GET', `/seller_payouts/${id}`, {
...options,
params: getParams(params),
}),
complete: (
id: string,
data?: SellerPayoutCompleteParams,
options?: RequestOptions,
): Promise<SellerPayout> =>
this.request<SellerPayout>('PATCH', `/seller_payouts/${id}/complete`, {
...options,
body: data,
}),
}
// ============================================
// 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<GiftCardFilters, GiftCardSort>,
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),
}
// ============================================
// Store credits, across all customers
// ============================================
/**
* Read-only view of what the store owes in prepaid balances. Issuing,
* editing and deleting a credit stays nested under the customer that holds
* it (`client.customers.storeCredits`).
*
* The list's `meta.totals` carries the outstanding balance as one row per
* currency, summed over the same filter the page used — so filtering by a
* customer answers that customer's balance and no filter answers the
* store's liability.
*/
readonly storeCredits = {
list: (
params?: ListParams<StoreCreditFilters, StoreCreditSort>,
options?: RequestOptions,
): Promise<StoreCreditListResponse> =>
this.request<StoreCreditListResponse>('GET', '/store_credits', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<StoreCredit> =>
this.request<StoreCredit>('GET', `/store_credits/${id}`, {
...options,
params: getParams(params),
}),
/** The credit's ledger — how its balance got to where it is. */
events: {
list: (
storeCreditId: string,
params?: ListParams<StoreCreditEventFilters, StoreCreditEventSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<StoreCreditEvent>> =>
this.request<PaginatedResponse<StoreCreditEvent>>(
'GET',
`/store_credits/${storeCreditId}/events`,
{
...options,
params: params ? transformListParams(params) : undefined,
},
),
},
}
// ============================================
// Post-sale, across all orders (read-only — creating any of these needs an
// order, so writes live on client.orders.{returns,exchanges,claims})
// ============================================
readonly returns = {
list: (
params?: ListParams<ReturnFilters, ReturnSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Return>> =>
this.request<PaginatedResponse<Return>>('GET', '/returns', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Return> =>
this.request<Return>('GET', `/returns/${id}`, {
...options,
params: getParams(params),
}),
}
readonly exchanges = {
list: (
params?: ListParams<ExchangeFilters, ExchangeSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Exchange>> =>
this.request<PaginatedResponse<Exchange>>('GET', '/exchanges', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<Exchange> =>
this.request<Exchange>('GET', `/exchanges/${id}`, {
...options,
params: getParams(params),
}),
}
readonly claims = {
list: (
params?: ListParams<ClaimFilters, ClaimSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Claim>> =>
this.request<PaginatedResponse<Claim>>('GET', '/claims', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Claim> =>
this.request<Claim>('GET', `/claims/${id}`, {
...options,
params: getParams(params),
}),
}
// ============================================
// 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<GiftCardBatchFilters, GiftCardBatchSort>,
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 }),
}
// ============================================
// 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<TaxRateFilters, TaxRateSort>,
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: TaxRateCreateParams, options?: RequestOptions): Promise<TaxRate> =>
this.request<TaxRate>('POST', '/tax_rates', { ...options, body: params }),
update: (id: string, params: TaxRateUpdateParams, 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<TaxProviderOption>> =>
this.request<PaginatedResponse<TaxProviderOption>>('GET', '/tax_providers', options),
}
/**
* How this installation can pay its sellers. Discovery only — which one a
* store uses is a store preference, so there is nothing here to create.
*
* Each says whether it is usable by this store today, and whether it needs
* sellers to hold an account with it: choosing one changes what the
* marketplace has to ask of its sellers before it can pay them.
*/
readonly payoutProviders = {
list: (options?: RequestOptions): Promise<PaginatedResponse<StorePayoutProvider>> =>
this.request<PaginatedResponse<StorePayoutProvider>>('GET', '/payout_providers', options),
}
// ============================================
// Companies (business customers)
// ============================================
/**
* Business customers as an organization tree: self-referential company
* nodes (`kind: 'company' | 'division'`), each with an address book and
* members whose standing covers the node's subtree. A legal-entity node
* holds the tax registration that goes on its invoices and the exemption
* certificates that decide whether its purchases are taxed; a division
* reads both through its nearest legal-entity ancestor.
*
* List roots with `{ parent_id_null: 1 }` and a node's children with
* `{ parent_id_eq: 'comp_…' }`. Deleting a node destroys its subtree.
*
* Address-book entries, memberships and invitations all belong to a node,
* so every one of them is reached through it.
*/
readonly companies = {
list: (
params?: ListParams<CompanyFilters, CompanySort>,
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: CompanyCreateParams, options?: RequestOptions): Promise<Company> =>
this.request<Company>('POST', '/companies', { ...options, body: params }),
/** Re-parenting is an ordinary update — depth, cycle and store revalidate. */
update: (id: string, params: CompanyUpdateParams, options?: RequestOptions): Promise<Company> =>
this.request<Company>('PATCH', `/companies/${id}`, { ...options, body: params }),
/** Destroys the node and its whole subtree. */
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/companies/${id}`, options),
addresses: {
list: (
companyId: string,
params?: ListParams<AddressFilters, AddressSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Address>> =>
this.request<PaginatedResponse<Address>>('GET', `/companies/${companyId}/addresses`, {
...options,
params: params ? transformListParams(params) : undefined,
}),
create: (
companyId: string,
params: CompanyAddressCreateParams,
options?: RequestOptions,
): Promise<Address> =>
this.request<Address>('POST', `/companies/${companyId}/addresses`, {
...options,
body: params,
}),
get: (companyId: string, id: string, options?: RequestOptions): Promise<Address> =>
this.request<Address>('GET', `/companies/${companyId}/addresses/${id}`, options),
/** Address fields edit the entry in place, so send only what changes. */
update: (
companyId: string,
id: string,
params: CompanyAddressUpdateParams,
options?: RequestOptions,
): Promise<Address> =>
this.request<Address>('PATCH', `/companies/${companyId}/addresses/${id}`, {
...options,
body: params,
}),
delete: (companyId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/companies/${companyId}/addresses/${id}`, options),
},
/**
* The people with standing over the node (and, through it, its subtree).
* `create` takes an email and does the right thing: a membership for an
* existing customer, a CompanyInvitation otherwise — check the returned
* id prefix (`cmem_` vs `cinv_`).
*/
memberships: {
list: (
companyId: string,
params?: ListParams<CompanyMembershipFilters, CompanyMembershipSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<CompanyMembership>> =>
this.request<PaginatedResponse<CompanyMembership>>(
'GET',
`/companies/${companyId}/memberships`,
{ ...options, params: params ? transformListParams(params) : undefined },
),
create: (
companyId: string,
params: CompanyMembershipCreateParams,
options?: RequestOptions,
): Promise<CompanyMembership | CompanyInvitation> =>
this.request<CompanyMembership | CompanyInvitation>(
'POST',
`/companies/${companyId}/memberships`,
{ ...options, body: params },
),
get: (companyId: string, id: string, options?: RequestOptions): Promise<CompanyMembership> =>
this.request<CompanyMembership>(
'GET',
`/companies/${companyId}/memberships/${id}`,
options,
),
/** Withdraws the member's standing. The customer account is untouched. */
delete: (companyId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/companies/${companyId}/memberships/${id}`, options),
},
invitations: {
list: (
companyId: string,
params?: ListParams<CompanyInvitationFilters, CompanyInvitationSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<CompanyInvitation>> =>
this.request<PaginatedResponse<CompanyInvitation>>(
'GET',
`/companies/${companyId}/invitations`,
{ ...options, params: params ? transformListParams(params) : undefined },
),
get: (companyId: string, id: string, options?: RequestOptions): Promise<CompanyInvitation> =>
this.request<CompanyInvitation>(
'GET',
`/companies/${companyId}/invitations/${id}`,
options,
),
/** Revokes a pending invitation; its token then stops resolving. */
delete: (companyId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/companies/${companyId}/invitations/${id}`, options),
},
/**
* 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<TaxIdentifierFilters, TaxIdentifierSort>,
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: TaxIdentifierCreateParams,
options?: RequestOptions,
): Promise<TaxIdentifier> =>
this.request<TaxIdentifier>('POST', `/companies/${companyId}/tax_identifiers`, {
...options,
body: params,
}),
update: (
companyId: string,
id: string,
params: TaxIdentifierUpdateParams,
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 `files.upload()` first and pass the
* returned `signed_id` as `document_signed_id`. 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<TaxExemptionCertificateFilters, TaxExemptionCertificateSort>,
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: TaxExemptionCertificateCreateParams,
options?: RequestOptions,
): Promise<TaxExemptionCertificate> =>
this.request<TaxExemptionCertificate>(
'POST',
`/companies/${companyId}/tax_exemption_certificates`,
{ ...options, body: params },
),
update: (
companyId: string,
id: string,
params: TaxExemptionCertificateUpdateParams,
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,
),
},
}
// ============================================
// Catalogs (assortment + optional price list)
// ============================================
/**
* Catalogs narrow what an audience sees and, through an attached price
* list, what they pay. Audiences are assignments: a channel, a customer
* group, a market, or a company node (covering its subtree).
*/
readonly catalogs = {
list: (
params?: ListParams<CatalogFilters, CatalogSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Catalog>> =>
this.request<PaginatedResponse<Catalog>>('GET', '/catalogs', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Catalog> =>
this.request<Catalog>('GET', `/catalogs/${id}`, { ...options, params: getParams(params) }),
create: (params: CatalogCreateParams, options?: RequestOptions): Promise<Catalog> =>
this.request<Catalog>('POST', '/catalogs', { ...options, body: params }),
update: (id: string, params: CatalogUpdateParams, options?: RequestOptions): Promise<Catalog> =>
this.request<Catalog>('PATCH', `/catalogs/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/catalogs/${id}`, options),
/**
* The catalog's assortment. Rows carry `catalog_price` when asked for
* with `expand: ['catalog_price']` — what a buyer on this agreement pays
* and where the amount comes from.
*/
products: this.productMembership<CatalogProduct>('/catalogs'),
/**
* Puts the agreement into effect: its audience starts seeing its
* assortment and paying its prices. Refused for a catalog nobody is
* assigned to, which would reach no buyer.
*/
activate: (id: string, options?: RequestOptions): Promise<Catalog> =>
this.request<Catalog>('PATCH', `/catalogs/${id}/activate`, options),
/** Takes it out of effect; everything it holds survives untouched. */
deactivate: (id: string, options?: RequestOptions): Promise<Catalog> =>
this.request<Catalog>('PATCH', `/catalogs/${id}/deactivate`, options),
/**
* Copies the attached price list's products into the assortment.
* Explicit by design — an empty assortment is a pricing-only overlay
* (nothing hidden), so making a catalog restrictive is deliberate.
*/
importProducts: (id: string, options?: RequestOptions): Promise<{ added_count: number }> =>
this.request<{ added_count: number }>('POST', `/catalogs/${id}/import_products`, options),
/** Shows the catalog to an audience. */
assign: (
id: string,
params: CatalogAssignParams,
options?: RequestOptions,
): Promise<CatalogAssignment> =>
this.request<CatalogAssignment>('POST', `/catalogs/${id}/assign`, {
...options,
body: params,
}),
/**
* A catalog's quantity terms. The catalog-wide default is a pair of
* fields on the catalog itself, so this is strictly the overrides.
*
* Written as a whole set at the grain a merchant states them at (per
* product, over rows the database keeps per variant). Read them back on
* the assortment rows instead: `catalogs.products.list(id, { expand:
* ['quantity_rule'] })`.
*/
quantityRules: {
/**
* Writes the whole set in one request. A product whose pair is both
* null has its terms cleared; a product not yet in the assortment is
* added, since a term with nothing to apply to is not a reachable
* state.
*/
upsert: (
catalogId: string,
params: CatalogProductTermsParams,
options?: RequestOptions,
): Promise<void> =>
this.request<void>('PUT', `/catalogs/${catalogId}/quantity_rules`, {
...options,
body: params,
}),
},
/** The order minimum in each currency this agreement states one for. */
orderMinimums: {
list: (
catalogId: string,
params?: ListParams<CatalogOrderMinimumFilters, CatalogOrderMinimumSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<CatalogOrderMinimum>> =>
this.request<PaginatedResponse<CatalogOrderMinimum>>(
'GET',
`/catalogs/${catalogId}/order_minimums`,
{ ...options, params: params ? transformListParams(params) : undefined },
),
create: (
catalogId: string,
params: CatalogOrderMinimumParams,
options?: RequestOptions,
): Promise<CatalogOrderMinimum> =>
this.request<CatalogOrderMinimum>('POST', `/catalogs/${catalogId}/order_minimums`, {
...options,
body: params,
}),
update: (
catalogId: string,
id: string,
params: CatalogOrderMinimumParams,
options?: RequestOptions,
): Promise<CatalogOrderMinimum> =>
this.request<CatalogOrderMinimum>('PATCH', `/catalogs/${catalogId}/order_minimums/${id}`, {
...options,
body: params,
}),
delete: (catalogId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/catalogs/${catalogId}/order_minimums/${id}`, options),
},
}
readonly catalogAssignments = {
/** Withdraws the catalog from an audience. */
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/catalog_assignments/${id}`, options),
}
// ============================================
// Exports (CSV: products, orders, customers, …)
// ============================================
/**
* Queues asynchronous CSV exports and reports their progress. After
* `create()`, poll `get(id)` until `done === true`, then fetch
* `download_url` (with `Authorization: Bearer …`) and drive the browser
* download via a Blob — top-level navigation cannot carry an in-memory
* JWT, so `window.location.href = download_url` does not work.
*/
readonly exports = {
list: (
params?: ListParams<ExportFilters, ExportSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Export>> =>
this.request<PaginatedResponse<Export>>('GET', '/exports', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, options?: RequestOptions): Promise<Export> =>
this.request<Export>('GET', `/exports/${id}`, options),
create: (params: ExportCreateParams, options?: RequestOptions): Promise<Export> =>
this.request<Export>('POST', '/exports', { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/exports/${id}`, options),
}
// ============================================
// Maintenance tasks
// ============================================
/**
* The upgrade manifest as an ordered checklist: what this release still
* needs run, the operator notes each step carries, and how each last went.
*
* Read-only — running a step is starting the task it names through
* `maintenanceTaskRuns.create()` with the step's own `task_name` and
* `arguments`.
*/
readonly upgradeSteps = {
list: (options?: RequestOptions): Promise<{ data: UpgradeStep[]; meta: UpgradeStepsMeta }> =>
this.request<{ data: UpgradeStep[]; meta: UpgradeStepsMeta }>(
'GET',
'/upgrade_steps',
options,
),
}
/**
* Runs of a maintenance task — the progress to poll while one is working and
* the audit trail afterwards (who ran what, with which arguments, and how it
* ended).
*
* After `create()`, poll `get(id)` while `active` is true; show `tick_count`
* against `tick_total`, or `tick_count` alone when the task could not count
* its collection. `cancel` stops an active run for good. There is no delete:
* a run records work that touched merchant data.
*/
readonly maintenanceTaskRuns = {
list: (
params?: ListParams & Record<string, unknown>,
options?: RequestOptions,
): Promise<PaginatedResponse<MaintenanceTaskRun>> =>
this.request<PaginatedResponse<MaintenanceTaskRun>>('GET', '/maintenance_task_runs', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<MaintenanceTaskRun> =>
this.request<MaintenanceTaskRun>('GET', `/maintenance_task_runs/${id}`, {
...options,
params: getParams(params),
}),
create: (
params: MaintenanceTaskRunCreateParams,
options?: RequestOptions,
): Promise<MaintenanceTaskRun> =>
this.request<MaintenanceTaskRun>('POST', '/maintenance_task_runs', {
...options,
body: params,
}),
cancel: (id: string, options?: RequestOptions): Promise<MaintenanceTaskRun> =>
this.request<MaintenanceTaskRun>(
'POST',
`/maintenance_task_runs/${id}/cancellation`,
options,
),
}
// ============================================
// Imports (CSV: products, customers, …)
// ============================================
/**
* Queues asynchronous CSV imports and drives the mapping flow. Upload the
* file via `files.upload()` first, then `create()` the import with
* the returned `signed_id` as `attachment_signed_id` — the response is in the `mapping` state and
* carries `schema_fields`, `csv_headers`, a `sample_row` and the
* auto-assigned `mappings`. Adjust mappings if needed and call
* `completeMapping(id)` to start processing, then poll `get(id)` while
* `status` is `completed_mapping`/`processing` (`completed`/`failed` are
* terminal). Failed rows are listed via `rows.list(id, { status_eq:
* 'failed' })` (flat Ransack predicates, wrapped into `q[...]` by
* `transformListParams`) and can be re-processed with `retryFailedRows(id)`.
*/
readonly imports = {
list: (
params?: ListParams<ImportFilters, ImportSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Import>> =>
this.request<PaginatedResponse<Import>>('GET', '/imports', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, options?: RequestOptions): Promise<Import> =>
this.request<Import>('GET', `/imports/${id}`, options),
create: (params: ImportCreateParams, options?: RequestOptions): Promise<Import> =>
this.request<Import>('POST', '/imports', { ...options, body: params }),
completeMapping: (
id: string,
params?: ImportCompleteMappingParams,
options?: RequestOptions,
): Promise<Import> =>
this.request<Import>('PATCH', `/imports/${id}/complete_mapping`, {
...options,
body: params ?? {},
}),
retryFailedRows: (id: string, options?: RequestOptions): Promise<Import> =>
this.request<Import>('PATCH', `/imports/${id}/retry_failed_rows`, options),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/imports/${id}`, options),
rows: {
list: (
importId: string,
params?: ListParams<ImportRowFilters, ImportRowSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<ImportRow>> =>
this.request<PaginatedResponse<ImportRow>>('GET', `/imports/${importId}/rows`, {
...options,
params: params ? transformListParams(params) : undefined,
}),
},
}
// ============================================
// Customers
// ============================================
readonly customers = {
list: (
params?: ListParams<CustomerFilters, CustomerSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Customer>> =>
this.request<PaginatedResponse<Customer>>('GET', '/customers', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<Customer> =>
this.request<Customer>('GET', `/customers/${id}`, {
...options,
params: getParams(params),
}),
creditCards: {
list: (
customerId: string,
params?: ListParams<CreditCardFilters, CreditCardSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<CreditCard>> =>
this.request<PaginatedResponse<CreditCard>>(
'GET',
`/customers/${customerId}/credit_cards`,
{
...options,
params: params ? transformListParams(params) : undefined,
},
),
get: (
customerId: string,
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<CreditCard> =>
this.request<CreditCard>('GET', `/customers/${customerId}/credit_cards/${id}`, {
...options,
params: getParams(params),
}),
delete: (customerId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/customers/${customerId}/credit_cards/${id}`, options),
},
create: (params: CustomerCreateParams, options?: RequestOptions): Promise<Customer> =>
this.request<Customer>('POST', '/customers', { ...options, body: params }),
update: (
id: string,
params: CustomerUpdateParams,
options?: RequestOptions,
): Promise<Customer> =>
this.request<Customer>('PATCH', `/customers/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/customers/${id}`, options),
/**
* Everything the store holds about this customer, for answering a GDPR
* subject access request that arrived by email.
*/
export: (id: string, options?: RequestOptions): Promise<Record<string, unknown>> =>
this.request<Record<string, unknown>>('GET', `/customers/${id}/export`, options),
/**
* Erases the customer's personal data, keeping the financial record.
* Irreversible.
*/
anonymize: (id: string, options?: RequestOptions): Promise<Customer> =>
this.request<Customer>('POST', `/customers/${id}/anonymize`, options),
/**
* Bulk-attach a set of customers to a set of groups. Both arrays carry
* prefixed IDs; the server decodes them. Idempotent.
*/
bulkAddToGroups: (
params: CustomerBulkGroupsParams,
options?: RequestOptions,
): Promise<{ customer_count: number; customer_group_count: number }> =>
this.request('POST', '/customers/bulk_add_to_groups', { ...options, body: params }),
/**
* Bulk-detach a set of customers from a set of groups. No-op for
* non-members. Same shape as `bulkAddToGroups`.
*/
bulkRemoveFromGroups: (
params: CustomerBulkGroupsParams,
options?: RequestOptions,
): Promise<{ customer_count: number; customer_group_count: number }> =>
this.request('POST', '/customers/bulk_remove_from_groups', { ...options, body: params }),
/** Add each tag name to every customer. Tags are upserted by name. */
bulkAddTags: (
params: BulkTagsParams,
options?: RequestOptions,
): Promise<{ customer_count: number; tag_count: number }> =>
this.request('POST', '/customers/bulk_add_tags', { ...options, body: params }),
/** Remove each tag name from every customer. No-op for non-tagged. */
bulkRemoveTags: (
params: BulkTagsParams,
options?: RequestOptions,
): Promise<{ customer_count: number; tag_count: number }> =>
this.request('POST', '/customers/bulk_remove_tags', { ...options, body: params }),
addresses: {
list: (
customerId: string,
params?: ListParams<AddressFilters, AddressSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Address>> =>
this.request<PaginatedResponse<Address>>('GET', `/customers/${customerId}/addresses`, {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
customerId: string,
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<Address> =>
this.request<Address>('GET', `/customers/${customerId}/addresses/${id}`, {
...options,
params: getParams(params),
}),
create: (
customerId: string,
params: CustomerAddressCreateParams,
options?: RequestOptions,
): Promise<Address> =>
this.request<Address>('POST', `/customers/${customerId}/addresses`, {
...options,
body: params,
}),
update: (
customerId: string,
id: string,
params: CustomerAddressUpdateParams,
options?: RequestOptions,
): Promise<Address> =>
this.request<Address>('PATCH', `/customers/${customerId}/addresses/${id}`, {
...options,
body: params,
}),
delete: (customerId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/customers/${customerId}/addresses/${id}`, options),
},
/**
* The customer's own tax registrations — the durable profile value, as
* opposed to the override entered during a single checkout. A company's
* registration outranks these when the buyer purchases for a business.
*/
taxIdentifiers: {
list: (
customerId: string,
params?: ListParams<TaxIdentifierFilters, TaxIdentifierSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<TaxIdentifier>> =>
this.request<PaginatedResponse<TaxIdentifier>>(
'GET',
`/customers/${customerId}/tax_identifiers`,
{ ...options, params: params ? transformListParams(params) : undefined },
),
get: (customerId: string, id: string, options?: RequestOptions): Promise<TaxIdentifier> =>
this.request<TaxIdentifier>(
'GET',
`/customers/${customerId}/tax_identifiers/${id}`,
options,
),
create: (
customerId: string,
params: TaxIdentifierCreateParams,
options?: RequestOptions,
): Promise<TaxIdentifier> =>
this.request<TaxIdentifier>('POST', `/customers/${customerId}/tax_identifiers`, {
...options,
body: params,
}),
update: (
customerId: string,
id: string,
params: TaxIdentifierUpdateParams,
options?: RequestOptions,
): Promise<TaxIdentifier> =>
this.request<TaxIdentifier>('PATCH', `/customers/${customerId}/tax_identifiers/${id}`, {
...options,
body: params,
}),
delete: (customerId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/customers/${customerId}/tax_identifiers/${id}`, options),
/**
* Re-asks the registry. Manual because a registry answers only "valid
* now" — a number verified last year may have been deregistered since.
*/
validate: (
customerId: string,
id: string,
options?: RequestOptions,
): Promise<TaxIdentifier> =>
this.request<TaxIdentifier>(
'POST',
`/customers/${customerId}/tax_identifiers/${id}/validate`,
options,
),
},
storeCredits: {
list: (
customerId: string,
params?: ListParams<StoreCreditFilters, StoreCreditSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<StoreCredit>> =>
this.request<PaginatedResponse<StoreCredit>>(
'GET',
`/customers/${customerId}/store_credits`,
{
...options,
params: params ? transformListParams(params) : undefined,
},
),
get: (
customerId: string,
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<StoreCredit> =>
this.request<StoreCredit>('GET', `/customers/${customerId}/store_credits/${id}`, {
...options,
params: getParams(params),
}),
create: (
customerId: string,
params: CustomerStoreCreditCreateParams,
options?: RequestOptions,
): Promise<StoreCredit> =>
this.request<StoreCredit>('POST', `/customers/${customerId}/store_credits`, {
...options,
body: params,
}),
update: (
customerId: string,
id: string,
params: CustomerStoreCreditUpdateParams,
options?: RequestOptions,
): Promise<StoreCredit> =>
this.request<StoreCredit>('PATCH', `/customers/${customerId}/store_credits/${id}`, {
...options,
body: params,
}),
delete: (customerId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/customers/${customerId}/store_credits/${id}`, options),
},
customFields: this.parentScopedCustomFields(CUSTOM_FIELD_OWNER_PATHS.customer),
}
/** The consents customers gave or withdrew — evidence of what each one agreed to and when. */
readonly consentRecords = {
list: (
params?: ListParams<ConsentRecordFilters, ConsentRecordSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<ConsentRecord>> =>
this.request<PaginatedResponse<ConsentRecord>>('GET', '/consent_records', {
...options,
params: params ? transformListParams(params) : undefined,
}),
}
/** Requests customers made to export (`access`) or erase (`erasure`) their personal data. */
readonly dataRequests = {
list: (
params?: ListParams<DataRequestFilters, DataRequestSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<DataRequest>> =>
this.request<PaginatedResponse<DataRequest>>('GET', '/data_requests', {
...options,
params: params ? transformListParams(params) : undefined,
}),
/**
* Records a request the customer made to the merchant directly and starts
* answering it. A request of the same kind already in progress is returned
* instead of a second one.
*/
create: (params: DataRequestCreateParams, options?: RequestOptions): Promise<DataRequest> =>
this.request<DataRequest>('POST', '/data_requests', { ...options, body: params }),
}
// ============================================
// Categories
// ============================================
/**
* The media library — every file in the store, whether or not it has been
* placed on a product. Files are put ON a product through
* `products.media.create` with a `source_media_id`; this is where they are
* uploaded, browsed and deleted.
*/
readonly media = {
list: (
params?: ListParams<MediaFilters, MediaSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Media>> =>
this.request<PaginatedResponse<Media>>('GET', '/media', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, options?: RequestOptions): Promise<Media> =>
this.request<Media>('GET', `/media/${id}`, options),
/** Upload a file before deciding where it goes. */
create: (params: MediaLibraryCreateParams, options?: RequestOptions): Promise<Media> =>
this.request<Media>('POST', '/media', { ...options, body: params }),
update: (
id: string,
params: MediaLibraryUpdateParams,
options?: RequestOptions,
): Promise<Media> => this.request<Media>('PATCH', `/media/${id}`, { ...options, body: params }),
/**
* Deletes the file. A file still in use is refused (422 with its usage)
* unless `detach` is set, which removes it from every place using it —
* product galleries, category and collection images — in one pass.
* Descriptions embedding it keep a URL that no longer resolves.
*/
delete: (id: string, params?: { detach?: boolean }, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/media/${id}`, {
...options,
params: params?.detach ? { detach: 'true' } : undefined,
}),
/**
* Where this file is in use. Worth showing before a delete: reuse shares
* the file, so removing one placement can leave others pointing at it.
*/
usage: (id: string, options?: RequestOptions): Promise<{ data: MediaUsageReference[] }> =>
this.request<{ data: MediaUsageReference[] }>('GET', `/media/${id}/usage`, options),
}
readonly categories = {
list: (
params?: ListParams<CategoryFilters, CategorySort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Category>> =>
this.request<PaginatedResponse<Category>>('GET', '/categories', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<Category> =>
this.request<Category>('GET', `/categories/${id}`, {
...options,
params: getParams(params),
}),
create: (params: CategoryCreateParams, options?: RequestOptions): Promise<Category> =>
this.request<Category>('POST', '/categories', { ...options, body: params }),
update: (
id: string,
params: CategoryUpdateParams,
options?: RequestOptions,
): Promise<Category> =>
this.request<Category>('PATCH', `/categories/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/categories/${id}`, options),
/** Move a category to a new parent and/or index within the tree. */
reposition: (
id: string,
params: CategoryRepositionParams,
options?: RequestOptions,
): Promise<Category> =>
this.request<Category>('PATCH', `/categories/${id}/reposition`, { ...options, body: params }),
/** Manual product membership + ordering within a category. */
products: this.positionedProductMembership('/categories'),
customFields: this.parentScopedCustomFields(CUSTOM_FIELD_OWNER_PATHS.category),
translations: this.parentScopedTranslations('/categories'),
}
// ============================================
// Collections
// ============================================
readonly collections = {
list: (
params?: ListParams<CollectionFilters, CollectionSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Collection>> =>
this.request<PaginatedResponse<Collection>>('GET', '/collections', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<Collection> =>
this.request<Collection>('GET', `/collections/${id}`, {
...options,
params: getParams(params),
}),
create: (params: CollectionCreateParams, options?: RequestOptions): Promise<Collection> =>
this.request<Collection>('POST', '/collections', { ...options, body: params }),
/**
* Collections are a flat list, so reordering one is a plain `position`
* update — `acts_as_list` shifts its siblings on save and there is no
* separate reposition action.
*/
update: (
id: string,
params: CollectionUpdateParams,
options?: RequestOptions,
): Promise<Collection> =>
this.request<Collection>('PATCH', `/collections/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/collections/${id}`, options),
/**
* Manual product membership + ordering within a collection. `add`, `remove`
* and `reposition` are rejected on an automatic collection, whose members
* are materialized from its rules; `list` works on both.
*/
products: this.positionedProductMembership('/collections'),
customFields: this.parentScopedCustomFields(CUSTOM_FIELD_OWNER_PATHS.collection),
translations: this.parentScopedTranslations('/collections'),
}
/**
* Collection rule kinds. Read-only discovery — rules themselves are written
* through the owning collection's `rules` array on update. The list is
* registry-driven server-side, so plugin-registered rules appear here too.
*/
readonly collectionRules = {
types: (options?: RequestOptions): Promise<{ data: ResourceTypeDefinition[] }> =>
this.request<{ data: ResourceTypeDefinition[] }>('GET', '/collection_rules/types', options),
}
// ============================================
// Variants (top-level, for search/autocomplete)
// ============================================
readonly variants = {
list: (
params?: ListParams<VariantFilters, VariantSort> & VariantSalesContextParams,
options?: RequestOptions,
): Promise<PaginatedResponse<Variant>> =>
this.request<PaginatedResponse<Variant>>('GET', '/variants', {
...options,
params: params ? variantListQuery(params) : undefined,
}),
get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Variant> =>
this.request<Variant>('GET', `/variants/${id}`, {
...options,
params: getParams(params),
}),
customFields: this.parentScopedCustomFields(CUSTOM_FIELD_OWNER_PATHS.variant),
}
// ============================================
// Tax Categories
// ============================================
readonly productTypes = {
list: (
params?: ListParams<ProductTypeFilters, ProductTypeSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<ProductType>> =>
this.request<PaginatedResponse<ProductType>>('GET', '/product_types', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, options?: RequestOptions): Promise<ProductType> =>
this.request<ProductType>('GET', `/product_types/${id}`, options),
create: (params: ProductTypeCreateParams, options?: RequestOptions): Promise<ProductType> =>
this.request<ProductType>('POST', '/product_types', { ...options, body: params }),
update: (
id: string,
params: ProductTypeUpdateParams,
options?: RequestOptions,
): Promise<ProductType> =>
this.request<ProductType>('PATCH', `/product_types/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/product_types/${id}`, options),
/**
* Backfills the type's option types and categories onto the products that
* already carry it. Additive — nothing is removed. Runs in the background;
* the response reports how many products are affected.
*/
applyToProducts: (
id: string,
options?: RequestOptions,
): Promise<ProductTypeApplyToProductsResponse> =>
this.request<ProductTypeApplyToProductsResponse>(
'POST',
`/product_types/${id}/apply_to_products`,
options,
),
}
readonly taxCategories = {
list: (
params?: ListParams<TaxCategoryFilters, TaxCategorySort>,
options?: RequestOptions,
): Promise<PaginatedResponse<TaxCategory>> =>
this.request<PaginatedResponse<TaxCategory>>('GET', '/tax_categories', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<TaxCategory> =>
this.request<TaxCategory>('GET', `/tax_categories/${id}`, {
...options,
params: getParams(params),
}),
create: (params: TaxCategoryCreateParams, options?: RequestOptions): Promise<TaxCategory> =>
this.request<TaxCategory>('POST', '/tax_categories', { ...options, body: params }),
update: (
id: string,
params: TaxCategoryUpdateParams,
options?: RequestOptions,
): Promise<TaxCategory> =>
this.request<TaxCategory>('PATCH', `/tax_categories/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/tax_categories/${id}`, options),
}
// ============================================
// Policies — the store's legal documents
// ============================================
/**
* The store's own policy documents: terms of service, privacy, returns,
* shipping, and anything else the merchant publishes.
*
* Addressable by slug as well as prefixed id. A marketplace seller's
* policies are theirs and live on the seller API, not here.
*/
readonly policies = {
list: (
params?: ListParams<PolicyFilters, PolicySort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Policy>> =>
this.request<PaginatedResponse<Policy>>('GET', '/policies', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (idOrSlug: string, options?: RequestOptions): Promise<Policy> =>
this.request<Policy>('GET', `/policies/${idOrSlug}`, options),
create: (params: PolicyCreateParams, options?: RequestOptions): Promise<Policy> =>
this.request<Policy>('POST', '/policies', { ...options, body: params }),
update: (
idOrSlug: string,
params: PolicyUpdateParams,
options?: RequestOptions,
): Promise<Policy> =>
this.request<Policy>('PATCH', `/policies/${idOrSlug}`, { ...options, body: params }),
delete: (idOrSlug: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/policies/${idOrSlug}`, options),
}
// ============================================
// Reasons — why a return, claim or refund happened
// ============================================
/** Why a customer sent something back. Shared by returns and exchanges. */
readonly returnReasons = {
list: (
params?: ListParams<ReturnReasonFilters, ReturnReasonSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<ReturnReason>> =>
this.request<PaginatedResponse<ReturnReason>>('GET', '/return_reasons', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, options?: RequestOptions): Promise<ReturnReason> =>
this.request<ReturnReason>('GET', `/return_reasons/${id}`, options),
create: (params: ReasonCreateParams, options?: RequestOptions): Promise<ReturnReason> =>
this.request<ReturnReason>('POST', '/return_reasons', { ...options, body: params }),
update: (
id: string,
params: ReasonUpdateParams,
options?: RequestOptions,
): Promise<ReturnReason> =>
this.request<ReturnReason>('PATCH', `/return_reasons/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/return_reasons/${id}`, options),
}
/** What went wrong with a delivery — damaged, missing, wrong item. */
readonly claimReasons = {
list: (
params?: ListParams<ClaimReasonFilters, ClaimReasonSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<ClaimReason>> =>
this.request<PaginatedResponse<ClaimReason>>('GET', '/claim_reasons', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, options?: RequestOptions): Promise<ClaimReason> =>
this.request<ClaimReason>('GET', `/claim_reasons/${id}`, options),
create: (params: ReasonCreateParams, options?: RequestOptions): Promise<ClaimReason> =>
this.request<ClaimReason>('POST', '/claim_reasons', { ...options, body: params }),
update: (
id: string,
params: ReasonUpdateParams,
options?: RequestOptions,
): Promise<ClaimReason> =>
this.request<ClaimReason>('PATCH', `/claim_reasons/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/claim_reasons/${id}`, options),
}
/** Why an order was called off before it shipped. */
readonly orderCancellationReasons = {
list: (
params?: ListParams<OrderCancellationReasonFilters, OrderCancellationReasonSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<OrderCancellationReason>> =>
this.request<PaginatedResponse<OrderCancellationReason>>(
'GET',
'/order_cancellation_reasons',
{
...options,
params: params ? transformListParams(params) : undefined,
},
),
get: (id: string, options?: RequestOptions): Promise<OrderCancellationReason> =>
this.request<OrderCancellationReason>('GET', `/order_cancellation_reasons/${id}`, options),
create: (
params: ReasonCreateParams,
options?: RequestOptions,
): Promise<OrderCancellationReason> =>
this.request<OrderCancellationReason>('POST', '/order_cancellation_reasons', {
...options,
body: params,
}),
update: (
id: string,
params: ReasonUpdateParams,
options?: RequestOptions,
): Promise<OrderCancellationReason> =>
this.request<OrderCancellationReason>('PATCH', `/order_cancellation_reasons/${id}`, {
...options,
body: params,
}),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/order_cancellation_reasons/${id}`, options),
}
/**
* Why a business buys without tax — the reasons a merchant records on a tax
* exemption certificate. `code` is what the certificate stores and the tax
* engine receives; `taxProviders.list()` says which codes an engine reads.
*/
readonly taxExemptionReasons = {
list: (
params?: ListParams<TaxExemptionReasonFilters, TaxExemptionReasonSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<TaxExemptionReason>> =>
this.request<PaginatedResponse<TaxExemptionReason>>('GET', '/tax_exemption_reasons', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, options?: RequestOptions): Promise<TaxExemptionReason> =>
this.request<TaxExemptionReason>('GET', `/tax_exemption_reasons/${id}`, options),
create: (
params: TaxExemptionReasonCreateParams,
options?: RequestOptions,
): Promise<TaxExemptionReason> =>
this.request<TaxExemptionReason>('POST', '/tax_exemption_reasons', {
...options,
body: params,
}),
update: (
id: string,
params: TaxExemptionReasonUpdateParams,
options?: RequestOptions,
): Promise<TaxExemptionReason> =>
this.request<TaxExemptionReason>('PATCH', `/tax_exemption_reasons/${id}`, {
...options,
body: params,
}),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/tax_exemption_reasons/${id}`, options),
}
/**
* Why money went back. Some rows are seeded and immutable: core looks
* them up by name, so `can_be_deleted` is false and renaming is refused.
*/
readonly refundReasons = {
list: (
params?: ListParams<RefundReasonFilters, RefundReasonSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<RefundReason>> =>
this.request<PaginatedResponse<RefundReason>>('GET', '/refund_reasons', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, options?: RequestOptions): Promise<RefundReason> =>
this.request<RefundReason>('GET', `/refund_reasons/${id}`, options),
create: (params: ReasonCreateParams, options?: RequestOptions): Promise<RefundReason> =>
this.request<RefundReason>('POST', '/refund_reasons', { ...options, body: params }),
update: (
id: string,
params: ReasonUpdateParams,
options?: RequestOptions,
): Promise<RefundReason> =>
this.request<RefundReason>('PATCH', `/refund_reasons/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/refund_reasons/${id}`, options),
}
// ============================================
// Channels (per-store distribution surfaces — online, POS, wholesale)
// ============================================
readonly channels = {
list: (
params?: ListParams<ChannelFilters, ChannelSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Channel>> =>
this.request<PaginatedResponse<Channel>>('GET', '/channels', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Channel> =>
this.request<Channel>('GET', `/channels/${id}`, {
...options,
params: getParams(params),
}),
create: (params: ChannelCreateParams, options?: RequestOptions): Promise<Channel> =>
this.request<Channel>('POST', '/channels', { ...options, body: params }),
update: (id: string, params: ChannelUpdateParams, options?: RequestOptions): Promise<Channel> =>
this.request<Channel>('PATCH', `/channels/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/channels/${id}`, options),
/**
* Publishes the listed products on this channel. Idempotent — re-publishing
* an already-published product is a no-op for its existing publication
* window unless +published_at+ / +unpublished_at+ are explicitly passed.
* Cross-store onboarding is allowed: if the caller's API key has update
* permission on a product owned by a sibling store, that product is
* co-published onto this channel. Products the caller can't update are
* silently dropped.
*/
addProducts: (
id: string,
params: ChannelAddProductsParams,
options?: RequestOptions,
): Promise<{ product_count: number }> =>
this.request<{ product_count: number }>('POST', `/channels/${id}/add_products`, {
...options,
body: params,
}),
/** Unpublishes the listed products from this channel. */
removeProducts: (
id: string,
params: ChannelRemoveProductsParams,
options?: RequestOptions,
): Promise<{ product_count: number }> =>
this.request<{ product_count: number }>('POST', `/channels/${id}/remove_products`, {
...options,
body: params,
}),
/**
* Order routing rules — the channel's prioritized list of signals the
* `Rules` routing strategy walks when choosing fulfillment locations.
* Rule kinds are discovered via `client.orderRoutingRules.types()`.
*/
orderRoutingRules: {
list: (
channelId: string,
params?: ListParams<OrderRoutingRuleFilters, OrderRoutingRuleSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<OrderRoutingRule>> =>
this.request<PaginatedResponse<OrderRoutingRule>>(
'GET',
`/channels/${channelId}/order_routing_rules`,
{ ...options, params: params ? transformListParams(params) : undefined },
),
get: (channelId: string, id: string, options?: RequestOptions): Promise<OrderRoutingRule> =>
this.request<OrderRoutingRule>(
'GET',
`/channels/${channelId}/order_routing_rules/${id}`,
options,
),
create: (
channelId: string,
params: OrderRoutingRuleCreateParams,
options?: RequestOptions,
): Promise<OrderRoutingRule> =>
this.request<OrderRoutingRule>('POST', `/channels/${channelId}/order_routing_rules`, {
...options,
body: params,
}),
update: (
channelId: string,
id: string,
params: OrderRoutingRuleUpdateParams,
options?: RequestOptions,
): Promise<OrderRoutingRule> =>
this.request<OrderRoutingRule>(
'PATCH',
`/channels/${channelId}/order_routing_rules/${id}`,
{ ...options, body: params },
),
delete: (channelId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/channels/${channelId}/order_routing_rules/${id}`, options),
},
}
readonly orderRoutingRules = {
types: (options?: RequestOptions): Promise<{ data: ResourceTypeDefinition[] }> =>
this.request<{ data: ResourceTypeDefinition[] }>(
'GET',
'/order_routing_rules/types',
options,
),
}
/**
* Markets — store-scoped pricing regions. Each market binds one or more
* countries to a currency, a default locale, and a tax-display policy.
* Drives label resolution for `Spree::PriceRules::MarketRule` and is the
* unit that price lists target.
*/
readonly markets = {
list: (
params?: ListParams<MarketFilters, MarketSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Market>> =>
this.request<PaginatedResponse<Market>>('GET', '/markets', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Market> =>
this.request<Market>('GET', `/markets/${id}`, {
...options,
params: getParams(params),
}),
create: (params: MarketCreateParams, options?: RequestOptions): Promise<Market> =>
this.request<Market>('POST', '/markets', { ...options, body: params }),
update: (id: string, params: MarketUpdateParams, options?: RequestOptions): Promise<Market> =>
this.request<Market>('PATCH', `/markets/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/markets/${id}`, options),
}
// ============================================
// Stock Locations
// ============================================
readonly stockLocations = {
list: (
params?: ListParams<StockLocationFilters, StockLocationSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<StockLocation>> =>
this.request<PaginatedResponse<StockLocation>>('GET', '/stock_locations', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<StockLocation> =>
this.request<StockLocation>('GET', `/stock_locations/${id}`, {
...options,
params: getParams(params),
}),
create: (params: StockLocationCreateParams, options?: RequestOptions): Promise<StockLocation> =>
this.request<StockLocation>('POST', '/stock_locations', { ...options, body: params }),
update: (
id: string,
params: StockLocationUpdateParams,
options?: RequestOptions,
): Promise<StockLocation> =>
this.request<StockLocation>('PATCH', `/stock_locations/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/stock_locations/${id}`, options),
}
// ============================================
// Stock Levels
// ============================================
readonly stockLevels = {
list: (
params?: ListParams<StockLevelFilters, StockLevelSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<StockLevel>> =>
this.request<PaginatedResponse<StockLevel>>('GET', '/stock_levels', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<StockLevel> =>
this.request<StockLevel>('GET', `/stock_levels/${id}`, {
...options,
params: getParams(params),
}),
update: (
id: string,
params: StockLevelUpdateParams,
options?: RequestOptions,
): Promise<StockLevel> =>
this.request<StockLevel>('PATCH', `/stock_levels/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/stock_levels/${id}`, options),
/**
* Sets stock levels for many (variant, location) pairs at once — what a
* warehouse feed posts on a schedule. Rows name their variant and location
* either by Spree id or by an external reference, so a feed can use the
* keys it already holds.
*
* Each change is recorded as a stock movement, so the history stays
* intact. Response is `{ stock_level_count }`.
*/
bulkUpsert: (
params: StockLevelBulkUpsertParams,
options?: RequestOptions,
): Promise<{ stock_level_count: number }> =>
this.request('POST', '/stock_levels/bulk_upsert', { ...options, body: params }),
}
// ============================================
// Stock Movements
// ============================================
// Read-only: a movement records something that already happened to stock.
// Reversing one means writing its counterpart through the resource that
// caused it.
readonly stockMovements = {
list: (
params?: ListParams<StockMovementFilters, StockMovementSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<StockMovement>> =>
this.request<PaginatedResponse<StockMovement>>('GET', '/stock_movements', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<StockMovement> =>
this.request<StockMovement>('GET', `/stock_movements/${id}`, {
...options,
params: getParams(params),
}),
}
// ============================================
// Stock Reservations
// ============================================
/**
* Stock held for orders being checked out, so it cannot be sold twice
* before they complete or the hold expires. Read-only: holds are placed and
* released by checkout.
*/
readonly stockReservations = {
list: (
params?: ListParams<StockReservationFilters, StockReservationSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<StockReservation>> =>
this.request<PaginatedResponse<StockReservation>>('GET', '/stock_reservations', {
...options,
params: params ? transformListParams(params) : undefined,
}),
}
// ============================================
// Stock Transfers
// ============================================
/**
* Stock moving between two of the merchant's own warehouses. A transfer is a
* trip: `create` records a plan, `markInTransit` takes the units off the
* source shelf, and each delivery the destination counts in is a stock
* receipt (`stockReceipts.create`). Receiving from a supplier is a purchase
* order, not a transfer.
*/
readonly stockTransfers = {
list: (
params?: ListParams<StockTransferFilters, StockTransferSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<StockTransfer>> =>
this.request<PaginatedResponse<StockTransfer>>('GET', '/stock_transfers', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<StockTransfer> =>
this.request<StockTransfer>('GET', `/stock_transfers/${id}`, {
...options,
params: getParams(params),
}),
/** Persists a draft. Nothing moves until `markInTransit`. */
create: (params: StockTransferCreateParams, options?: RequestOptions): Promise<StockTransfer> =>
this.request<StockTransfer>('POST', '/stock_transfers', { ...options, body: params }),
/** Drafts only: past that, what is in the box is a matter of record. */
update: (
id: string,
params: StockTransferUpdateParams,
options?: RequestOptions,
): Promise<StockTransfer> =>
this.request<StockTransfer>('PATCH', `/stock_transfers/${id}`, { ...options, body: params }),
/** Drafts only: anything that has shipped is cancelled, not deleted. */
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/stock_transfers/${id}`, options),
/** Freezes the lines without taking anything off the shelf. */
markReady: (id: string, options?: RequestOptions): Promise<StockTransfer> =>
this.request<StockTransfer>('PATCH', `/stock_transfers/${id}/mark_ready`, options),
/**
* The van has left: writes the source's `shipped` movements. Pass
* `force` to ship anyway when the shelf cannot cover it.
*/
markInTransit: (
id: string,
params?: StockTransferMarkInTransitParams,
options?: RequestOptions,
): Promise<StockTransfer> =>
this.request<StockTransfer>('PATCH', `/stock_transfers/${id}/mark_in_transit`, {
...options,
body: params,
}),
/** Unfreezes a ready-to-ship transfer; nothing has left the source yet. */
markDraft: (id: string, options?: RequestOptions): Promise<StockTransfer> =>
this.request<StockTransfer>('PATCH', `/stock_transfers/${id}/mark_draft`, options),
/**
* Ends a partially received transfer whose missing units are not going to
* turn up. Nothing moves; the outstanding count stays on each line.
*/
close: (
id: string,
params?: ReceivableCloseParams,
options?: RequestOptions,
): Promise<StockTransfer> =>
this.request<StockTransfer>('PATCH', `/stock_transfers/${id}/close`, {
...options,
body: params,
}),
/**
* The deliveries the destination counted in. Creating one is how a
* transfer is received: this delivery's counts, accepted and refused,
* per line — a second box adds to the first.
*/
stockReceipts: {
list: (
stockTransferId: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<PaginatedResponse<StockReceipt>> =>
this.request<PaginatedResponse<StockReceipt>>(
'GET',
`/stock_transfers/${stockTransferId}/stock_receipts`,
{ ...options, params: getParams(params) },
),
get: (
stockTransferId: string,
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<StockReceipt> =>
this.request<StockReceipt>(
'GET',
`/stock_transfers/${stockTransferId}/stock_receipts/${id}`,
{ ...options, params: getParams(params) },
),
create: (
stockTransferId: string,
params?: StockReceiptCreateParams,
options?: RequestOptions,
): Promise<StockReceipt> =>
this.request<StockReceipt>('POST', `/stock_transfers/${stockTransferId}/stock_receipts`, {
...options,
body: params,
}),
},
cancel: (
id: string,
params?: StockTransferCancelParams,
options?: RequestOptions,
): Promise<StockTransfer> =>
this.request<StockTransfer>('PATCH', `/stock_transfers/${id}/cancel`, {
...options,
body: params,
}),
}
// ============================================
// Suppliers
// ============================================
/** The merchant's supplier address book. */
readonly suppliers = {
list: (
params?: ListParams<SupplierFilters, SupplierSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Supplier>> =>
this.request<PaginatedResponse<Supplier>>('GET', '/suppliers', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<Supplier> =>
this.request<Supplier>('GET', `/suppliers/${id}`, {
...options,
params: getParams(params),
}),
create: (params: SupplierCreateParams, options?: RequestOptions): Promise<Supplier> =>
this.request<Supplier>('POST', '/suppliers', { ...options, body: params }),
update: (
id: string,
params: SupplierUpdateParams,
options?: RequestOptions,
): Promise<Supplier> =>
this.request<Supplier>('PATCH', `/suppliers/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/suppliers/${id}`, options),
}
// ============================================
// Purchase Orders
// ============================================
/**
* Goods bought from a supplier. Ordered units never count toward
* availability: nothing reaches the shelf until a delivery is booked in as
* a stock receipt (`stockReceipts.create`).
*/
readonly purchaseOrders = {
list: (
params?: ListParams<PurchaseOrderFilters, PurchaseOrderSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<PurchaseOrder>> =>
this.request<PaginatedResponse<PurchaseOrder>>('GET', '/purchase_orders', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<PurchaseOrder> =>
this.request<PurchaseOrder>('GET', `/purchase_orders/${id}`, {
...options,
params: getParams(params),
}),
create: (params: PurchaseOrderCreateParams, options?: RequestOptions): Promise<PurchaseOrder> =>
this.request<PurchaseOrder>('POST', '/purchase_orders', { ...options, body: params }),
/** Drafts only: a placed order is a matter of record with the supplier. */
update: (
id: string,
params: PurchaseOrderUpdateParams,
options?: RequestOptions,
): Promise<PurchaseOrder> =>
this.request<PurchaseOrder>('PATCH', `/purchase_orders/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/purchase_orders/${id}`, options),
/** Sends the order: freezes the lines and starts the expected-date clock. */
markOrdered: (id: string, options?: RequestOptions): Promise<PurchaseOrder> =>
this.request<PurchaseOrder>('PATCH', `/purchase_orders/${id}/mark_ordered`, options),
/** Reopens a placed order for editing, while no delivery has been booked. */
markDraft: (id: string, options?: RequestOptions): Promise<PurchaseOrder> =>
this.request<PurchaseOrder>('PATCH', `/purchase_orders/${id}/mark_draft`, options),
/**
* Ends a partially received order whose balance the supplier will not
* deliver. What arrived stays; the outstanding count stays on each line.
*/
close: (
id: string,
params?: ReceivableCloseParams,
options?: RequestOptions,
): Promise<PurchaseOrder> =>
this.request<PurchaseOrder>('PATCH', `/purchase_orders/${id}/close`, {
...options,
body: params,
}),
/**
* The deliveries booked against an order. Creating one is how an order is
* received: this delivery's counts, accepted and refused, per line, at
* the line's cost — a second delivery adds to the first.
*/
stockReceipts: {
list: (
purchaseOrderId: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<PaginatedResponse<StockReceipt>> =>
this.request<PaginatedResponse<StockReceipt>>(
'GET',
`/purchase_orders/${purchaseOrderId}/stock_receipts`,
{ ...options, params: getParams(params) },
),
get: (
purchaseOrderId: string,
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<StockReceipt> =>
this.request<StockReceipt>(
'GET',
`/purchase_orders/${purchaseOrderId}/stock_receipts/${id}`,
{ ...options, params: getParams(params) },
),
create: (
purchaseOrderId: string,
params?: StockReceiptCreateParams,
options?: RequestOptions,
): Promise<StockReceipt> =>
this.request<StockReceipt>('POST', `/purchase_orders/${purchaseOrderId}/stock_receipts`, {
...options,
body: params,
}),
},
cancel: (
id: string,
params?: PurchaseOrderCancelParams,
options?: RequestOptions,
): Promise<PurchaseOrder> =>
this.request<PurchaseOrder>('PATCH', `/purchase_orders/${id}/cancel`, {
...options,
body: params,
}),
}
// ============================================
// Countries
// ============================================
readonly countries = {
list: (
params?: ListParams & Record<string, unknown>,
options?: RequestOptions,
): Promise<PaginatedResponse<Country>> =>
this.request<PaginatedResponse<Country>>('GET', '/countries', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
iso: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<Country> =>
this.request<Country>('GET', `/countries/${iso}`, {
...options,
params: getParams(params),
}),
}
// ============================================
// Files
// ============================================
/**
* Uploading the files other endpoints use — product media, imports, logos,
* documents. Each upload returns a `signed_id`: pass it unchanged to the
* endpoint that uses the file (`signed_id`, `avatar_signed_id`,
* `attachment_signed_id`, …) within a day, after which it expires.
*/
readonly files = {
/**
* Creates an upload. JSON metadata returns `upload`, the storage target to
* send the bytes to; a `FormData` body with a `file` part stores the bytes
* directly and returns `upload: null`. `upload()` does both steps for you.
*/
create: (
params: FileUploadCreateParams | FormData,
options?: RequestOptions,
): Promise<FileUpload> =>
this.request<FileUpload>('POST', '/files', { ...options, body: params }),
/**
* Uploads a file and resolves to the response; its `signed_id` is what the
* endpoint that uses the file takes. Pass `visibility: 'private'` for
* documents, imports and digital products.
*/
upload: (
file: Blob,
options: UploadFileOptions = {},
requestOptions?: RequestOptions,
): Promise<FileUpload> =>
uploadFile((body) => this.files.create(body, requestOptions), file, options),
}
// ============================================
// Staff (admin users with role assignment on the current store)
// ============================================
readonly adminUsers = {
list: (
params?: ListParams<AdminUserFilters, AdminUserSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<AdminUser>> =>
this.request<PaginatedResponse<AdminUser>>('GET', '/admin_users', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<AdminUser> =>
this.request<AdminUser>('GET', `/admin_users/${id}`, {
...options,
params: getParams(params),
}),
update: (
id: string,
params: AdminUserUpdateParams,
options?: RequestOptions,
): Promise<AdminUser> =>
this.request<AdminUser>('PATCH', `/admin_users/${id}`, { ...options, body: params }),
/**
* Removes the user's role assignments on the current store. The account is
* preserved — the user keeps access to any other stores. Mirrors the
* legacy "remove from staff" behaviour rather than the legacy controller's
* hard delete.
*/
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/admin_users/${id}`, options),
}
// ============================================
// Invitations (pending staff invitations)
// ============================================
readonly invitations = {
list: (
params?: ListParams<InvitationFilters, InvitationSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Invitation>> =>
this.request<PaginatedResponse<Invitation>>('GET', '/invitations', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<Invitation> =>
this.request<Invitation>('GET', `/invitations/${id}`, {
...options,
params: getParams(params),
}),
create: (params: InvitationCreateParams, options?: RequestOptions): Promise<Invitation> =>
this.request<Invitation>('POST', '/invitations', { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/invitations/${id}`, options),
/** Issues a fresh token + email for a pending invitation. */
resend: (id: string, options?: RequestOptions): Promise<Invitation> =>
this.request<Invitation>('PATCH', `/invitations/${id}/resend`, options),
/**
* The acceptance link of a pending invitation. It carries the token, so it
* needs write access to staff and the right to grant the invitation's role.
*/
acceptanceLink: (id: string, options?: RequestOptions): Promise<InvitationAcceptanceLink> =>
this.request<InvitationAcceptanceLink>('GET', `/invitations/${id}/acceptance_link`, options),
}
// ============================================
// API Keys (publishable + secret)
// ============================================
/**
* OAuth 2.1 consent, for the screen a merchant approves when an agent or an
* app asks for access to the store.
*
* `authorization` describes what is being asked for; `approve` and `deny`
* both answer with the `redirect_uri` the browser should then be sent to.
* These require a signed-in admin: a secret key authenticates but is not a
* person, so it can never grant authority on someone's behalf.
*/
readonly oauth = {
authorization: (
params: OauthAuthorizationParams,
options?: RequestOptions,
): Promise<OauthConsentRequest> =>
this.request<OauthConsentRequest>('GET', '/oauth/authorize', {
...options,
// The authorization request is a flat set of strings by construction,
// so it travels as query params untouched — no Ransack wrapping, and
// nothing re-derived on the way.
params: { ...params } as Record<string, string | undefined>,
}),
approve: (params: OauthAuthorizationParams, options?: RequestOptions): Promise<OauthRedirect> =>
this.request<OauthRedirect>('POST', '/oauth/authorize', { ...options, body: params }),
deny: (params: OauthAuthorizationParams, options?: RequestOptions): Promise<OauthRedirect> =>
this.request<OauthRedirect>('DELETE', '/oauth/authorize', { ...options, body: params }),
/** The OAuth clients registered against this store. */
applications: {
list: (
params?: ListParams & Record<string, unknown>,
options?: RequestOptions,
): Promise<PaginatedResponse<OauthApplication>> =>
this.request<PaginatedResponse<OauthApplication>>('GET', '/oauth/applications', {
...options,
params: params ? transformListParams(params) : undefined,
}),
create: (
params: { name: string; redirect_uri: string },
options?: RequestOptions,
): Promise<OauthApplication> =>
this.request<OauthApplication>('POST', '/oauth/applications', {
...options,
body: params,
}),
update: (
id: string,
params: Partial<{ name: string; redirect_uri: string }>,
options?: RequestOptions,
): Promise<OauthApplication> =>
this.request<OauthApplication>('PATCH', `/oauth/applications/${id}`, {
...options,
body: params,
}),
/** Removes the registration, and every grant and token with it. */
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/oauth/applications/${id}`, options ?? {}),
/**
* The live access a connected client holds, one entry per person who
* connected it. A store registers a client once and everyone connects
* to that same registration, so this is who is actually connected.
*/
tokens: {
list: (
applicationId: string,
params?: ListParams,
options?: RequestOptions,
): Promise<PaginatedResponse<OauthAccessToken>> =>
this.request<PaginatedResponse<OauthAccessToken>>(
'GET',
`/oauth/applications/${applicationId}/tokens`,
{ ...(options ?? {}), params: params ? transformListParams(params) : undefined },
),
/**
* Revokes one person's access, leaving their colleagues connected.
*/
delete: (applicationId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>(
'DELETE',
`/oauth/applications/${applicationId}/tokens/${id}`,
options ?? {},
),
},
},
}
readonly apiKeys = {
list: (
params?: ListParams<ApiKeyFilters, ApiKeySort>,
options?: RequestOptions,
): Promise<PaginatedResponse<ApiKey>> =>
this.request<PaginatedResponse<ApiKey>>('GET', '/api_keys', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<ApiKey> =>
this.request<ApiKey>('GET', `/api_keys/${id}`, {
...options,
params: getParams(params),
}),
/**
* Describes the key that authenticated this request, including its live
* scopes — useful to show the real, current authority of a secret key
* (e.g. after a scope change) rather than a cached snapshot. Only available
* to secret-key principals; a JWT admin has no single key to describe.
*/
current: (options?: RequestOptions): Promise<ApiKey> =>
this.request<ApiKey>('GET', '/api_keys/current', options ?? {}),
/**
* Creates a publishable or secret API key. For secret keys the response
* carries `plaintext_token` exactly once — store it client-side immediately
* because subsequent reads will return `null`.
*/
create: (params: ApiKeyCreateParams, options?: RequestOptions): Promise<ApiKey> =>
this.request<ApiKey>('POST', '/api_keys', { ...options, body: params }),
/**
* Updates a key's `name`. `key_type` and `scopes` are fixed at creation —
* to change authority, create a new key and revoke the old one (`revoke`).
*/
update: (id: string, params: ApiKeyUpdateParams, options?: RequestOptions): Promise<ApiKey> =>
this.request<ApiKey>('PATCH', `/api_keys/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/api_keys/${id}`, options),
/** Marks a key revoked without deleting the row (preserves audit history). */
revoke: (id: string, options?: RequestOptions): Promise<ApiKey> =>
this.request<ApiKey>('PATCH', `/api_keys/${id}/revoke`, options),
}
// ============================================
// Allowed Origins (CORS allowlist for admin cookie auth)
// ============================================
/**
* Origins permitted to call the admin API from a browser. Backs the
* `Rack::Cors` allowlist and the CSRF boundary of the admin cookie session
* (see `docs/plans/5.5-admin-auth-cookie-refresh.md`). Each entry is a
* bare `scheme://host[:port]` — no paths, queries, or fragments.
*/
readonly allowedOrigins = {
list: (
params?: ListParams<AllowedOriginFilters, AllowedOriginSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<AllowedOrigin>> =>
this.request<PaginatedResponse<AllowedOrigin>>('GET', '/allowed_origins', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<AllowedOrigin> =>
this.request<AllowedOrigin>('GET', `/allowed_origins/${id}`, {
...options,
params: getParams(params),
}),
create: (params: AllowedOriginCreateParams, options?: RequestOptions): Promise<AllowedOrigin> =>
this.request<AllowedOrigin>('POST', '/allowed_origins', { ...options, body: params }),
update: (
id: string,
params: AllowedOriginUpdateParams,
options?: RequestOptions,
): Promise<AllowedOrigin> =>
this.request<AllowedOrigin>('PATCH', `/allowed_origins/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/allowed_origins/${id}`, options),
}
// ============================================
// Webhook Endpoints + Deliveries
// ============================================
readonly emailTemplates = {
/** Every editable email template: customer emails, the layout and shared partials. */
list: (
params?: EmailTemplateLanguageParams,
options?: RequestOptions,
): Promise<{ data: EmailTemplate[] }> =>
this.request<{ data: EmailTemplate[] }>('GET', '/email_templates', { ...options, params }),
/** One template in one language, with the draft (`expand: ['draft.updated_by']` names who saved it). */
get: (
id: string,
params?: EmailTemplateLanguageParams & { expand?: string[] },
options?: RequestOptions,
): Promise<EmailTemplate> =>
this.request<EmailTemplate>('GET', `/email_templates/${id}`, {
...options,
// getParams keeps only expand and fields, so the language is added back.
params: {
...getParams(params),
...(params?.language ? { language: params.language } : {}),
},
}),
/** Goes back to Spree's default and discards the draft. Published versions stay in the history. */
revert: (
id: string,
params?: EmailTemplateVersionParams,
options?: RequestOptions,
): Promise<EmailTemplate> =>
this.request<EmailTemplate>('DELETE', `/email_templates/${id}`, { ...options, params }),
draft: {
/** Saves the draft. A save from a stale `lock_version` is refused with 409. */
update: (
id: string,
params: EmailTemplateDraftParams,
options?: RequestOptions,
): Promise<EmailTemplate> =>
this.request<EmailTemplate>('PUT', `/email_templates/${id}/draft`, {
...options,
body: params,
}),
delete: (
id: string,
params?: EmailTemplateVersionParams,
options?: RequestOptions,
): Promise<EmailTemplate> =>
this.request<EmailTemplate>('DELETE', `/email_templates/${id}/draft`, {
...options,
params,
}),
},
/** Makes the draft live; refused with 422 and each problem's email and line when it does not render. */
publish: (
id: string,
params?: EmailTemplateVersionParams,
options?: RequestOptions,
): Promise<EmailTemplate> =>
this.request<EmailTemplate>('POST', `/email_templates/${id}/publication`, {
...options,
body: params ?? {},
}),
/** Renders the template, or unsaved changes to it, with sample data. */
preview: (
id: string,
params?: EmailTemplatePreviewParams,
options?: RequestOptions,
): Promise<EmailTemplatePreview> =>
this.request<EmailTemplatePreview>('POST', `/email_templates/${id}/preview`, {
...options,
body: params ?? {},
}),
/** Sends the rendered template to the signed-in admin. */
sendTest: (
id: string,
params?: EmailTemplatePreviewParams,
options?: RequestOptions,
): Promise<{ sent_to: string }> =>
this.request<{ sent_to: string }>('POST', `/email_templates/${id}/test_email`, {
...options,
body: params ?? {},
}),
sampleRecords: {
/** The store's latest records the template can be previewed with, newest first. */
list: (
id: string,
params?: { email_key?: string },
options?: RequestOptions,
): Promise<{ data: EmailTemplateSampleRecord[] }> =>
this.request<{ data: EmailTemplateSampleRecord[] }>(
'GET',
`/email_templates/${id}/sample_records`,
{ ...options, params },
),
},
revisions: {
/** Published versions in one language, newest first. */
list: (
id: string,
params?: ListParams & EmailTemplateLanguageParams & Record<string, unknown>,
options?: RequestOptions,
): Promise<PaginatedResponse<EmailTemplateRevision>> =>
this.request<PaginatedResponse<EmailTemplateRevision>>(
'GET',
`/email_templates/${id}/revisions`,
{
...options,
// The language picks the version, so it stays out of the Ransack filters.
params: params
? (({ language, ...list }) => ({
...transformListParams(list),
...(language ? { language } : {}),
}))(params)
: undefined,
},
),
/** Copies a revision into the draft, to publish like any change. */
restore: (
id: string,
revisionId: string,
params?: EmailTemplateRestoreParams,
options?: RequestOptions,
): Promise<EmailTemplate> =>
this.request<EmailTemplate>(
'POST',
`/email_templates/${id}/revisions/${revisionId}/restoration`,
{ ...options, body: params ?? {} },
),
},
}
/**
* The events a webhook endpoint can subscribe to, including those installed
* extensions declare. A `credential` event carries a live credential and
* needs `credential_permission` to subscribe to; a `deprecated` one names the
* event that replaces it in `replaced_by`.
*/
readonly webhookEvents = {
list: (options?: RequestOptions): Promise<{ data: WebhookEvent[]; meta: { count: number } }> =>
this.request<{ data: WebhookEvent[]; meta: { count: number } }>(
'GET',
'/webhook_events',
options,
),
}
/**
* Outbound webhook subscriptions: each endpoint receives a signed POST when
* any subscribed event fires (`subscriptions` is a list of event names or
* `*` patterns). The plaintext `secret_key` is returned **once** on create —
* persist it client-side immediately because later reads serialize `null`.
* Each endpoint exposes a nested `deliveries` log for auditing and retry.
*/
readonly webhookEndpoints = {
list: (
params?: ListParams<WebhookEndpointFilters, WebhookEndpointSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<WebhookEndpoint>> =>
this.request<PaginatedResponse<WebhookEndpoint>>('GET', '/webhook_endpoints', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (
id: string,
params?: { expand?: string[] },
options?: RequestOptions,
): Promise<WebhookEndpoint> =>
this.request<WebhookEndpoint>('GET', `/webhook_endpoints/${id}`, {
...options,
params: getParams(params),
}),
create: (
params: WebhookEndpointCreateParams,
options?: RequestOptions,
): Promise<WebhookEndpoint> =>
this.request<WebhookEndpoint>('POST', '/webhook_endpoints', { ...options, body: params }),
update: (
id: string,
params: WebhookEndpointUpdateParams,
options?: RequestOptions,
): Promise<WebhookEndpoint> =>
this.request<WebhookEndpoint>('PATCH', `/webhook_endpoints/${id}`, {
...options,
body: params,
}),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/webhook_endpoints/${id}`, options),
/** Fires a synthetic `webhook.test` delivery so admins can verify reachability. */
sendTest: (id: string, options?: RequestOptions): Promise<WebhookDelivery> =>
this.request<WebhookDelivery>('POST', `/webhook_endpoints/${id}/send_test`, options),
/** Re-enables an endpoint that was disabled (manually or after auto-disable). */
enable: (id: string, options?: RequestOptions): Promise<WebhookEndpoint> =>
this.request<WebhookEndpoint>('PATCH', `/webhook_endpoints/${id}/enable`, options),
/** Manually disable an endpoint with an optional human-readable reason. */
disable: (
id: string,
params?: WebhookEndpointDisableParams,
options?: RequestOptions,
): Promise<WebhookEndpoint> =>
this.request<WebhookEndpoint>('PATCH', `/webhook_endpoints/${id}/disable`, {
...options,
body: params,
}),
deliveries: {
list: (
endpointId: string,
params?: ListParams<WebhookDeliveryFilters, WebhookDeliverySort>,
options?: RequestOptions,
): Promise<PaginatedResponse<WebhookDelivery>> =>
this.request<PaginatedResponse<WebhookDelivery>>(
'GET',
`/webhook_endpoints/${endpointId}/deliveries`,
{ ...options, params: params ? transformListParams(params) : undefined },
),
get: (endpointId: string, id: string, options?: RequestOptions): Promise<WebhookDelivery> =>
this.request<WebhookDelivery>(
'GET',
`/webhook_endpoints/${endpointId}/deliveries/${id}`,
options,
),
/**
* Creates a new delivery row with the same payload + event_name and
* queues it. The original row is preserved for audit history.
*/
redeliver: (
endpointId: string,
id: string,
options?: RequestOptions,
): Promise<WebhookDelivery> =>
this.request<WebhookDelivery>(
'POST',
`/webhook_endpoints/${endpointId}/deliveries/${id}/redeliver`,
options,
),
},
}
// ============================================
// Roles (staff roles + catalog permissions)
// ============================================
readonly roles = {
list: (
params?: ListParams<RoleFilters, RoleSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Role>> =>
this.request<PaginatedResponse<Role>>('GET', '/roles', {
...options,
params: params ? transformListParams(params) : undefined,
}),
get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Role> =>
this.request<Role>('GET', `/roles/${id}`, {
...options,
params: getParams(params),
}),
create: (params: RoleCreateParams, options?: RequestOptions): Promise<Role> =>
this.request<Role>('POST', '/roles', { ...options, body: params }),
update: (id: string, params: RoleUpdateParams, options?: RequestOptions): Promise<Role> =>
this.request<Role>('PATCH', `/roles/${id}`, { ...options, body: params }),
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/roles/${id}`, options),
}
// ============================================
// Permissions (the grant vocabulary — read-only catalog)
// ============================================
readonly permissions = {
list: (options?: RequestOptions): Promise<{ data: Permission[]; meta: { count: number } }> =>
this.request<{ data: Permission[]; meta: { count: number } }>('GET', '/permissions', options),
}
}
// Re-export for type convenience
export type {
EmailPasswordLogin,
ListParams,
LoginCredentials,
PaginatedResponse,
ProviderLogin,
RequestOptions,
}