Serviceability Module — Storefront

Ask whether the store delivers to a pincode before the shopper commits to it. Returns the operator's own message plus whether it is a soft warning or a hard block, so the PDP pincode box and the checkout address step can render either.

Source: api-modules/serviceability/src/controllers/store-serviceability.controller.ts.

This is an optional plugin. When ServiceabilityModule.forRoot() is removed from app.module.ts this route disappears, the cart stops carrying a serviceability field, and every pincode is deliverable. The operator surface is documented in Serviceability — Admin.

Conventions

Authentication

Public — no session required. It runs on the product page and in the guest checkout address step, both of which happen before a session may exist, and it discloses nothing beyond the operator's delivery policy for a pincode the caller already typed.

Response envelope

{ "data": <payload>, "message": "Success", "statusCode": 200 }

Endpoints

GET /store/serviceability/check — Can we deliver here?

Response 200:

type ServiceabilityCheck = {
  pincode: string;
  status: "allowed" | "inform" | "block";
  deliverable: boolean;    // true for allowed and inform
  message: string | null;  // null when allowed
};

deliverable is the single boolean to gate the "Place order" button on; status is there when the UI wants to distinguish a warning from an error.

Checkout integration

Once the shopper has picked a delivery address, the cart carries the verdict itself, so the checkout page does not need a second call:

// GET /store/cart, POST /store/cart/prepare-checkout
type CartResponse = {
  // …
  deliveryAddress: Address | null;
  serviceability: {
    pincode: string;
    status: "allowed" | "inform" | "block";
    deliverable: boolean;
    message: string | null;
  } | null;
};

serviceability is null when no delivery address is picked (use GET /store/serviceability/check for the pincode box then) or when the plugin is not installed. It is computed fresh on every cart read — never cached — so an operator adding a pincode takes effect on the shopper's next request.

The advisory never fails a cart read: a blocked pincode still returns the full priced cart so the shopper can see and edit their bag. The refusal lands at placement.

POST /store/orders with a blocked pincode

{
  "data": null,
  "message": "We don't deliver to 110001 yet",
  "statusCode": 400,
  "errorCode": "PINCODE_NOT_SERVICEABLE",
  "details": { "pincode": "110001" }
}

message is the operator's own copy from the rule, so it can be surfaced verbatim. This applies to both the signed-in and the guest checkout path — guest addresses are checked the same way once captured. A pincode in inform mode never produces this error.