Away 9:35 PM

5 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

POST /legacy-badges/v1/universes/{universeId}/badges — openapi

Creates a new badge.

Charges the selected payment source and creates the badge under the universe's root place.

Endpoint

Method: POST

Path: /legacy-badges/v1/universes/{universeId}/badges

Servers:

Parameters

NameLocationRequiredDescription
universeIdpathtrueThe ID of the universe to create the badge for.
 
[
  {
    "in": "path",
    "name": "universeId",
    "description": "The ID of the universe to create the badge for.",
    "required": true,
    "schema": {
      "type": "integer",
      "format": "int64"
    }
  }
]

Request Body

{
  "content": {
    "multipart/form-data": {
      "schema": {
        "type": "object",
        "properties": {
          "name": {
            "description": "The badge name.",
            "type": "string"
          },
          "description": {
            "description": "The badge description.",
            "type": "string"
          },
          "paymentSourceType": {
            "description": "Whether or not to pay for the badge with user funds, or group funds.",
            "type": "integer",
            "format": "int32",
            "enum": [
              1,
              2
            ]
          },
          "files": {
            "description": "The badge icon. Optional: when omitted and a curated default badge icon is configured on\r\nthe service, the badge is created with that default icon. When provided, exactly one file\r\nmust be supplied.",
            "type": "string",
            "format": "binary"
          },
          "expectedCost": {
            "description": "User expected cost of a badge.",
            "type": "integer",
            "format": "int64"
          },
          "isActive": {
            "description": "Whether or not the badge should be created in the active state.",
            "type": "boolean"
          }
        }
      }
    }
  }
}

Responses

StatusDescription
200OK
40011: The badge icon is invalid. 14: Invalid badge name. 15: Invalid badge description. 16: Payment source is invalid. 18: Expected badge cost is different from the actual badge cost.
4010: Authorization has been denied for this request.
4030: Token Validation Failed 6: Text moderated. 12: You do not have permission to manage this game's badges. 17: Insufficient funds.
4043: The game is invalid or does not exist.
42913: Too many requests, try again later.
 
{
  "200": {
    "description": "OK",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Roblox.Web.Responses.Badges.BadgeResponseV2"
        }
      },
      "text/json": {
        "schema": {
          "$ref": "#/components/schemas/Roblox.Web.Responses.Badges.BadgeResponseV2"
        }
      }
    }
  },
  "400": {
    "description": "11: The badge icon is invalid.\r\n14: Invalid badge name.\r\n15: Invalid badge description.\r\n16: Payment source is invalid.\r\n18: Expected badge cost is different from the actual badge cost."
  },
  "401": {
    "description": "0: Authorization has been denied for this request."
  },
  "403": {
    "description": "0: Token Validation Failed\r\n6: Text moderated.\r\n12: You do not have permission to manage this game's badges.\r\n17: Insufficient funds."
  },
  "404": {
    "description": "3: The game is invalid or does not exist."
  },
  "429": {
    "description": "13: Too many requests, try again later."
  }
}

Authentication

{
  "security": [
    {
      "roblox-api-key": []
    },
    {
      "roblox-oauth2": []
    }
  ],
  "securitySchemes": {
    "roblox-api-key": {
      "type": "apiKey",
      "description": "A configurable key that allows granular access to Roblox resources. See https://create.roblox.com/docs/cloud/auth/api-keys for more information.",
      "name": "x-api-key",
      "in": "header"
    },
    "roblox-legacy-cookie": {
      "type": "apiKey",
      "description": "A browser cookie that represents the identity of a Roblox user. DO NOT SHARE THIS. Sharing this will allow someone to log in as you and to steal your Robux and items. We do not recommend using cookies to call endpoints. When possible, use API keys with the x-api-key header or OAuth 2.0 instead for authentication.",
      "in": "cookie",
      "name": ".ROBLOSECURITY"
    },
    "roblox-oauth2": {
      "type": "oauth2",
      "description": "Build or authorize apps to access Roblox resources. See https://create.roblox.com/docs/cloud/auth/oauth2-overview for more information.",
      "flows": {
        "authorizationCode": {
          "authorizationUrl": "https://apis.roblox.com/oauth/v1/authorize",
          "tokenUrl": "https://apis.roblox.com/oauth/v1/token",
          "refreshUrl": "https://apis.roblox.com/oauth/v1/token",
          "scopes": {}
        }
      }
    }
  }
}

Complete Operation Definition

{
  "tags": [
    "Badges",
    "Universes"
  ],
  "summary": "Creates a new badge.",
  "description": "Charges the selected payment source and creates the badge under the universe's root place.",
  "parameters": [
    {
      "in": "path",
      "name": "universeId",
      "description": "The ID of the universe to create the badge for.",
      "required": true,
      "schema": {
        "type": "integer",
        "format": "int64"
      }
    }
  ],
  "requestBody": {
    "content": {
      "multipart/form-data": {
        "schema": {
          "type": "object",
          "properties": {
            "name": {
              "description": "The badge name.",
              "type": "string"
            },
            "description": {
              "description": "The badge description.",
              "type": "string"
            },
            "paymentSourceType": {
              "description": "Whether or not to pay for the badge with user funds, or group funds.",
              "type": "integer",
              "format": "int32",
              "enum": [
                1,
                2
              ]
            },
            "files": {
              "description": "The badge icon. Optional: when omitted and a curated default badge icon is configured on\r\nthe service, the badge is created with that default icon. When provided, exactly one file\r\nmust be supplied.",
              "type": "string",
              "format": "binary"
            },
            "expectedCost": {
              "description": "User expected cost of a badge.",
              "type": "integer",
              "format": "int64"
            },
            "isActive": {
              "description": "Whether or not the badge should be created in the active state.",
              "type": "boolean"
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "OK",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Roblox.Web.Responses.Badges.BadgeResponseV2"
          }
        },
        "text/json": {
          "schema": {
            "$ref": "#/components/schemas/Roblox.Web.Responses.Badges.BadgeResponseV2"
          }
        }
      }
    },
    "400": {
      "description": "11: The badge icon is invalid.\r\n14: Invalid badge name.\r\n15: Invalid badge description.\r\n16: Payment source is invalid.\r\n18: Expected badge cost is different from the actual badge cost."
    },
    "401": {
      "description": "0: Authorization has been denied for this request."
    },
    "403": {
      "description": "0: Token Validation Failed\r\n6: Text moderated.\r\n12: You do not have permission to manage this game's badges.\r\n17: Insufficient funds."
    },
    "404": {
      "description": "3: The game is invalid or does not exist."
    },
    "429": {
      "description": "13: Too many requests, try again later."
    }
  },
  "x-roblox-stability": "EXPERIMENTAL",
  "x-roblox-rate-limits": {
    "perApiKeyOwner": {
      "period": "MINUTE",
      "maxInPeriod": 100
    },
    "perOauth2Authorization": {
      "period": "MINUTE",
      "maxInPeriod": 100
    }
  },
  "x-roblox-engine-usability": {
    "apiKeyWithHttpService": false
  },
  "security": [
    {
      "roblox-api-key": []
    },
    {
      "roblox-oauth2": []
    }
  ],
  "x-roblox-scopes": [
    {
      "name": "legacy-universe.badge:manage-and-spend-robux"
    }
  ],
  "externalDocs": {
    "url": "https://create.roblox.com/docs/cloud/reference/features/badges#post_legacy_badges_v1_universes__universeId__badges"
  }
}