Store Settings

Code

<ShippingSettings zones={zones} pickups={pickups} currency="USD" onSaveZone={async (z) => api.saveZone(z)} /><TaxSettings rates={rates} currency="USD" onSave={async (r) => api.saveTax(r)} /><DiscountsManager discounts={discounts} currency="USD" products={products} onSave={async (d) => api.saveDiscount(d)} /><GiftCardsManager cards={cards} currency="USD" onIssue={async (c) => api.createCard(c)} onUpdate={async (c) => api.saveCard(c)} />

Store Admin · beta

Live examples and controls: Store Settings in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/store-settings.json

The screens a merchant uses to set up how the store charges: shipping zones with flat, by-weight, by-price and free-over rates plus local pickup; tax rates that are inclusive or exclusive; discounts (automatic or by code, percentage, fixed, buy X get Y, free shipping) with a basket simulator; and gift cards with issue, balance, history and redeem. Money is integer minor units and tax rates are basis points, so nothing rounds through a float. The components hold no data and call no API: you pass records and save in on* callbacks. The same pure functions run on your server at checkout.

When to useCopy Anchor Link

• A store back office settings area.
• Checkout, for GiftCardField and the pure functions (resolveShippingOptions, evaluateDiscounts, orderTax, applyGiftCards).

When not to useCopy Anchor Link

• Showing shipping or discounts to shoppers: use store-cart and store-checkout.
• Product prices and stock: use store-products-admin.

ImportCopy Anchor Link

import { ShippingSettings, TaxSettings, DiscountsManager, GiftCardsManager, GiftCardField, evaluateDiscounts } from "@fadymondy/nasaq/web";

Quick startCopy Anchor Link

<ShippingSettings zones={zones} pickups={pickups} currency="USD" onSaveZone={async (z) => api.saveZone(z)} />
<TaxSettings rates={rates} currency="USD" onSave={async (r) => api.saveTax(r)} />
<DiscountsManager discounts={discounts} currency="USD" products={products} onSave={async (d) => api.saveDiscount(d)} />
<GiftCardsManager cards={cards} currency="USD" onIssue={async (c) => api.createCard(c)} onUpdate={async (c) => api.saveCard(c)} />

AnatomyCopy Anchor Link

ShippingSettings  [data-slot=shipping-settings]  zone cards, zone editor with rate and tier editors, pickup points, destination tester
TaxSettings       [data-slot=tax-settings]       DataTable, editor dialog, calculator
DiscountsManager  [data-slot=discounts-manager]  DataTable, editor dialog, DiscountSimulator [data-slot=discount-simulator]
GiftCardsManager  [data-slot=gift-cards-manager] DataTable, issue dialog, detail sheet with ledger
GiftCardField     [data-slot=gift-card-field]    checkout box with card chips

APICopy Anchor Link

ShippingSettingsCopy Anchor Link

Rate types: flat, weight (tiers in grams), price (tiers on the order price), free-over (with an optional charge below the threshold). Zones that share a country are flagged: the first wins.

TaxSettingsCopy Anchor Link

TaxSettings({ rates, currency, onSave, onDelete, loading, error, onRetry, labels }). A TaxRate is { id, name, country, region?, bps, inclusive, onShipping?, active? }. bps 1400 is 14%. Inclusive rates split the tax out of the price; exclusive rates add it. Tax is computed once per order with orderTax.

DiscountsManagerCopy Anchor Link

evaluateDiscounts(discounts, { lines, shipping, codes, now, customer }) returns applied, rejected with a reason, the totals after discounts and the shipping discount. Discounts of one kind never stack. Percentages are basis points and shares are split with allocateDiscount, so the parts always add up to the whole.

GiftCardsManagerCopy Anchor Link

GiftCardsManager({ cards, currency, now, onIssue, onUpdate, actor, loading, error, onRetry, labels }). Cards hold a ledger; the balance is its sum, never stored. Redeem, adjust and disable call onUpdate with the card and its new entry.

GiftCardFieldCopy Anchor Link

GiftCardField({ cards, total, currency, onLookup, onCardsChange, onChange, now, disabled, labels }). Codes are checked for shape and check character before onLookup is called. The card that expires first is spent first.

Logic (pure, also exported)Copy Anchor Link

Shipping: zoneFor, rateFor, resolveShippingOptions, cheapestDelivery, toCommerceShippingMethods, tierIssues, overlappingCountries. Tax: taxRateFor, splitTax, orderTax, duplicateTaxRegions. Discounts: evaluateDiscounts (also allocateDiscount, percentOf, canCombine, discountStanding, discountRejection). Gift cards: issueGiftCard, redeemGiftCard, refundToGiftCard, adjustGiftCard, applyGiftCards, giftCardBalance, giftCardStatus, generateGiftCardCode, isValidGiftCardCode, ledgerIssues.

ExamplesCopy Anchor Link

const result = evaluateDiscounts(discounts, {
  lines: [{ id: "a", productId: "p1", unitPrice: 25000, quantity: 3 }],
  shipping: 5000,
  codes: ["SUMMER10"],
  now: new Date(),
});
result.goodsAfter + result.shippingAfter; // what the customer pays, in minor units

AccessibilityCopy Anchor Link

Results in the simulator, tester and checkout box are live regions. Errors are tied to their field. Every icon-only button has a label.

RTL & i18nCopy Anchor Link

English and Arabic built in through useOptionalNasaq(). Codes, SKUs, prices and numbers stay LTR inside dir="ltr" or <bdi>. Country names use Intl.DisplayNames in the page language.

Styling & tokensCopy Anchor Link

Uses --nq-* tokens only. Target the data-slot names above.

Do / Don'tCopy Anchor Link

• Do keep money in minor units and tax in basis points.
• Do run evaluateDiscounts, orderTax and resolveShippingOptions again on the server.
• Don't store a gift card balance: derive it from the ledger.

RelatedCopy Anchor Link

• store-products-admin
• store-checkout
• data-table

LabCopy Anchor Link

https://docs.nasaqui.com/?path=/docs/components-store-admin-store-settings--docs