Source: https://datafa.st/docs/api/account/goal-customizations/update
Markdown source: https://datafa.st/docs/api/account/goal-customizations/update.md
Description: Set display name, color, or description for one goal.

# Update goal customization

`PATCH https://datafa.st/api/v1/admin/websites/{websiteId}/goals/customizations`

Create or update display-only metadata for one tracked goal. This changes dashboard labels/colors, not the raw event name your tracker or API sends.

Send only fields you want to change. Pass `null` for `displayName`, `color`, or `description` to clear that one field.

> **Related:** [Custom goals](/docs/custom-goals)

## Request

#### Path parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `websiteId` | string | — | Website ObjectId. From [List websites](/docs/api/account/websites/list) (`_id` field). Example: `665f0b3c4d2e1a0012345678`. |

#### Body parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `goalName` | string | Yes | Goal name stored lowercase; spaces → `_`. Allowed: `a-z`, `0-9`, `_`, `-`, `:`. Max 64 chars. Reserved: `identify`. Example: `"newsletter_signup"`. See [custom goals](/docs/custom-goals). |
| `displayName` | string\|null | No | Display-only label used in dashboard charts, tooltips, and CLI output. It does not change the raw tracked goal name. Max 80 characters. Example: `"Signup started"`. |
| `color` | string\|null | No | Hex color from the allowed DataFast goal palette. Get options from [List goal customizations](/docs/api/account/goal-customizations/list) or `datafast goals colors`. Pass `null` to clear. Example: `"#8dcdff"`. |
| `description` | string\|null | No | Internal display description for your team. Not shown to end users and not used for tracking. Max 300 characters. Pass `null` to clear. |

#### Example request body

```json
{
  "goalName": "signup_started",
  "displayName": "Signup started",
  "color": "#8dcdff",
  "description": "Visitor opened the signup flow"
}
```

## Response

Returns a JSON object with `status: "success"` and endpoint-specific fields in `data`.

#### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `data[].goalName` | string | Raw tracked goal name. |
| `data[].displayName` | string\|null | Custom display name. |
| `data[].color` | string\|null | Custom chart color. |
| `data[].description` | string\|null | Internal custom description. |
| `data[].updatedAt` | string\|null | Last update timestamp. |
| `colors[]` | object[] | Allowed color palette returned by list requests. |
| `colors[].color` | string | Allowed hex color. |
| `colors[].label` | string | Human-readable color label. |
| `colors[].family` | string | Color family used to avoid similar defaults. |

### Authentication

Use a `dft_` account token with `goals:write`.

A `df_` website API key for the same website can also call this route when the path `websiteId` matches the key's website. Write access with a `df_` key is capped at **member** level — owner-only actions such as [team management](/docs/api/account/team) require a `dft_` token and owner role.

### Errors

**400** — Invalid goal name, color not in the allowed palette, no fields provided, or text fields too long.

**413** — Request body is larger than 4 KB.

See [API errors](/docs/api#errors) for the standard error envelope, auth failures, validation errors, permission errors, and rate limits.

## Code examples

### Example request

```bash
curl -X PATCH "https://datafa.st/api/v1/admin/websites/{websiteId}/goals/customizations" \
  -H "Authorization: Bearer dft_xxx" \
  -H "Content-Type: application/json" \
  -d '{"goalName":"signup_started","displayName":"Signup started","color":"#8dcdff"}'
```

### Success response

```json
{
  "status": "success",
  "data": [{
    "goalName": "signup_started",
    "displayName": "Signup started",
    "color": "#8dcdff",
    "description": "Visitor opened the signup flow",
    "updatedAt": "2026-05-21T00:00:00.000Z"
  }],
  "colors": [
    { "color": "#ef4444", "family": "red", "label": "Red" },
    { "color": "#8dcdff", "family": "blue", "label": "Sky" }
  ]
}
```