> ## Documentation Index > Fetch the complete documentation index at: https://docs.dittofeed.com/llms.txt > Use this file to discover all available pages before exploring further. # Custom Subscription Management Page > Serve a self-contained subscription management page with custom templates. ## Introduction Dittofeed provides a self-contained subscription management page that can be served directly from the API. This is useful for deployments where you only expose `/api/public/*` endpoints (e.g., Kubernetes ingress configurations that don't expose the dashboard's static assets). The page is served from `/api/public/subscription-management/page` and includes all CSS and JavaScript inline, requiring no external dependencies. ## Self-Contained Page Endpoint ### Endpoint ``` GET /api/public/subscription-management/page ``` ### Query Parameters | Parameter | Required | Description | | ----------- | -------- | -------------------------------------------------------------- | | `w` | Yes | Workspace ID | | `i` | Yes | User identifier value | | `ik` | Yes | Identifier key (e.g., `email`, `userId`) | | `h` | Yes | Cryptographic hash for authentication | | `s` | No | Subscription group ID (for single subscription change on load) | | `sub` | No | Subscription action: `1` to subscribe, `0` to unsubscribe | | `isPreview` | No | Set to `true` to preview the page without making changes | ### Response The endpoint returns a complete HTML page (`Content-Type: text/html`) with: * Inline CSS for styling * Inline JavaScript for interactivity * Server-rendered subscription data ### Example URL ``` /api/public/subscription-management/page?w=workspace-id&i=user@example.com&ik=email&h=hash-value ``` ## Custom Templates You can customize the subscription management page by uploading a custom Liquid template via the admin API. ### Template API Endpoints #### Get Current Template ``` GET /api/subscription-management-template ``` Returns the current custom template, or `null` if using the default. #### Upsert Template ``` PUT /api/subscription-management-template Content-Type: application/json { "template": "... your Liquid template ..." } ``` #### Delete Template (Reset to Default) ``` DELETE /api/subscription-management-template ``` Removes the custom template, reverting to the default. ## Template Variables Your Liquid template has access to the following variables: | Variable | Type | Description | | ---------------------------- | ------- | ----------------------------------------------------- | | `workspaceName` | string | Name of the workspace | | `channels` | array | Array of channel objects | | `subscriptionChange` | string | `"Subscribe"` or `"Unsubscribe"` if a change occurred | | `changedSubscriptionName` | string | Name of the subscription that changed | | `changedSubscriptionChannel` | string | Channel of the subscription that changed | | `isPreview` | boolean | Whether this is a preview render | | `subscriptionDataJson` | string | JSON data for JavaScript initialization | ### Channel Object ```json theme={null} { "name": "Email", "subscriptions": [ { "id": "subscription-uuid", "name": "Marketing Updates", "isSubscribed": true } ] } ``` ## Custom Liquid Tags ### `subscription_hidden_fields` The `subscription_hidden_fields` tag is a custom Liquid tag available only in subscription management page templates. It renders the hidden form fields required for form submission authentication. ```html theme={null} {% subscription_hidden_fields %} ``` This tag is **required** in your custom template for form submissions to work. Place it inside your `

` element. The tag renders: ```html theme={null} ``` Without this tag, the form cannot authenticate the user or identify which workspace the submission belongs to. ## CSS Class API The JavaScript behavior attaches to specific CSS classes. Your custom template must include elements with these classes for the interactive features to work. ### Required Classes | Class | Element | Description | | -------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------- | | `df-subscription-form` | `` | Main form container. Handles form submission. | | `df-subscription-checkbox` | `` | Individual subscription checkboxes. Requires `data-subscription-id` and `data-channel` attributes. | | `df-channel-toggle` | `` | Channel-level toggle. Requires `data-channel` attribute. Toggles all subscriptions in the channel. | | `df-save-button` | `

``` ## JavaScript Behavior The page automatically initializes subscription data from `window.__SUBSCRIPTION_DATA__`. Your template should include this at the bottom of the body: ```html theme={null} ``` The injected JavaScript handles: 1. **Channel Toggle Logic**: When a channel toggle is checked/unchecked, all subscriptions in that channel are updated accordingly. 2. **Individual Subscription Logic**: When an individual subscription is toggled, the channel toggle is updated (checked if all subscriptions are checked, unchecked otherwise). 3. **Save Functionality**: Clicking the save button or submitting the form sends a PUT request to `/api/public/subscription-management/user-subscriptions` with the updated subscription states. 4. **UI Feedback**: Loading, success, and error indicators are shown/hidden automatically during the save process. ## Default Template Reference Below is the default template that Dittofeed uses when no custom template is configured. You can use this as a starting point for your own customizations: ```liquid theme={null} Subscription Preferences - {{ workspaceName }}

{% if subscriptionChange %} {% if subscriptionChange == "Subscribe" %} You have subscribed to {{ changedSubscriptionChannel }} from {{ workspaceName }} {% else %} You have unsubscribed from {{ changedSubscriptionChannel }} from {{ workspaceName }} {% endif %} {% else %} Manage your preferences for {{ workspaceName }} {% endif %}

Manage your communication preferences below

{% subscription_hidden_fields %}

{% if success %}

Preferences saved successfully!

{% endif %} {% if previewSubmitted %}

Preview: Subscription preferences would be updated.

{% endif %} {% if error %}

Failed to save preferences. Please try again.

{% endif %}

Communication Channels

{% for channel in channels %}

{% for subscription in channel.subscriptions %} {{ subscription.name }} {% endfor %}

{% endfor %}

``` ## Example Custom Template Below is a simpler custom template example that you can use as a starting point: ```liquid theme={null} Email Preferences - {{ workspaceName }}

Email Preferences

Manage your subscription preferences for {{ workspaceName }}.

{% if subscriptionChange %}

{% if subscriptionChange == "Subscribe" %} You have subscribed to {{ changedSubscriptionName }}. {% else %} You have unsubscribed from all {{ changedSubscriptionChannel }} messages. {% endif %}

{% endif %}

``` ## Use Cases ### Kubernetes Ingress Restriction If your Kubernetes ingress only exposes `/api/public/*` paths, you can use the self-contained page endpoint instead of the default dashboard page: ```yaml theme={null} # Example ingress configuration apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: dittofeed-public spec: rules: - http: paths: - path: /api/public pathType: Prefix backend: service: name: dittofeed-api port: number: 3001 ``` Users accessing `/api/public/subscription-management/page` will receive a fully functional subscription management page without requiring access to dashboard static assets. ### Branded Subscription Pages Use custom templates to match your brand: * Custom colors and typography * Your company logo * Custom messaging and copy * Localized content ### Simplified UI Create minimal templates that only show essential options, removing unnecessary complexity for your users.