> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appcharge.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Badge

> Updates a badge.

```bash Update Emblem Badge with Asset ID theme={"system"}
curl -X PUT \
  'https://api.appcharge.com/components/v1/badge/new_item' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-publisher-token: <x-publisher-token>' \
  --data '{
    "name": "New Item",
    "publisherBadgeId": "new_item",
    "type": "emblem",
    "badgeImageId": "507f1f77bcf86cd799439011"
  }'
```

```bash Update Emblem Badge with Image URL theme={"system"}
curl -X PUT \
  'https://api.appcharge.com/components/v1/badge/limited_offer' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-publisher-token: <x-publisher-token>' \
  --data '{
    "name": "Limited Offer",
    "publisherBadgeId": "limited_offer",
    "type": "emblem",
    "badgeImageUrl": "https://media.appcharge.com/media/69133d595af23405d8e843a5"
  }'
```

```json Update Emblem Badge with Asset ID theme={"system"}
{
  "id": "507f1f77bcf86cd799439020",
  "name": "New Item",
  "publisherBadgeId": "new_item",
  "type": "emblem",
  "badgeImageId": "507f1f77bcf86cd799439011",
  "badgeImageUrl": "https://media.appcharge.com/media/69133d595af23405d8e843a5"
}
```

```json Update Emblem Badge with Image URL theme={"system"}
{
  "id": "507f1f77bcf86cd799439021",
  "name": "Limited Offer",
  "publisherBadgeId": "limited_offer",
  "type": "emblem",
  "badgeImageId": "507f1f77bcf86cd799439022",
  "badgeImageUrl": "https://media.appcharge.com/media/69133d595af23405d8e843a5"
}
```


## OpenAPI

````yaml openapi-badges-api.json PUT /components/v1/badge/{externalId}
openapi: 3.0.3
info:
  title: Badges API
  version: 1.0.0
servers:
  - url: https://api-sandbox.appcharge.com
security:
  - PublisherTokenAuth: []
tags:
  - name: Badges
paths:
  /components/v1/badge/{externalId}:
    parameters:
      - in: path
        name: externalId
        required: true
        schema:
          type: string
          example: new_year_ribbon
        description: External ID that you defined.
    put:
      tags:
        - Badges
      description: >-
        Updates a badge.


        For emblem badges, to change the badge image, provide `badgeImageId`,
        `badgeImageUrl`, or both. Use `badgeImageId`, the `id` returned by [Get
        All Assets](/../../api-reference/media/assets-library/get-all-assets),
        to reuse an existing asset. Use `badgeImageUrl` to create a new asset
        from a URL. If both are provided, `badgeImageId` takes precedence and no
        new asset is created.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/EmblemBadgeUpdate'
                - $ref: '#/components/schemas/RibbonBadgeUpdate'
              discriminator:
                propertyName: type
                mapping:
                  emblem: '#/components/schemas/EmblemBadgeUpdate'
                  ribbon: '#/components/schemas/RibbonBadgeUpdate'
            examples:
              emblemReuseViaAssetId:
                summary: Reuse existing asset
                value:
                  name: New Year Celebration
                  publisherBadgeId: new_year_celebration
                  type: emblem
                  badgeImageId: 507f1f77bcf86cd799439011
              emblemCreateViaUrl:
                summary: Create asset from URL
                value:
                  name: New Year Celebration
                  publisherBadgeId: new_year_celebration
                  type: emblem
                  badgeImageUrl: https://media.appcharge.com/media/69133d595af23405d8e843a5
              emblemWithAssetIdAndUrl:
                summary: Reuse asset ID and image URL
                value:
                  name: New Year Celebration
                  publisherBadgeId: new_year_celebration
                  type: emblem
                  badgeImageId: 507f1f77bcf86cd799439011
                  badgeImageUrl: https://media.appcharge.com/media/69133d595af23405d8e843a5
      responses:
        '200':
          description: Badge updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadgeReadResponse'
        '400':
          description: >-
            Bad request. Invalid input or validation failure. For emblem badges,
            returned when the asset ID isn't found or isn't of type `badge`.
        '404':
          description: Badge not found.
components:
  schemas:
    EmblemBadgeUpdate:
      title: Emblem Badge
      allOf:
        - $ref: '#/components/schemas/BadgeBase'
        - description: >-
            Update an emblem badge. To change the badge image, provide
            `badgeImageId` (asset ID), `badgeImageUrl`, or both. If both are
            provided, `badgeImageId` takes precedence.
        - type: object
          properties:
            name:
              type: string
              description: Badge name.
              example: New Year Celebration
            publisherBadgeId:
              type: string
              description: Badge ID that you define.
              example: new_year_celebration
            type:
              type: string
              enum:
                - emblem
              description: Badge type.
              example: emblem
          required:
            - type
    RibbonBadgeUpdate:
      title: Ribbon Badge
      allOf:
        - $ref: '#/components/schemas/RibbonBadgeBase'
        - description: Update a ribbon badge.
        - type: object
          properties:
            name:
              type: string
              description: Badge name.
              example: New Year Celebration
            publisherBadgeId:
              type: string
              description: Badge ID that you define.
              example: new_year_celebration
            type:
              type: string
              enum:
                - ribbon
              description: Badge type.
              example: ribbon
            imageUrl:
              type: string
              format: url
              description: >-
                Badge image URL in PNG or JPEG format.


                For uploaded files, this is the Appcharge-hosted CDN URL. For
                external image URLs, this is the original image URL served from
                the provided URL. External image URLs are saved and used as-is,
                and Appcharge doesn't download, copy, upload, or host them.
                Images must remain available at the provided URLs.


                We recommend uploading image files instead of using external
                URLs when possible.
              example: https://media.appcharge.com/media/69133d595af23405d8e843a5
            text:
              type: string
              description: Badge text.
              example: Updated New Year Sale
            backgroundColor:
              allOf:
                - $ref: '#/components/schemas/BackgroundColorGradient'
                - description: Background color details.
                  example:
                    colorOne: '#f9d423'
                    colorTwo: '#ff4e50'
                    gradientDirection: to top
            textColor:
              type: object
              properties:
                colorOne:
                  type: string
                  pattern: ^#[0-9a-fA-F]{6}$
                  description: Text color in hex format.
                  example: '#ffffff'
          required:
            - type
    BadgeReadResponse:
      oneOf:
        - $ref: '#/components/schemas/EmblemBadgeResponse'
        - $ref: '#/components/schemas/RibbonBadgeResponse'
      discriminator:
        propertyName: type
        mapping:
          emblem: '#/components/schemas/EmblemBadgeResponse'
          ribbon: '#/components/schemas/RibbonBadgeResponse'
    BadgeBase:
      type: object
      properties:
        name:
          type: string
          description: Badge name.
          example: New Year Celebration
        publisherBadgeId:
          type: string
          description: Badge ID that you define.
          example: new_year_celebration
        type:
          type: string
          description: Badge type.
          example: ribbon
        badgeImageId:
          type: string
          description: >-
            Asset ID of an existing badge image in the [Assets
            Library](/../../api-reference/media/assets-library/introduction).
            Must reference an asset of type `badge`. Reuses the existing asset
            without creating a duplicate. If both `badgeImageId` and
            `badgeImageUrl` are provided, `badgeImageId` takes precedence.
          example: 507f1f77bcf86cd799439011
        badgeImageUrl:
          type: string
          format: url
          description: >-
            Badge image URL in PNG or JPEG format. Creates a new asset from the
            URL when `badgeImageId` isn't provided. If both `badgeImageId` and
            `badgeImageUrl` are provided, `badgeImageId` takes precedence.


            For uploaded files, this is the Appcharge-hosted CDN URL. For
            external image URLs, this is the original image URL served from the
            provided URL. External image URLs are saved and used as-is, and
            Appcharge doesn't download, copy, upload, or host them. Images must
            remain available at the provided URLs.


            We recommend uploading image files instead of using external URLs
            when possible.
          example: https://media.appcharge.com/media/69133d595af23405d8e843a5
      required:
        - name
        - publisherBadgeId
        - type
    RibbonBadgeBase:
      type: object
      properties:
        name:
          type: string
          description: Badge name.
          example: New Year Celebration
        publisherBadgeId:
          type: string
          description: Badge ID that you define.
          example: new_year_celebration
        type:
          type: string
          description: Badge type.
          example: ribbon
      required:
        - name
        - publisherBadgeId
        - type
    BackgroundColorGradient:
      type: object
      properties:
        colorOne:
          type: string
          default: '#000000'
          pattern: ^#[0-9a-fA-F]{6}$
          description: Primary gradient color in hex format.
          example: '#00c6ff'
        colorTwo:
          type: string
          pattern: ^#[0-9a-fA-F]{6}$
          description: Secondary gradient color in hex format.
          example: '#0072ff'
        gradientDirection:
          type: string
          enum:
            - to bottom
            - to top
            - to right
            - to left
            - to bottom right
            - to top left
            - to bottom left
            - to top right
          default: to bottom
          description: Direction of gradient transition between `colorOne` and `colorTwo`.
          example: to right
    EmblemBadgeResponse:
      title: Emblem Badge
      type: object
      properties:
        id:
          type: string
          description: Badge ID.
          example: 507f1f77bcf86cd799439011
        name:
          type: string
          description: Badge name.
          example: New Year Celebration
        publisherBadgeId:
          type: string
          description: Badge ID that you defined.
          example: new_year_celebration
        type:
          type: string
          enum:
            - emblem
          description: Badge type.
          example: emblem
        badgeImageId:
          type: string
          description: >-
            Asset ID of the badge image. Save this value to reuse the same asset
            in future create or update requests. Only present for emblem badges
            when the image is linked to an asset.
          example: 507f1f77bcf86cd799439011
        badgeImageUrl:
          type: string
          format: url
          description: >-
            Badge image URL. For uploaded files, this is the Appcharge-hosted
            CDN URL. For external image URLs, this is the original image URL
            served from the provided URL. For emblem badges, returned alongside
            `badgeImageId` when the image is linked to an asset.
          example: https://media.appcharge.com/media/69133d595af23405d8e843a5
    RibbonBadgeResponse:
      title: Ribbon Badge
      type: object
      properties:
        id:
          type: string
          description: Badge ID.
          example: 507f1f77bcf86cd799439012
        name:
          type: string
          description: Badge name.
          example: New Year Celebration
        publisherBadgeId:
          type: string
          description: Badge ID that you defined.
          example: new_year_celebration
        type:
          type: string
          enum:
            - ribbon
          description: Badge type.
          example: ribbon
        badgeImageUrl:
          type: string
          format: url
          description: >-
            Badge image URL. For uploaded files, this is the Appcharge-hosted
            CDN URL. For external image URLs, this is the original image URL
            served from the provided URL.
          example: https://media.appcharge.com/media/69133d595af23405d8e843a5
        text:
          type: string
          description: Badge text.
          example: New Year Sale
        backgroundColor:
          allOf:
            - $ref: '#/components/schemas/BackgroundColorGradient'
            - description: Background color details.
              example:
                colorOne: '#00c6ff'
                colorTwo: '#0072ff'
                gradientDirection: to right
        textColor:
          type: object
          properties:
            colorOne:
              type: string
              pattern: ^#[0-9a-fA-F]{6}$
              description: Text color in hex format.
              example: '#ffffff'
  securitySchemes:
    PublisherTokenAuth:
      type: apiKey
      in: header
      name: x-publisher-token
      description: Publisher token, as displayed in the Publisher Dashboard.

````