---
title: "Update Benefit"
method: PATCH
path: "/v1/benefits/{id}"
tags: ["benefits", "public"]
---

# Update Benefit

`PATCH /v1/benefits/{id}`

Update a benefit.

**Scopes**: `benefits:write`

## Path parameters

- `id` string, uuid4, required — The benefit ID.

## Request body

- union
  - BenefitCustomUpdate
    - `metadata` object — Key-value object allowing you to store additional information. The key must be a string with a maximum length of **40 characters**. The value must be either: * A string with a maximum length of **500 characters** * An integer * A floating-point number * A boolean You can store up to **50 key-value pairs**.
    - `description` string, nullable — The description of the benefit. Will be displayed on products having this benefit.
    - `visibility` 'draft' | 'private' | 'public'
    - `type` 'custom', required
    - `properties` BenefitCustomProperties — Properties for a benefit of type `custom`.
      - `note` string, nullable, required
  - BenefitDiscordUpdate
    - `metadata` object — Key-value object allowing you to store additional information. The key must be a string with a maximum length of **40 characters**. The value must be either: * A string with a maximum length of **500 characters** * An integer * A floating-point number * A boolean You can store up to **50 key-value pairs**.
    - `description` string, nullable — The description of the benefit. Will be displayed on products having this benefit.
    - `type` 'discord', required
    - `properties` BenefitDiscordCreateProperties — Properties to create a benefit of type `discord`.
      - `guild_token` string, required
      - `role_id` string, required — The ID of the Discord role to grant.
      - `kick_member` boolean, required — Whether to kick the member from the Discord server on revocation.
  - BenefitGitHubRepositoryUpdate
    - `metadata` object — Key-value object allowing you to store additional information. The key must be a string with a maximum length of **40 characters**. The value must be either: * A string with a maximum length of **500 characters** * An integer * A floating-point number * A boolean You can store up to **50 key-value pairs**.
    - `description` string, nullable — The description of the benefit. Will be displayed on products having this benefit.
    - `type` 'github_repository', required
    - `properties` BenefitGitHubRepositoryCreateProperties — Properties to create a benefit of type `github_repository`.
      - `repository_owner` string, required — The owner of the repository.
      - `repository_name` string, required — The name of the repository.
      - `permission` 'pull' | 'triage' | 'push' | 'maintain' | 'admin', required — The permission level to grant. Read more about roles and their permissions on [GitHub documentation](https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization#permissions-for-each-role).
  - BenefitDownloadablesUpdate
    - `metadata` object — Key-value object allowing you to store additional information. The key must be a string with a maximum length of **40 characters**. The value must be either: * A string with a maximum length of **500 characters** * An integer * A floating-point number * A boolean You can store up to **50 key-value pairs**.
    - `description` string, nullable — The description of the benefit. Will be displayed on products having this benefit.
    - `type` 'downloadables', required
    - `properties` BenefitDownloadablesCreateProperties
      - `archived` object
      - `files` string[], required
  - BenefitLicenseKeysUpdate
    - `metadata` object — Key-value object allowing you to store additional information. The key must be a string with a maximum length of **40 characters**. The value must be either: * A string with a maximum length of **500 characters** * An integer * A floating-point number * A boolean You can store up to **50 key-value pairs**.
    - `description` string, nullable — The description of the benefit. Will be displayed on products having this benefit.
    - `visibility` 'draft' | 'private' | 'public'
    - `type` 'license_keys', required
    - `properties` BenefitLicenseKeysCreateProperties
      - `prefix` string, nullable
      - `expires` BenefitLicenseKeyExpirationProperties
        - `ttl` integer, required
        - `timeframe` 'year' | 'month' | 'day', required
      - `activations` BenefitLicenseKeyActivationCreateProperties
        - `limit` integer, required
        - `enable_customer_admin` boolean, required
      - `limit_usage` integer, nullable
  - BenefitMeterCreditUpdate
    - `metadata` object — Key-value object allowing you to store additional information. The key must be a string with a maximum length of **40 characters**. The value must be either: * A string with a maximum length of **500 characters** * An integer * A floating-point number * A boolean You can store up to **50 key-value pairs**.
    - `description` string, nullable — The description of the benefit. Will be displayed on products having this benefit.
    - `visibility` 'draft' | 'private' | 'public'
    - `type` 'meter_credit', required
    - `properties` BenefitMeterCreditCreateProperties — Properties for creating a benefit of type `meter_unit`.
      - `units` integer, required
      - `rollover` boolean, required
      - `meter_id` string, uuid4, required
  - BenefitFeatureFlagUpdate
    - `metadata` object — Key-value object allowing you to store additional information. The key must be a string with a maximum length of **40 characters**. The value must be either: * A string with a maximum length of **500 characters** * An integer * A floating-point number * A boolean You can store up to **50 key-value pairs**.
    - `description` string, nullable — The description of the benefit. Will be displayed on products having this benefit.
    - `visibility` 'draft' | 'private' | 'public'
    - `type` 'feature_flag', required
    - `properties` BenefitFeatureFlagProperties — Properties for a benefit of type `feature_flag`.
  - BenefitSlackSharedChannelUpdate
    - `metadata` object — Key-value object allowing you to store additional information. The key must be a string with a maximum length of **40 characters**. The value must be either: * A string with a maximum length of **500 characters** * An integer * A floating-point number * A boolean You can store up to **50 key-value pairs**.
    - `description` string, nullable — The description of the benefit. Will be displayed on products having this benefit.
    - `type` 'slack_shared_channel', required
    - `properties` BenefitSlackSharedChannelCreateProperties
      - `slack_integration_id` string, uuid4, required — Polar Slack integration to use for this benefit.
      - `channel_name_template` string, required
      - `private` boolean
      - `welcome_message` string, nullable
      - `archive_on_revoke` boolean
      - `team_invitees` string[]

## Response `200`

Benefit updated.

- union
  - BenefitCustom — A benefit of type `custom`. Use it to grant any kind of benefit that doesn't fit in the other types.
    - `id` string, uuid4, required — The ID of the benefit.
    - `created_at` string, date-time, required — Creation timestamp of the object.
    - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object.
    - `type` 'custom', required
    - `description` string, required — The description of the benefit.
    - `selectable` boolean, required — Whether the benefit is selectable when creating a product.
    - `deletable` boolean, required — Whether the benefit is deletable.
    - `is_deleted` boolean, required — Whether the benefit is deleted.
    - `organization_id` string, uuid4, required — The ID of the organization owning the benefit.
    - `metadata` MetadataOutputType, required
    - `visibility` 'draft' | 'private' | 'public', required
    - `properties` BenefitCustomProperties, required — Properties for a benefit of type `custom`.
      - `note` string, nullable, required
    - `visibility_configurable` boolean, required
  - BenefitDiscord — A benefit of type `discord`. Use it to automatically invite your backers to a Discord server.
    - `id` string, uuid4, required — The ID of the benefit.
    - `created_at` string, date-time, required — Creation timestamp of the object.
    - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object.
    - `type` 'discord', required
    - `description` string, required — The description of the benefit.
    - `selectable` boolean, required — Whether the benefit is selectable when creating a product.
    - `deletable` boolean, required — Whether the benefit is deletable.
    - `is_deleted` boolean, required — Whether the benefit is deleted.
    - `organization_id` string, uuid4, required — The ID of the organization owning the benefit.
    - `metadata` MetadataOutputType, required
    - `visibility` 'draft' | 'private' | 'public', required
    - `properties` BenefitDiscordProperties, required — Properties for a benefit of type `discord`.
      - `guild_id` string, required — The ID of the Discord server.
      - `role_id` string, required — The ID of the Discord role to grant.
      - `kick_member` boolean, required — Whether to kick the member from the Discord server on revocation.
      - `guild_token` string, required
    - `visibility_configurable` boolean, required
  - BenefitGitHubRepository — A benefit of type `github_repository`. Use it to automatically invite your backers to a private GitHub repository.
    - `id` string, uuid4, required — The ID of the benefit.
    - `created_at` string, date-time, required — Creation timestamp of the object.
    - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object.
    - `type` 'github_repository', required
    - `description` string, required — The description of the benefit.
    - `selectable` boolean, required — Whether the benefit is selectable when creating a product.
    - `deletable` boolean, required — Whether the benefit is deletable.
    - `is_deleted` boolean, required — Whether the benefit is deleted.
    - `organization_id` string, uuid4, required — The ID of the organization owning the benefit.
    - `metadata` MetadataOutputType, required
    - `visibility` 'draft' | 'private' | 'public', required
    - `properties` BenefitGitHubRepositoryProperties, required — Properties for a benefit of type `github_repository`.
      - `repository_owner` string, required — The owner of the repository.
      - `repository_name` string, required — The name of the repository.
      - `permission` 'pull' | 'triage' | 'push' | 'maintain' | 'admin', required — The permission level to grant. Read more about roles and their permissions on [GitHub documentation](https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization#permissions-for-each-role).
    - `visibility_configurable` boolean, required
  - BenefitDownloadables
    - `id` string, uuid4, required — The ID of the benefit.
    - `created_at` string, date-time, required — Creation timestamp of the object.
    - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object.
    - `type` 'downloadables', required
    - `description` string, required — The description of the benefit.
    - `selectable` boolean, required — Whether the benefit is selectable when creating a product.
    - `deletable` boolean, required — Whether the benefit is deletable.
    - `is_deleted` boolean, required — Whether the benefit is deleted.
    - `organization_id` string, uuid4, required — The ID of the organization owning the benefit.
    - `metadata` MetadataOutputType, required
    - `visibility` 'draft' | 'private' | 'public', required
    - `properties` BenefitDownloadablesProperties, required
      - `archived` object, required
      - `files` string[], required
    - `visibility_configurable` boolean, required
  - BenefitLicenseKeys
    - `id` string, uuid4, required — The ID of the benefit.
    - `created_at` string, date-time, required — Creation timestamp of the object.
    - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object.
    - `type` 'license_keys', required
    - `description` string, required — The description of the benefit.
    - `selectable` boolean, required — Whether the benefit is selectable when creating a product.
    - `deletable` boolean, required — Whether the benefit is deletable.
    - `is_deleted` boolean, required — Whether the benefit is deleted.
    - `organization_id` string, uuid4, required — The ID of the organization owning the benefit.
    - `metadata` MetadataOutputType, required
    - `visibility` 'draft' | 'private' | 'public', required
    - `properties` BenefitLicenseKeysProperties, required
      - `prefix` string, nullable, required
      - `expires` BenefitLicenseKeyExpirationProperties, required
        - `ttl` integer, required
        - `timeframe` 'year' | 'month' | 'day', required
      - `activations` BenefitLicenseKeyActivationProperties, required
        - `limit` integer, required
        - `enable_customer_admin` boolean, required
      - `limit_usage` integer, nullable, required
    - `visibility_configurable` boolean, required
  - BenefitMeterCredit — A benefit of type `meter_unit`. Use it to grant a number of units on a specific meter.
    - `id` string, uuid4, required — The ID of the benefit.
    - `created_at` string, date-time, required — Creation timestamp of the object.
    - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object.
    - `type` 'meter_credit', required
    - `description` string, required — The description of the benefit.
    - `selectable` boolean, required — Whether the benefit is selectable when creating a product.
    - `deletable` boolean, required — Whether the benefit is deletable.
    - `is_deleted` boolean, required — Whether the benefit is deleted.
    - `organization_id` string, uuid4, required — The ID of the organization owning the benefit.
    - `metadata` MetadataOutputType, required
    - `visibility` 'draft' | 'private' | 'public', required
    - `properties` BenefitMeterCreditProperties, required — Properties for a benefit of type `meter_unit`.
      - `units` integer, required
      - `rollover` boolean, required
      - `meter_id` string, uuid4, required
    - `visibility_configurable` boolean, required
  - BenefitFeatureFlag — A benefit of type `feature_flag`. Use it to grant feature flags with key-value metadata that can be queried via the API and webhooks.
    - `id` string, uuid4, required — The ID of the benefit.
    - `created_at` string, date-time, required — Creation timestamp of the object.
    - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object.
    - `type` 'feature_flag', required
    - `description` string, required — The description of the benefit.
    - `selectable` boolean, required — Whether the benefit is selectable when creating a product.
    - `deletable` boolean, required — Whether the benefit is deletable.
    - `is_deleted` boolean, required — Whether the benefit is deleted.
    - `organization_id` string, uuid4, required — The ID of the organization owning the benefit.
    - `metadata` MetadataOutputType, required
    - `visibility` 'draft' | 'private' | 'public', required
    - `properties` BenefitFeatureFlagProperties, required — Properties for a benefit of type `feature_flag`.
    - `visibility_configurable` boolean, required
  - BenefitSlackSharedChannel
    - `id` string, uuid4, required — The ID of the benefit.
    - `created_at` string, date-time, required — Creation timestamp of the object.
    - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object.
    - `type` 'slack_shared_channel', required
    - `description` string, required — The description of the benefit.
    - `selectable` boolean, required — Whether the benefit is selectable when creating a product.
    - `deletable` boolean, required — Whether the benefit is deletable.
    - `is_deleted` boolean, required — Whether the benefit is deleted.
    - `organization_id` string, uuid4, required — The ID of the organization owning the benefit.
    - `metadata` MetadataOutputType, required
    - `visibility` 'draft' | 'private' | 'public', required
    - `properties` BenefitSlackSharedChannelProperties, required
      - `slack_integration_id` string, uuid4, required — Polar Slack integration linked to this benefit.
      - `channel_name_template` string, required — Template for the channel name. Supports placeholders: {customer_name}, {customer_email_local}, and {metadata.<key>} for any value stored in customer user metadata.
      - `private` boolean — Create the channel as private (recommended).
      - `welcome_message` string, nullable — Optional message posted to the channel right after creation.
      - `archive_on_revoke` boolean — Archive the channel when the benefit is revoked.
      - `team_invitees` string[] — Slack user IDs from the merchant workspace to invite to every channel created for this benefit.
    - `visibility_configurable` boolean, required

## Other responses

- `404` — Benefit not found.
- `422` — Validation Error

---

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