Tax Module — Admin

HTTP surface for the platform-admin override of any vendor's flat-tax config — the list of tax lines (e.g. { type: "GST", rate: 18 }) that the flat tax provider applies to that vendor's bag at pricing time.

Source: api-modules/tax-flat/src/controllers/admin-vendor-tax-config.controller.ts.

The flat tax provider is one implementation of the tax port; other providers (jurisdictional, HSN-driven) can be plugged in via the same port and would carry their own admin endpoint. This doc covers the flat provider only — the only one shipped today.

Conventions

Authentication

All endpoints require a Better-Auth admin session and a role granting the matching permission. Reuses the platformVendorSetting resource — semantically the same action as the platform-vendor settings override surface in settings.md.

Response envelope

Successful responses are wrapped by ResponseInterceptor:

{
  "data": <payload>,
  "message": "Success",
  "statusCode": 200,
  "metadata": { /* optional, e.g. pagination */ }
}

Error envelope

Domain types

TaxConfigLine

type TaxConfigLine = {
  type: string;                       // 1..50, trimmed (e.g. "GST", "VAT")
  rate: number;                       // 0..100 — whole or decimal percent
};

FlatTaxConfigResponse

type FlatTaxConfigResponse = { taxes: TaxConfigLine[] };

Endpoints

GET /admin/vendors/:vendorId/tax/config — Get tax config for a target vendor

Required permission: platformVendorSetting: read.

Path params

Response 200 — FlatTaxConfigResponse.

PATCH /admin/vendors/:vendorId/tax/config — Override tax config

Required permission: platformVendorSetting: update. Bypasses any forAdmin guard on the underlying vendor settings. Sending taxes: [] explicitly clears the list; omitting taxes leaves the current list intact.

Body

{
  "taxes": [
    { "type": "GST", "rate": 18 },
    { "type": "Cess", "rate": 1.5 }
  ]
}

The body is strict() — unknown keys are rejected.

Response 200 — updated FlatTaxConfigResponse.

Errors

Related modules

• admin-rbac — gates every endpoint via platformVendorSetting:*. See admin-rbac.md.
• settings — same platformVendorSetting resource; tax config is stored as a group inside the vendor-settings store. See settings.md.
• tax — exposes the taxConfigLineSchema consumed by the flat provider and any future provider with similar input shape.
• cart — applies the resolved tax lines at quote time.
• order — snapshots the applied tax breakdown into order totals at place-order. See order.md.