Distribution CRUD

Workspace-scoped CRUD endpoints for managing distributions from the dashboard. A distribution is the configuration behind a public landing page (or API integration) that issues wallet passes — its template, project, page address, landing/email HTML, and form-field config.

These endpoints are mounted by the generic collection-CRUD mounter, so they follow a uniform shape: list/create are scoped under /workspace/:workspaceId, while get/update/delete operate on a distribution by :id. All are mounted under the /wallethero-api prefix. Base URL: https://api.wallethero.app.

Auth model: All five endpoints require a Bearer token. list and create are guarded by workspace membership via the :workspaceId path. The :id endpoints (get, update, delete) are entity-guarded — the caller must be a member of the workspace that owns the distribution (resolved from the row's workspace_id).

List Distributions

GET /wallethero-api/workspace/:workspaceId/distributions

Lists all distributions belonging to a workspace, sorted by creation date (newest first). Returns every matching row (no pagination).

Auth: Bearer token — workspace member (path-guarded on :workspaceId).

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier.

Example Request

bash

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/distributions" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

json

{
  "data": [
    {
      "id": "b7f0c9d2-1a3e-4c8b-9f2d-7e6a5c4b3a21",
      "workspace_id": "a1b2c3d4-0000-0000-0000-000000000001",
      "project_id": "c3d4e5f6-0000-0000-0000-000000000002",
      "pass_template_id": "d4e5f6a7-0000-0000-0000-000000000003",
      "name": "Spring Loyalty Campaign",
      "status": "published",
      "page_address": "spring-loyalty",
      "mode": "landing_page",
      "delivery_mode": "email",
      "date_created": "2026-05-01T09:00:00.000Z"
    }
  ]
}

SDK

typescript

const result = await wh.distributions.list({
  filter: { workspace_id: { _eq: workspaceId } },
});
// Or, equivalently:
const result = await wh.distributions.getByWorkspace(workspaceId);

list requires the workspace to be supplied via filter.workspace_id._eq — cross-workspace listing is not supported.

Get Distribution

GET /wallethero-api/distributions/:id

Fetches a single distribution by its ID, including all fields.

Auth: Bearer token — workspace member (entity-guarded; the caller must belong to the distribution's workspace_id). Returns 404 (distributions not found) if the ID does not exist.

Path Parameters

Parameter	Type	Description
`id`	`string (UUID)`	Distribution identifier.

Example Request

bash

curl "https://api.wallethero.app/wallethero-api/distributions/DISTRIBUTION_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

json

{
  "data": {
    "id": "b7f0c9d2-1a3e-4c8b-9f2d-7e6a5c4b3a21",
    "workspace_id": "a1b2c3d4-0000-0000-0000-000000000001",
    "project_id": "c3d4e5f6-0000-0000-0000-000000000002",
    "pass_template_id": "d4e5f6a7-0000-0000-0000-000000000003",
    "name": "Spring Loyalty Campaign",
    "status": "published",
    "page_address": "spring-loyalty",
    "landing_html": "<form>...</form>",
    "landing_html_success": "<p>Check your email!</p>",
    "email_html": "<p>Your pass is ready.</p>",
    "email_reply_to": "[email protected]",
    "email_topic": "Your Acme pass",
    "email_background_color": "#ffffff",
    "css": ".form { max-width: 480px; }",
    "form_fields_config": {
      "marketing_consent": { "enabled": true, "required": false }
    },
    "setup_config": {},
    "mode": "landing_page",
    "delivery_mode": "email",
    "api_token_prefix": "whd_ab12",
    "allowed_origins": ["https://acme.example"],
    "date_created": "2026-05-01T09:00:00.000Z",
    "date_updated": "2026-05-02T10:30:00.000Z"
  }
}

SDK

typescript

const result = await wh.distributions.get(distributionId);

Create Distribution

POST /wallethero-api/workspace/:workspaceId/distributions

Creates a new distribution in the given workspace. The workspace_id is taken from the path and applied server-side (any workspace_id in the body is overridden), and user_created is set from the authenticated caller. Returns the created distribution.

Auth: Bearer token — workspace member (path-guarded on :workspaceId).

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace the distribution is created in. Overrides any `workspace_id` sent in the body.

Request Body

All fields except the server-managed ones (id, user_created, date_created, user_updated, date_updated) may be supplied. The SDK's CreateDistributionRequest type expects the distribution's core relations.

Field	Type	Required	Description
`project_id`	`string (UUID)`	Yes	Project the distribution belongs to.
`pass_template_id`	`string (UUID)`	Yes	Pass template issued to enrollees.
`status`	`"draft" \| "published"`	Yes	Lifecycle status. New distributions are typically created as `draft`.
`name`	`string`	No	Human-readable name.
`page_address`	`string`	No	Public page slug (used by the landing-page submission flow).
`landing_html`	`string`	No	HTML for the landing/form page.
`landing_html_success`	`string`	No	HTML shown after a successful submission.
`email_html`	`string`	No	HTML body of the pass-delivery email.
`email_reply_to`	`string`	No	Reply-to address for delivery emails.
`email_topic`	`string`	No	Subject line of delivery emails.
`email_background_color`	`string \| null`	No	Background color for the email template.
`css`	`string`	No	Custom CSS for the landing form.
`setup_config`	`object`	No	Arbitrary setup/config blob.
`form_fields_config`	`object`	No	Which form fields to render and their options.
`mode`	`"landing_page" \| "api_integration"`	No	Distribution mode.
`delivery_mode`	`"email" \| "inline" \| "both"`	No	How the pass is delivered to the enrollee.
`allowed_origins`	`string[] \| null`	No	Origins permitted to embed/submit (for API integration mode).
`workspace_id`	`string (UUID)`	No	Ignored — set from the path.

Example Request

bash

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/distributions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "c3d4e5f6-0000-0000-0000-000000000002",
    "pass_template_id": "d4e5f6a7-0000-0000-0000-000000000003",
    "name": "Spring Loyalty Campaign",
    "status": "draft",
    "page_address": "spring-loyalty",
    "mode": "landing_page",
    "delivery_mode": "email"
  }'

Response (201)

json

{
  "data": {
    "id": "b7f0c9d2-1a3e-4c8b-9f2d-7e6a5c4b3a21",
    "workspace_id": "a1b2c3d4-0000-0000-0000-000000000001",
    "project_id": "c3d4e5f6-0000-0000-0000-000000000002",
    "pass_template_id": "d4e5f6a7-0000-0000-0000-000000000003",
    "name": "Spring Loyalty Campaign",
    "status": "draft",
    "page_address": "spring-loyalty",
    "mode": "landing_page",
    "delivery_mode": "email",
    "date_created": "2026-06-16T12:00:00.000Z"
  }
}

SDK

typescript

const result = await wh.distributions.create({
  workspace_id: workspaceId, // required by the SDK to route the request
  project_id: "c3d4e5f6-0000-0000-0000-000000000002",
  pass_template_id: "d4e5f6a7-0000-0000-0000-000000000003",
  name: "Spring Loyalty Campaign",
  status: "draft",
});

The SDK reads workspace_id from the request data to build the URL, then the server re-applies it from the path. They must refer to the same workspace.

Update Distribution

PATCH /wallethero-api/distributions/:id

Updates an existing distribution. Only the supplied fields are changed (partial update). user_updated is set from the authenticated caller. Returns the updated distribution.

Server-managed columns sent in the body are silently stripped and cannot be changed via this endpoint: workspace_id (a distribution cannot be moved between workspaces), id, user_created, date_created, and date_updated.

Auth: Bearer token — workspace member (entity-guarded; the caller must belong to the distribution's workspace_id). Returns 404 if the ID does not exist.

Path Parameters

Parameter	Type	Description
`id`	`string (UUID)`	Distribution identifier.

Request Body

Any subset of the create fields (see Create Distribution) except the stripped server-managed columns above. The SDK's UpdateDistributionRequest is a Partial of the distribution.

Field	Type	Required	Description
`status`	`"draft" \| "published"`	No	Publish/unpublish the distribution.
`name`	`string`	No	Updated name.
`landing_html`	`string`	No	Updated landing HTML.
`...`	—	No	Any other writable distribution field.

Example Request

bash

curl -X PATCH "https://api.wallethero.app/wallethero-api/distributions/DISTRIBUTION_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "published" }'

Response (200)

json

{
  "data": {
    "id": "b7f0c9d2-1a3e-4c8b-9f2d-7e6a5c4b3a21",
    "workspace_id": "a1b2c3d4-0000-0000-0000-000000000001",
    "status": "published",
    "name": "Spring Loyalty Campaign",
    "date_updated": "2026-06-16T12:05:00.000Z"
  }
}

SDK

typescript

const result = await wh.distributions.update(distributionId, {
  status: "published",
});

// Convenience wrappers:
await wh.distributions.publish(distributionId);   // status: "published"
await wh.distributions.unpublish(distributionId); // status: "draft"

Delete Distribution

DELETE /wallethero-api/distributions/:id

Permanently deletes a distribution by its ID.

Auth: Bearer token — workspace member (entity-guarded; the caller must belong to the distribution's workspace_id). Returns 404 if the ID does not exist.

Path Parameters

Parameter	Type	Description
`id`	`string (UUID)`	Distribution identifier.

Example Request

bash

curl -X DELETE "https://api.wallethero.app/wallethero-api/distributions/DISTRIBUTION_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

json

{ "message": "distributions deleted" }

SDK

typescript

await wh.distributions.delete(distributionId);

Distribution CRUD ​

List Distributions ​

Path Parameters ​

Example Request ​

Response (200) ​

SDK ​

Get Distribution ​

Path Parameters ​

Example Request ​

Response (200) ​

SDK ​

Create Distribution ​

Path Parameters ​

Request Body ​

Example Request ​

Response (201) ​

SDK ​

Update Distribution ​

Path Parameters ​

Request Body ​

Example Request ​

Response (200) ​

SDK ​

Delete Distribution ​

Path Parameters ​

Example Request ​

Response (200) ​

SDK ​

Distribution CRUD

List Distributions

Path Parameters

Example Request

Response (200)

SDK

Get Distribution

Path Parameters

Example Request

Response (200)

SDK

Create Distribution

Path Parameters

Request Body

Example Request

Response (201)

SDK

Update Distribution

Path Parameters

Request Body

Example Request

Response (200)

SDK

Delete Distribution

Path Parameters

Example Request

Response (200)

SDK