Dynamic Link Module — Storefront

HTTP surface for reading dynamic link groups by slug. Dynamic link groups are CMS-style ordered collections of {image, text, url} cards — used for the storefront home grid, promo…

HTTP surface for reading dynamic link groups by slug. Dynamic link groups are CMS-style ordered collections of {image, text, url} cards — used for the storefront home grid, promo tiles, "explore" rows, and any other content slot whose layout is data-driven rather than hard-coded.

Source: api-modules/dynamic-link/src/controllers/public-dynamic-link-group.controller.ts.

Admin CRUD for groups and links is in docs/separated/admin/dynamic-link.md. The storefront uses one read endpoint to fetch a group + its ordered links in a single call.

Conventions

Authentication

Endpoint	Auth
`GET /store/dynamic-link-groups/slug/:slug`	none (public)

Dynamic links are public marketing content — no session, no PII.

Response envelope

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

Error envelope

`statusCode`	`errorCode` examples
404	`NOT_FOUND`
500	`INTERNAL_SERVER_ERROR`, `DATABASE_ERROR`

Domain types

`DynamicLinkResponse`

type DynamicLinkResponse = {
  id: string;
  groupId: string;
  image: string | null;                // storage key — resolve via storage CDN
  url: string | null;                  // click destination
  text: string | null;                 // caption / label
  order: number;                       // sort key — links are emitted in ASC order
  metadata: Record<string, unknown> | null;
  createdAt: string;                   // ISO
  updatedAt: string;                   // ISO
};

`DynamicLinkGroupWithLinksResponse`

type DynamicLinkGroupWithLinksResponse = {
  id: string;
  title: string;
  slug: string;                        // lowercase alnum + hyphens, e.g. "home-grid"
  metadata: Record<string, unknown> | null;
  createdAt: string;                   // ISO
  updatedAt: string;                   // ISO
  links: DynamicLinkResponse[];        // sorted by `order` ASC
};

Endpoints

`GET /store/dynamic-link-groups/slug/:slug` — Fetch a group with its links

Returns the group plus its nested links array, sorted by order ASC. Used by the storefront to populate a named content slot in a single round-trip.

Path params

Name	Notes
`slug`	Group slug (lowercase alnum + hyphens)

Response 200 — DynamicLinkGroupWithLinksResponse.

{
  "data": {
    "id": "01J9...",
    "title": "Home Grid",
    "slug": "home-grid",
    "metadata": null,
    "createdAt": "2026-04-01T08:00:00.000Z",
    "updatedAt": "2026-05-01T08:00:00.000Z",
    "links": [
      {
        "id": "01J9...",
        "groupId": "01J9...",
        "image": "dlinks/2026-05/promo-1.jpg",
        "url": "/sale",
        "text": "Summer Sale",
        "order": 0,
        "metadata": null,
        "createdAt": "2026-05-01T08:00:00.000Z",
        "updatedAt": "2026-05-01T08:00:00.000Z"
      }
    ]
  },
  "message": "Success",
  "statusCode": 200
}

Errors

Status	Code	When
404	`NOT_FOUND`	No group matches the slug

storage — resolves image keys to CDN URLs on the client.
banner — adjacent CMS surface for taxonomy-pinned promotional banners. See banner.md.

Dynamic Link Module — Storefront

On this page