Shipping Module

HTTP surface for the platform-admin override of any vendor's shipping config (enabled providers list + customer-charge flat-rate + free-shipping threshold). Vendor-self read/write…

HTTP surface for the platform-admin override of any vendor's shipping config (enabled providers list + customer-charge flat-rate + free-shipping threshold). Vendor-self read/write of the same config lives on the vendor side.

Source: api-modules/shipping/src/controllers/admin-shipping.controller.ts.

Shipping has two layers: a customer-charge layer (per-vendor flat rate, cart-side, plugin-free) and a provider layer (AWB / pickup, post-order, plugin-driven). This admin surface owns the customer-charge configuration; vendors pick the active provider per sub-order via the vendor-side fulfilment endpoints.

Conventions

Authentication

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

Endpoint	Permission
`GET /admin/vendors/:vendorId/shipping/config`	`platformVendorSetting: read`
`PATCH /admin/vendors/:vendorId/shipping/config`	`platformVendorSetting: update`

Response envelope

Successful responses are wrapped by ResponseInterceptor:

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

Error envelope

`statusCode`	`errorCode` examples
400	`BAD_REQUEST`, `VALIDATION_ERROR`
401	`UNAUTHORIZED`
403	`FORBIDDEN`
404	`NOT_FOUND`
500	`INTERNAL_SERVER_ERROR`, `DATABASE_ERROR`

Currency

flatRateSubunit and freeAboveSubunit are integer subunits (paise / cents).

Domain types

`ShippingConfigResponse`

type ShippingConfigResponse = {
  enabledProviders: string[];          // provider ids registered via the shipping plugin tokens
  flatRateSubunit: number;             // flat customer charge per vendor bag, in subunits
  freeAboveSubunit: number | null;     // bag subtotal at/above which shipping is free; null = always charge
};

Endpoints

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

Required permission: platformVendorSetting: read.

Path params

Name	Notes
`vendorId`	Target vendor id

Response 200 — ShippingConfigResponse.

`PATCH /admin/vendors/:vendorId/shipping/config` — Override config

Required permission: platformVendorSetting: update. Partial body — service maps to VendorSettingsService.setMany so unset keys are left untouched. Bypasses any forAdmin write guard on the underlying vendor-settings keys — platform staff can set any registered key.

Body

{
  "enabledProviders": ["self-handled", "clickpost"],
  "flatRateSubunit": 5000,                     // ₹50 in paise
  "freeAboveSubunit": 100000                   // free shipping at ≥ ₹1000 cart subtotal
}

Field	Type	Constraints
`enabledProviders`	`string[]?`	Non-empty when sent; each entry: registered provider id
`flatRateSubunit`	`int?`	`>= 0`
`freeAboveSubunit`	`int? \| null`	`>= 0` or explicit `null` to disable free-shipping

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

Response 200 — updated ShippingConfigResponse.

Errors

Status	Code	When
400	`VALIDATION_ERROR`	Body fails zod (unknown field, empty `enabledProviders` array, negative subunit)

admin-rbac — gates every endpoint via platformVendorSetting:*. See admin-rbac.md.
settings — same platformVendorSetting resource; shipping config is stored as a group inside the vendor-settings store. See settings.md.
shipping-self-handled, shipping-clickpost — provider plugins; enabledProviders[] references their registered ids.
cart — uses the customer-charge layer at quote time. See cart.md.
order — vendors pick the active provider at the pending→fulfilled transition; see order.md.

Shipping Module — Admin