---
title: "Update Group"
method: PATCH
path: "/api/v1/groups/{group_id}"
tags: ["Groups"]
---

# Update Group

`PATCH /api/v1/groups/{group_id}`

Updates a group's name, adds websites, removes websites, and/or (partners only) sets or clears the `external_id` mapping. At least one field must be provided. Requires a global API key. **Partner integrations** may pass `external_id` as a non-empty string to set/replace the mapping, or as `null` to clear it.

## Request body

- UpdateGroupRequest — Request body for updating a group. At least one field must be provided.
  - `name` string — New name for the group.
  - `add_website_ids` string[] — Website IDs to add to the group. Must belong to your organization. Websites already in the group are silently ignored.
  - `remove_website_ids` string[] — Website IDs to remove from the group. IDs not currently in the group are silently ignored.
  - `external_id` string, nullable — **Partner-only.** Partner-supplied identifier to attach to this group. Pass a non-empty string to set or replace the mapping, or `null` to clear an existing mapping. Accepted only when authenticating with an API key for an organization flagged as a partner. Sending this field as a direct customer returns `403 Forbidden`. Must be unique per resource type within your organization — setting a value already used by another group returns `409` with the existing resource in the payload.
  - `billing_enabled` boolean — Set to `true` to enable billing for this group. This provisions a billing entity in the upstream billing provider, which is a prerequisite for setting credits on the group (a partner-only operation). Idempotent — safe to call on groups whose entity was never created or whose initial provisioning failed silently. Set to `false` to disable the flag without destroying existing billing state; credit balances and usage history are preserved. Returns `502` if the upstream billing provider fails to provision the entity — in that case the database is not modified, so the request can be retried cleanly.

## Response `200`

Group updated successfully. Partner responses include an `externalId` field (string or `null`); direct-customer responses omit the field entirely.

- object
  - `group` Group, required — A group of websites in your organization
    - `id` string, uuid, required — Unique identifier for the group
    - `name` string, required — Display name of the group
    - `orgId` string, uuid, required — The organization ID the group belongs to
    - `billingEnabled` boolean, required — Whether billing is enabled for this group
    - `createdAt` string, date-time, required — Timestamp when the group was created (UTC)
    - `websites` GroupWebsite[], required — Websites associated with this group
      - `id` string, uuid, required — Unique identifier for the website
      - `websiteUrl` string, required — The URL of the website
      - `websiteName` string, required — Display name of the website
    - `externalId` string, nullable — **Partner-only.** The partner-supplied identifier mapped to this group. Only present on responses to callers whose organization is flagged as a partner. Direct-customer responses omit the field entirely. `null` indicates no mapping exists for this group.

## Other responses

- `400` — Bad request - Validation error or invalid website IDs
- `401` — Unauthorized - Invalid or missing API key
- `403` — Forbidden - Requires a global API key, or (partner-only field) the key lacks partner identity for an `external_id`.
- `404` — Not found - Group does not exist or does not belong to your organization
- `409` — Conflict - (partners only) the supplied `external_id` is already mapped to another group.
- `500` — Internal server error
- `502` — Upstream billing provider failed to provision the billing entity. Only returned when `billing_enabled: true` is in the request body. No database changes were committed — the request can be retried cleanly.

---

[API](https://skmtc.net/athenahq/apis/athenahq-api.md) · [All operations](https://skmtc.net/athenahq/apis/athenahq-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/athenahq/athenahq-api/versions/6c5d71622cb9/schema)