@sixtyninecommerce/admin 0.11.0 → 0.12.0

package/dist/stored-value/index.d.ts

@@ -33,7 +33,12 @@ export interface StoredValueEntry {
     id: string;
     createdAt: string;
     occurredAt: string;
-    entryType: 'issue' | 'redeem' | 'reversal' | 'adjustment' | 'expiry' | 'forfeit';
+    /**
+     * `payout`: store credit moved from an order, paid back to the payment it came from
+     * (`payOut`); a payout whose refund did not happen comes back as a `reversal` with
+     * `sourceType: 'payout_refund'`. Treat a value you do not know as a movement you do not report.
+     */
+    entryType: 'issue' | 'redeem' | 'reversal' | 'adjustment' | 'expiry' | 'forfeit' | 'payout';
     /** Signed: credits positive, debits negative. */
     amount: number;
     balanceAfter: number;
@@ -48,6 +53,31 @@ export interface StoredValueEntry {
     onBehalfOfRef: string | null;
     deviceRef: string | null;
     reason: string | null;
+    /**
+     * Store credit moved from an order (`sourceType: 'order_credit'`): the decision that moved it,
+     * `return`, `correction`, `order_edit`, `surcharge`, `fulfillment_cancel`, `cancel`,
+     * `overpayment` or `till_return` (a value you do not know is another decision). Null otherwise,
+     * and on an engine before incentives sprint 8.
+     */
+    origin: string | null;
+    /**
+     * The record of that decision, when it has one: the return's id (`return`), the credit note's
+     * (`correction`), the surcharge's, the fulfillment's, or the till return's. Null otherwise.
+     */
+    originRef: string | null;
+    /**
+     * The lot (an `order_credit` entry's id) a `payout` pays back, or its `payout_refund` restore
+     * gives back to. Null otherwise, and on an engine before payouts.
+     */
+    lotId: string | null;
+    /**
+     * Store credit moved from an order: whether the customer expressly agreed to store credit
+     * instead of a refund to their payment (EU consumer law), as the staff member who chose it
+     * recorded, a till return's included (`pos.returns.create`'s `customerAgreed`). Null when nobody
+     * said (the door was not told, a till that did not ask, a move recorded before the field), on
+     * every other entry, and on an engine before it. A record, never a condition.
+     */
+    customerAgreed: boolean | null;
 }
 export interface StoredValueStatement {
     account: StoredValueAccount;
@@ -56,17 +86,34 @@ export interface StoredValueStatement {
     entries: StoredValueEntry[];
     totalItems: number;
 }
-/** `outstanding = issued − redeemed + reversed + adjusted − expired − forfeited`. */
+/**
+ * `outstanding = issued − redeemed + reversed + adjusted − expired − forfeited − paidOut`, where
+ * `paidOut` is store credit paid back to money (`payOut`), net of the payouts whose refund did not
+ * happen. On an engine before incentives sprint 8 the split of `issued` and `paidOut` are null
+ * (it serves neither; nothing was paid out there).
+ */
 export interface StoredValueLiability {
     unit: string;
     kind: string;
     accounts: number;
     issued: number;
+    /** Of `issued`: created by staff without payment (goodwill, a staff gift card). */
+    issuedGoodwill: number | null;
+    /** Of `issued`: an order's money moved to store credit instead of a refund. */
+    issuedFromOrders: number | null;
+    /** Of `issued`: store credit for goods a till took back that no order payment paid for. */
+    issuedFromReturns: number | null;
     redeemed: number;
+    /**
+     * Value given back by refunds and cancelled payments. A payout's restore (a `reversal` with
+     * `sourceType: 'payout_refund'`) is NOT here: the engine nets it in `paidOut`.
+     */
     reversed: number;
     adjusted: number;
     expired: number;
     forfeited: number;
+    /** Paid back to money (`payOut`), net of the payouts whose refund did not happen. */
+    paidOut: number | null;
     outstanding: number;
 }
 export interface IssueStoredValueInput {
@@ -119,6 +166,25 @@ export interface RedeemStoredValueInput {
     /** The code of the store's payment method on the `stored-value` handler. */
     method: string;
 }
+export interface PayOutStoreCreditInput {
+    /** The lot: an `order_credit` entry of the customer's store credit (`StoredValueEntry.id`). */
+    entryId: string;
+    /** Minor units of the store credit's currency. Omitted: everything the lot can pay back. */
+    amount?: number;
+    /** Free text, on the Refund and the order note. */
+    reason?: string;
+}
+/** The refund a payout made, of the payment the store credit came from. */
+export interface StoreCreditPayoutRefund {
+    id: string;
+    /** Minor units. */
+    total: number;
+    /** `Settled`, or `Pending` while the payment provider has not confirmed it. */
+    state: string;
+    method: string;
+    transactionId: string | null;
+    reason: string | null;
+}
 export interface StoredValueModule {
     accounts(filter?: {
         customerId?: string;
@@ -173,11 +239,31 @@ export interface StoredValueModule {
     unblock(id: string, reason: string, options?: Call): Promise<StoredValueAccount>;
     /**
      * Pay part (or all) of an order from an account (`redeemStoredValue`), through the platform's
-     * payment position: the order lock, the outstanding bound and the store's deposit policy apply,
-     * and the ledger is debited in the payment's own transaction. Requires UpdateOrder. Answers the
-     * payment the SERVER recorded for this call; a repeat under the same key answers the same one.
+     * payment position: the order lock and the outstanding bound apply, and the ledger is debited in
+     * the payment's own transaction. Requires UpdateOrder. Answers the payment the SERVER recorded
+     * for this call; a repeat under the same key answers the same one.
+     *
+     * Stored value may pay PART of an order still arranging payment whatever the store's deposit
+     * policy (split tender, not a deposit): the order is placed only once its money covers it, so the
+     * rest is paid by another method, and cancelling the payment gives the part back to the account.
+     * On a parked or placed order a part is a deposit, refused `DEPOSITS_NOT_ENABLED` on a store
+     * without deposits.
      */
     redeem(input: RedeemStoredValueInput, options?: Call): Promise<StoredValueRedemption>;
+    /**
+     * Requires UpdateOrder AND ManageStoredValue (no Stored Value grant: it pays the customer's own
+     * money back; a blocked wallet may be paid out). Pay store credit moved from an order back to the
+     * payment it came from (`payOutStoreCredit`): a refund of that payment, the last step. Only an
+     * `order_credit` lot (`STORE_CREDIT_PAYOUT_NOT_PAYABLE`); at most what it still holds and what
+     * the customer can spend (`STORE_CREDIT_PAYOUT_EXCEEDED`; the thrown error's
+     * `extensions.storeCredit.payable` says how much may go); and
+     * the refund's own refusals (`REFUND_REFUSED`, …), after which the store credit is given back to
+     * its lot (a `reversal` of `sourceType: 'payout_refund'`). Send an
+     * `idempotencyKey`: a provider answer that is unknown answers `IDEMPOTENCY_OUTCOME_UNKNOWN`, the
+     * store credit stays paid out until `reconcileRefundOutcome`, and a repeat of the key replays the
+     * refund (MADE) or runs again (NOT_MADE). Needs an engine that serves it (incentives sprint 8).
+     */
+    payOut(input: PayOutStoreCreditInput, options?: Call): Promise<StoreCreditPayoutRefund>;
     /**
      * Requires ReadStoredValue. The store's refund-to-credit switch and whether it is usable now.
      * Needs an engine that serves `storeCreditSettings` (incentives sprint 8).
@@ -342,13 +428,18 @@ export interface StoredValueRedemption {
 }
 export declare const STORED_VALUE_ACCOUNTS_QUERY = "\n  query StoredValueAccounts($customerId: ID, $kind: String, $take: Int, $skip: Int) {\n    storedValueAccounts(customerId: $customerId, kind: $kind, take: $take, skip: $skip) {\n      items { \n  id\n  createdAt\n  updatedAt\n  kind\n  unit\n  customerId\n  codeLast4\n  expiresAt\n  expiresOn\n  status\n  balance\n  spendable\n }\n      totalItems\n    }\n  }\n";
 export declare const STORED_VALUE_ACCOUNT_QUERY = "\n  query StoredValueAccount($id: ID!) {\n    storedValueAccount(id: $id) { \n  id\n  createdAt\n  updatedAt\n  kind\n  unit\n  customerId\n  codeLast4\n  expiresAt\n  expiresOn\n  status\n  balance\n  spendable\n }\n  }\n";
-export declare const STORED_VALUE_STATEMENT_QUERY = "\n  query StoredValueStatement($accountId: ID!, $from: DateTime, $to: DateTime, $take: Int, $skip: Int) {\n    storedValueStatement(accountId: $accountId, from: $from, to: $to, take: $take, skip: $skip) {\n      account { \n  id\n  createdAt\n  updatedAt\n  kind\n  unit\n  customerId\n  codeLast4\n  expiresAt\n  expiresOn\n  status\n  balance\n  spendable\n }\n      openingBalance\n      closingBalance\n      totalItems\n      entries {\n        id createdAt occurredAt entryType amount balanceAfter unit sourceType sourceId paymentId\n        orderId locationId actorType actorId onBehalfOfRef deviceRef reason\n      }\n    }\n  }\n";
-export declare const STORED_VALUE_LIABILITY_QUERY = "\n  query StoredValueLiability($at: DateTime, $kind: String, $locationId: ID) {\n    storedValueLiability(at: $at, kind: $kind, locationId: $locationId) {\n      unit kind accounts issued redeemed reversed adjusted expired forfeited outstanding\n    }\n  }\n";
+export declare const STORED_VALUE_STATEMENT_QUERY = "\n  query StoredValueStatement($accountId: ID!, $from: DateTime, $to: DateTime, $take: Int, $skip: Int) {\n    storedValueStatement(accountId: $accountId, from: $from, to: $to, take: $take, skip: $skip) {\n      account { \n  id\n  createdAt\n  updatedAt\n  kind\n  unit\n  customerId\n  codeLast4\n  expiresAt\n  expiresOn\n  status\n  balance\n  spendable\n }\n      openingBalance\n      closingBalance\n      totalItems\n      entries {\n        id createdAt occurredAt entryType amount balanceAfter unit sourceType sourceId paymentId\n        orderId locationId actorType actorId onBehalfOfRef deviceRef reason origin originRef lotId\n        customerAgreed\n      }\n    }\n  }\n";
+export declare const STORED_VALUE_LIABILITY_QUERY = "\n  query StoredValueLiability($at: DateTime, $kind: String, $locationId: ID) {\n    storedValueLiability(at: $at, kind: $kind, locationId: $locationId) {\n      unit kind accounts issued issuedGoodwill issuedFromOrders issuedFromReturns redeemed\n      reversed adjusted expired forfeited paidOut outstanding\n    }\n  }\n";
+/** `document` without the fields above: what an engine before them accepts. */
+export declare function withoutWalletFields(document: string): string;
+/** `document` without the consent field: what an engine of sprint 8 before PR 6a accepts. */
+export declare function withoutConsentField(document: string): string;
 export declare const ISSUE_STORED_VALUE_MUTATION = "\n  mutation IssueStoredValue($input: IssueStoredValueInput!, $idempotencyKey: String) {\n    issueStoredValue(input: $input, idempotencyKey: $idempotencyKey) { \n  id\n  createdAt\n  updatedAt\n  kind\n  unit\n  customerId\n  codeLast4\n  expiresAt\n  expiresOn\n  status\n  balance\n  spendable\n }\n  }\n";
 export declare const ADJUST_STORED_VALUE_MUTATION = "\n  mutation AdjustStoredValue($input: AdjustStoredValueInput!, $idempotencyKey: String) {\n    adjustStoredValue(input: $input, idempotencyKey: $idempotencyKey) { \n  id\n  createdAt\n  updatedAt\n  kind\n  unit\n  customerId\n  codeLast4\n  expiresAt\n  expiresOn\n  status\n  balance\n  spendable\n }\n  }\n";
 export declare const BLOCK_STORED_VALUE_MUTATION = "\n  mutation BlockStoredValueAccount($id: ID!, $reason: String!) {\n    blockStoredValueAccount(id: $id, reason: $reason) { \n  id\n  createdAt\n  updatedAt\n  kind\n  unit\n  customerId\n  codeLast4\n  expiresAt\n  expiresOn\n  status\n  balance\n  spendable\n }\n  }\n";
 export declare const UNBLOCK_STORED_VALUE_MUTATION = "\n  mutation UnblockStoredValueAccount($id: ID!, $reason: String!) {\n    unblockStoredValueAccount(id: $id, reason: $reason) { \n  id\n  createdAt\n  updatedAt\n  kind\n  unit\n  customerId\n  codeLast4\n  expiresAt\n  expiresOn\n  status\n  balance\n  spendable\n }\n  }\n";
 export declare const SET_STORED_VALUE_EXPIRY_MUTATION = "\n  mutation SetStoredValueAccountExpiry(\n    $id: ID!\n    $expiresOn: String\n    $reason: String!\n    $idempotencyKey: String\n  ) {\n    setStoredValueAccountExpiry(\n      id: $id\n      expiresOn: $expiresOn\n      reason: $reason\n      idempotencyKey: $idempotencyKey\n    ) { \n  id\n  createdAt\n  updatedAt\n  kind\n  unit\n  customerId\n  codeLast4\n  expiresAt\n  expiresOn\n  status\n  balance\n  spendable\n }\n  }\n";
+export declare const PAY_OUT_STORE_CREDIT_MUTATION = "\n  mutation PayOutStoreCredit($input: PayOutStoreCreditInput!, $idempotencyKey: String) {\n    payOutStoreCredit(input: $input, idempotencyKey: $idempotencyKey) {\n      id\n      total\n      state\n      method\n      transactionId\n      reason\n    }\n  }\n";
 export declare const REDEEM_STORED_VALUE_MUTATION = "\n  mutation RedeemStoredValue($input: RedeemStoredValueInput!, $idempotencyKey: String) {\n    redeemStoredValue(input: $input, idempotencyKey: $idempotencyKey) {\n      orderId\n      paymentId\n      accountId\n      amount\n    }\n  }\n";
 export declare const STORE_CREDIT_SETTINGS_QUERY = "\n  query StoreCreditSettings {\n    storeCreditSettings { \n  refundToCredit\n  book\n  available\n  code\n  message\n }\n  }\n";
 export declare const UPDATE_STORE_CREDIT_SETTINGS_MUTATION = "\n  mutation UpdateStoreCreditSettings($input: UpdateStoreCreditSettingsInput!) {\n    updateStoreCreditSettings(input: $input) { \n  refundToCredit\n  book\n  available\n  code\n  message\n }\n  }\n";

package/dist/stored-value/index.js

@@ -1,3 +1,4 @@
+import { isUnknownFieldRejection } from '../payments/store-credit-fields.js';
 const ACCOUNT_FIELDS = `
   id
   createdAt
@@ -34,7 +35,8 @@ export const STORED_VALUE_STATEMENT_QUERY = /* GraphQL */ `
       totalItems
       entries {
         id createdAt occurredAt entryType amount balanceAfter unit sourceType sourceId paymentId
-        orderId locationId actorType actorId onBehalfOfRef deviceRef reason
+        orderId locationId actorType actorId onBehalfOfRef deviceRef reason origin originRef lotId
+        customerAgreed
       }
     }
   }
@@ -42,10 +44,28 @@ export const STORED_VALUE_STATEMENT_QUERY = /* GraphQL */ `
 export const STORED_VALUE_LIABILITY_QUERY = /* GraphQL */ `
   query StoredValueLiability($at: DateTime, $kind: String, $locationId: ID) {
     storedValueLiability(at: $at, kind: $kind, locationId: $locationId) {
-      unit kind accounts issued redeemed reversed adjusted expired forfeited outstanding
+      unit kind accounts issued issuedGoodwill issuedFromOrders issuedFromReturns redeemed
+      reversed adjusted expired forfeited paidOut outstanding
     }
   }
 `;
+/**
+ * The statement's and the liability's fields from incentives sprint 8 (the wallet's origins and
+ * split, PR 1; the payout's `lotId` and `paidOut`, PR 5; the customer's consent, PR 6a). An engine
+ * before them refuses a document naming one as a whole, before it runs; the same document without
+ * them reads as it did then.
+ */
+const WALLET_FIELDS = /\b(?:origin|originRef|lotId|customerAgreed|issuedGoodwill|issuedFromOrders|issuedFromReturns|paidOut)\b/g;
+/** `document` without the fields above: what an engine before them accepts. */
+export function withoutWalletFields(document) {
+    return document.replace(WALLET_FIELDS, '');
+}
+/** The newest of them, the customer's consent (PR 6a): an engine with the others lacks only it. */
+const CONSENT_FIELD = /\bcustomerAgreed\b/g;
+/** `document` without the consent field: what an engine of sprint 8 before PR 6a accepts. */
+export function withoutConsentField(document) {
+    return document.replace(CONSENT_FIELD, '');
+}
 export const ISSUE_STORED_VALUE_MUTATION = /* GraphQL */ `
   mutation IssueStoredValue($input: IssueStoredValueInput!, $idempotencyKey: String) {
     issueStoredValue(input: $input, idempotencyKey: $idempotencyKey) { ${ACCOUNT_FIELDS} }
@@ -81,6 +101,18 @@ export const SET_STORED_VALUE_EXPIRY_MUTATION = /* GraphQL */ `
     ) { ${ACCOUNT_FIELDS} }
   }
 `;
+export const PAY_OUT_STORE_CREDIT_MUTATION = /* GraphQL */ `
+  mutation PayOutStoreCredit($input: PayOutStoreCreditInput!, $idempotencyKey: String) {
+    payOutStoreCredit(input: $input, idempotencyKey: $idempotencyKey) {
+      id
+      total
+      state
+      method
+      transactionId
+      reason
+    }
+  }
+`;
 export const REDEEM_STORED_VALUE_MUTATION = /* GraphQL */ `
   mutation RedeemStoredValue($input: RedeemStoredValueInput!, $idempotencyKey: String) {
     redeemStoredValue(input: $input, idempotencyKey: $idempotencyKey) {
@@ -202,6 +234,21 @@ export const ISSUE_GIFT_CARD_MUTATION = /* GraphQL */ `
 `;
 export function createStoredValueModule(transport) {
     const read = async (query, variables, options) => transport.graphql({ api: 'admin', query, variables }, options);
+    // A read naming the sprint-8 fields, sent again to an engine that refuses one as unknown: first
+    // without the consent field alone (an engine with the rest of sprint 8), then without any of them.
+    const readWallet = async (query, variables, options) => {
+        const documents = [...new Set([query, withoutConsentField(query), withoutWalletFields(query)])];
+        for (const [index, document] of documents.entries()) {
+            try {
+                return await read(document, variables, options);
+            }
+            catch (error) {
+                if (index === documents.length - 1 || !isUnknownFieldRejection(error))
+                    throw error;
+            }
+        }
+        throw new Error('unreachable: the last document either answers or throws');
+    };
     // The key is an ARGUMENT on the Admin API; `undefined` keeps an omitted key off the wire.
     const write = async (query, variables, options) => transport.graphql({ api: 'admin', query, variables: { ...variables, idempotencyKey: options?.idempotencyKey } }, options);
     return {
@@ -212,10 +259,27 @@ export function createStoredValueModule(transport) {
             return (await read(STORED_VALUE_ACCOUNT_QUERY, { id }, options)).storedValueAccount;
         },
         async statement(accountId, window = {}, options) {
-            return (await read(STORED_VALUE_STATEMENT_QUERY, { accountId, ...window }, options)).storedValueStatement;
+            const statement = (await readWallet(STORED_VALUE_STATEMENT_QUERY, { accountId, ...window }, options)).storedValueStatement;
+            return {
+                ...statement,
+                entries: statement.entries.map((entry) => ({
+                    ...entry,
+                    origin: entry.origin ?? null,
+                    originRef: entry.originRef ?? null,
+                    lotId: entry.lotId ?? null,
+                    customerAgreed: entry.customerAgreed ?? null,
+                })),
+            };
         },
         async liability(filter = {}, options) {
-            return (await read(STORED_VALUE_LIABILITY_QUERY, filter, options)).storedValueLiability;
+            const rows = (await readWallet(STORED_VALUE_LIABILITY_QUERY, filter, options)).storedValueLiability;
+            return rows.map((row) => ({
+                ...row,
+                issuedGoodwill: row.issuedGoodwill ?? null,
+                issuedFromOrders: row.issuedFromOrders ?? null,
+                issuedFromReturns: row.issuedFromReturns ?? null,
+                paidOut: row.paidOut ?? null,
+            }));
         },
         async issue(input, options) {
             return (await write(ISSUE_STORED_VALUE_MUTATION, { input }, options)).issueStoredValue;
@@ -235,6 +299,9 @@ export function createStoredValueModule(transport) {
         async redeem(input, options) {
             return (await write(REDEEM_STORED_VALUE_MUTATION, { input }, options)).redeemStoredValue;
         },
+        async payOut(input, options) {
+            return (await write(PAY_OUT_STORE_CREDIT_MUTATION, { input }, options)).payOutStoreCredit;
+        },
         async storeCreditSettings(options) {
             return (await read(STORE_CREDIT_SETTINGS_QUERY, {}, options)).storeCreditSettings;
         },

package/dist/tax/display-policy.d.ts

@@ -0,0 +1,105 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/** `channel` follows the store's "prices include tax"; `gross` = incl. tax; `net` = excl. tax. */
+export type TaxDisplayDefault = 'channel' | 'gross' | 'net';
+/** `inherit` leaves B2B and trade customers on the default. */
+export type TaxDisplayB2b = 'inherit' | 'gross' | 'net';
+/** What a shopper is shown: `GROSS` = incl. tax, `NET` = excl. tax (the Shop API's casing). */
+export type TaxDisplayMode = 'GROSS' | 'NET';
+/** The shoppers a policy is answered for, in the order a settings screen lists them. */
+export type TaxDisplayAudience = 'VISITOR' | 'RETAIL_CUSTOMER' | 'B2B_CUSTOMER' | 'LISTED_COUNTRY_CUSTOMER';
+/**
+ * A store's price-display policy: who sees prices with or without tax. Three Channel custom fields
+ * (`taxDisplayDefault`, `taxDisplayB2b`, `taxExclusiveCountries`), in the organization settings
+ * group `settings.tax_display`.
+ */
+export interface TaxDisplayPolicy {
+    default: TaxDisplayDefault;
+    b2b: TaxDisplayB2b;
+    /**
+     * Upper-case ISO-3166 alpha-2 codes; empty turns the rule off. A customer shipping to a listed
+     * country always sees prices excl. tax, whatever the other two say, AND is taxed by that
+     * country's tax zone instead of the store's: this list changes what customers are charged, not
+     * only what they are shown.
+     */
+    countries: string[];
+}
+export interface TaxDisplayAudienceAnswer {
+    audience: TaxDisplayAudience;
+    /** The listed country the answer is judged for (`LISTED_COUNTRY_CUSTOMER` only); else null. */
+    countryCode: string | null;
+    /** What this shopper is shown, by the rule the storefront applies. Null when `dependsOnStore`. */
+    mode: TaxDisplayMode | null;
+    /**
+     * True only in an organization's workspace, for an answer that falls back to "prices include
+     * tax": each member store keeps its own, so there is no one answer.
+     */
+    dependsOnStore: boolean;
+}
+/** A policy and who it shows which tax figure, as the engine answers it. */
+export interface TaxDisplayPolicyView extends TaxDisplayPolicy {
+    /** The store's own storage mode, the policy's last fallback. */
+    pricesIncludeTax: boolean;
+    /**
+     * Visitor, retail customer, B2B or trade customer, then a customer in the FIRST listed country
+     * (absent while none is listed). The same rule decides the storefront's prices and the prices an
+     * order's emails, receipts and invoices show its customer.
+     */
+    audiences: TaxDisplayAudienceAnswer[];
+}
+/**
+ * The ACTIVE store's price-display policy (`admin.tax.displayPolicy`). Reading needs any
+ * administrator permission on the store; writing needs `UpdateChannel` (the policy is stored on
+ * the channel and written through core `updateChannel`).
+ *
+ * The engine owns the rule: who sees what is never worked out in the client. Ask {@link preview}
+ * for a policy the merchant has not saved.
+ */
+export interface TaxDisplayPolicyModule {
+    /**
+     * The policy the storefront applies and who it shows which figure. For a store that inherits
+     * `settings.tax_display` from its organization this is the organization's policy. An unreadable
+     * stored value reads as its default (`channel` / `inherit` / no countries); a stored choice is
+     * read trimmed and lower-cased, as the storefront reads it.
+     *
+     * @effect read
+     */
+    get(options?: Call): Promise<TaxDisplayPolicyView>;
+    /**
+     * Who `policy` WOULD show which figure on this store, without saving anything.
+     *
+     * Refused `CHANNEL_SETTINGS_INVALID` (`ValidationError`, one `details[]` entry per field named
+     * `customFields.<field>`) for a policy the save would refuse: a choice that is not exactly one of
+     * the values above, a country code that is not two letters, a country listed twice, or more than
+     * 300 countries.
+     *
+     * @effect read
+     */
+    preview(policy: TaxDisplayPolicy, options?: Call): Promise<TaxDisplayPolicyView>;
+    /**
+     * Replace the whole policy, and answer it as the engine now applies it.
+     *
+     * Pass all three fields: read with {@link get}, change what you mean to, send it back. An empty
+     * country list clears the stored list.
+     *
+     * Refused, before anything is written, `CHANNEL_SETTINGS_INVALID` (`ValidationError`) for a policy
+     * {@link preview} refuses. Refused by the save itself:
+     * - `ORGANIZATION_SETTINGS_INHERITED` (`BusinessRuleError`, 422) while the store uses its
+     *   organization's policy: override it first (`tenant.settingsSources`), or change it in the
+     *   organization's workspace;
+     * - `MANAGED_BY_ORGANIZATION` (`BusinessRuleError`, 422) if the organization manages the group;
+     * - `FORBIDDEN` without `UpdateChannel`.
+     *
+     * @effect write
+     */
+    set(policy: TaxDisplayPolicy, options?: Call): Promise<TaxDisplayPolicyView>;
+}
+export declare const TAX_DISPLAY_POLICY_QUERY = "\n  query TaxDisplayPolicy {\n    taxDisplayPolicy { \n  default\n  b2b\n  countries\n  pricesIncludeTax\n  audiences {\n    audience\n    countryCode\n    mode\n    dependsOnStore\n  }\n }\n  }\n";
+export declare const PREVIEW_TAX_DISPLAY_POLICY_QUERY = "\n  query PreviewTaxDisplayPolicy($input: TaxDisplayPolicyInput!) {\n    previewTaxDisplayPolicy(input: $input) { \n  default\n  b2b\n  countries\n  pricesIncludeTax\n  audiences {\n    audience\n    countryCode\n    mode\n    dependsOnStore\n  }\n }\n  }\n";
+/**
+ * The save's first step: the engine judges the policy (the preview's refusal is the save's) and
+ * names the channel `updateChannel` must be given, in one request with the save's call options.
+ */
+export declare const CHECK_TAX_DISPLAY_POLICY_QUERY = "\n  query CheckTaxDisplayPolicy($input: TaxDisplayPolicyInput!) {\n    activeChannel { id }\n    previewTaxDisplayPolicy(input: $input) { default }\n  }\n";
+export declare const SET_TAX_DISPLAY_POLICY_MUTATION = "\n  mutation SetTaxDisplayPolicy($input: UpdateChannelInput!) {\n    updateChannel(input: $input) {\n      ... on Channel { id }\n      ... on ErrorResult { errorCode message }\n    }\n  }\n";
+export declare function createTaxDisplayPolicyModule(transport: Transport): TaxDisplayPolicyModule;

package/dist/tax/display-policy.js

@@ -0,0 +1,84 @@
+import { errorFromErrorResult, isErrorResult, } from '@sixtyninecommerce/core';
+const VIEW_FIELDS = /* GraphQL */ `
+  default
+  b2b
+  countries
+  pricesIncludeTax
+  audiences {
+    audience
+    countryCode
+    mode
+    dependsOnStore
+  }
+`;
+export const TAX_DISPLAY_POLICY_QUERY = /* GraphQL */ `
+  query TaxDisplayPolicy {
+    taxDisplayPolicy { ${VIEW_FIELDS} }
+  }
+`;
+export const PREVIEW_TAX_DISPLAY_POLICY_QUERY = /* GraphQL */ `
+  query PreviewTaxDisplayPolicy($input: TaxDisplayPolicyInput!) {
+    previewTaxDisplayPolicy(input: $input) { ${VIEW_FIELDS} }
+  }
+`;
+/**
+ * The save's first step: the engine judges the policy (the preview's refusal is the save's) and
+ * names the channel `updateChannel` must be given, in one request with the save's call options.
+ */
+export const CHECK_TAX_DISPLAY_POLICY_QUERY = /* GraphQL */ `
+  query CheckTaxDisplayPolicy($input: TaxDisplayPolicyInput!) {
+    activeChannel { id }
+    previewTaxDisplayPolicy(input: $input) { default }
+  }
+`;
+export const SET_TAX_DISPLAY_POLICY_MUTATION = /* GraphQL */ `
+  mutation SetTaxDisplayPolicy($input: UpdateChannelInput!) {
+    updateChannel(input: $input) {
+      ... on Channel { id }
+      ... on ErrorResult { errorCode message }
+    }
+  }
+`;
+/** Exactly the input the engine takes: no extra keys travel. */
+function inputOf(policy) {
+    return { default: policy.default, b2b: policy.b2b, countries: [...policy.countries] };
+}
+export function createTaxDisplayPolicyModule(transport) {
+    const get = async (options) => {
+        const data = await transport.graphql({ api: 'admin', query: TAX_DISPLAY_POLICY_QUERY }, options);
+        return data.taxDisplayPolicy;
+    };
+    return {
+        get,
+        async preview(policy, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: PREVIEW_TAX_DISPLAY_POLICY_QUERY,
+                variables: { input: inputOf(policy) },
+            }, options);
+            return data.previewTaxDisplayPolicy;
+        },
+        async set(policy, options) {
+            const input = inputOf(policy);
+            const checked = await transport.graphql({ api: 'admin', query: CHECK_TAX_DISPLAY_POLICY_QUERY, variables: { input } }, options);
+            const data = await transport.graphql({
+                api: 'admin',
+                query: SET_TAX_DISPLAY_POLICY_MUTATION,
+                variables: {
+                    input: {
+                        id: checked.activeChannel.id,
+                        customFields: {
+                            taxDisplayDefault: input.default,
+                            taxDisplayB2b: input.b2b,
+                            // `null` is the column's "off", and the only value that clears a stored list.
+                            taxExclusiveCountries: input.countries.length === 0 ? null : JSON.stringify(input.countries),
+                        },
+                    },
+                },
+            }, options);
+            if (isErrorResult(data.updateChannel))
+                throw errorFromErrorResult(data.updateChannel);
+            return get(options);
+        },
+    };
+}

package/dist/tax/index.d.ts

@@ -1,5 +1,6 @@
 import { type Page, type Transport } from '@sixtyninecommerce/core';
 import type { Call, ListOptions } from '../types.js';
+import { type TaxDisplayPolicyModule } from './display-policy.js';
 /**
  * The mapping used when no mapping names the country the money is taxed in.
  *
@@ -187,6 +188,8 @@ export interface TaxModule {
     categories: TaxCategoriesModule;
     /** The platform-wide tax rates every store shares. */
     rates: TaxRatesModule;
+    /** Who the store shows prices with or without tax, saved or previewed. */
+    displayPolicy: TaxDisplayPolicyModule;
 }
 /** A {@link TaxCategory} as every read and write answers it (`platform.tax` reuses it). */
 export declare const TAX_CATEGORY_FIELDS = "\n  id\n  name\n  isDefault\n  createdAt\n  updatedAt\n";

package/dist/tax/index.js

@@ -1,5 +1,6 @@
 import { createPage } from '@sixtyninecommerce/core';
 import { vendureListPage } from '../catalog/types.js';
+import { createTaxDisplayPolicyModule } from './display-policy.js';
 /**
  * The mapping used when no mapping names the country the money is taxed in.
  *
@@ -100,6 +101,7 @@ export const REMOVE_TAX_CLASS_MAPPING_MUTATION = /* GraphQL */ `
 `;
 export function createTaxModule(transport) {
     return {
+        displayPolicy: createTaxDisplayPolicyModule(transport),
         classes: {
             async list(options) {
                 const data = await transport.graphql({ api: 'admin', query: TAX_CLASSES_QUERY }, options);