> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.beehiiv.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.beehiiv.com/_mcp/server. # Update a tier OAuth Scope: tiers:write PUT https://api.beehiiv.com/v2/publications/{publicationId}/tiers/{tierId} Content-Type: application/json Update an existing tier belonging to a specific publication Reference: https://developers.beehiiv.com/api-reference/tiers/put ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Path parameters - `publicationId` (string, required) — The prefixed ID of the publication object - `tierId` (string, required) — The prefixed ID of the tier object ### Body (application/json) This endpoint expects an object. - `name` (string, optional) - `description` (string, optional) - `prices_attributes` (list of UpdateTierPriceRequest, optional) ## Response ### 200 OK - `data` (Tier, optional) — The subscription tier object. ## Errors ### 400 Bad Request Error Bad Request - `status` (integer, required) - `statusText` (string, required) - `errors` (list of ErrorDetail, required) ### 401 Unauthorized Error Unauthorized. The API key or OAuth access token is missing, invalid, or expired. - `status` (integer, required) - `statusText` (string, required) - `errors` (list of ErrorDetail, required) ### 404 Not Found Error Resource Not Found - `status` (integer, required) - `statusText` (string, required) - `errors` (list of ErrorDetail, required) ### 429 Too Many Requests Error Rate Limit Exceeded - `status` (integer, required) - `statusText` (string, required) - `errors` (list of ErrorDetail, required) ### 500 Internal Server Error Internal Server Error - `status` (integer, required) - `statusText` (string, required) - `errors` (list of ErrorDetail, required) ## Types ### UpdateTierPriceRequest - `id` (string, required) — ID of the existing price. - `currency` (enum, required) - Allowed values: `usd`, `aud`, `cad`, `eur`, `gbp`, `inr`, `brl`, `mxn`, `nzd`, `dkk` - `amount_cents` (integer, required) - `interval` (enum, required) - Allowed values: `month`, `quarter`, `year`, `one_time`, `donation` - `interval_display` (string, optional) - `cta` (string, optional) - `features` (list of string, optional) - `delete` (boolean, optional, default: false) — Optionally delete the price when updating the tier. ### Tier The subscription tier object. - `id` (string, required) — The prefixed ID of the tier. - `name` (string, required) - `status` (enum, required) — Returns whether or not the tier has any active prices. - Allowed values: `active`, `archived` - `description` (string, optional, default: Super engaged readers) - `stats` (TierStats, optional) — Optional list of stats for a tier. Retrievable by including `expand: [stats]` in the tier request body. - `prices` (list of TierPrice, optional) — Optional list of prices for a tier. Retrievable by including `expand: [prices]` in the tier request body. ### ErrorDetail - `message` (string, required) - `code` (string, required) ### TierStats Optional list of stats for a tier. Retrievable by including `expand: [stats]` in the tier request body. - `active_subscriptions` (integer, required) — Total number of active subscriptions belonging to this tier. ### TierPrice Price belonging to a Tier - `id` (string, optional) — The prefixed ID of the price. - `currency` (enum, optional) - Allowed values: `usd`, `aud`, `cad`, `eur`, `gbp`, `inr`, `brl`, `mxn`, `nzd`, `dkk` - `amount_cents` (integer, optional) - `enabled` (boolean, optional, default: true) - `interval` (enum, optional) - Allowed values: `month`, `quarter`, `year`, `one_time`, `donation` - `denominator` (string, optional) - `cta` (string, optional) — When using the external Stripe checkout, this text will be displayed on the button - `features` (list of string, optional) ## Examples **Request** ```json { "name": "Gold", "description": "Our premium tier with exclusive benefits", "prices_attributes": [ { "id": "price_00000000-0000-0000-0000-000000000000", "currency": "usd", "amount_cents": 500, "interval": "month", "interval_display": "Monthly", "cta": "Subscribe Now", "features": [ "Exclusive content" ], "delete": true } ] } ``` **Response** ```json { "data": { "id": "tier_00000000-0000-0000-0000-000000000000", "name": "Gold", "status": "active", "description": "description", "stats": { "active_subscriptions": 1 }, "prices": [ { "id": "price_00000000-0000-0000-0000-000000000000", "amount_cents": 500 } ] } } ``` **SDK Code** ```typescript import { BeehiivClient } from "beehiiv"; const client = new BeehiivClient({ token: "YOUR_TOKEN" }); await client.tiers.putPublicationsPublicationIdTiersTierId("pub_00000000-0000-0000-0000-000000000000", "tier_00000000-0000-0000-0000-000000000000"); ``` ```python import requests url = "https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/tiers/tier_00000000-0000-0000-0000-000000000000" payload = { "name": "Gold", "description": "Our premium tier with exclusive benefits", "prices_attributes": [ { "id": "price_00000000-0000-0000-0000-000000000000", "currency": "usd", "amount_cents": 500, "interval": "month", "interval_display": "Monthly", "cta": "Subscribe Now", "features": ["Exclusive content"], "delete": True } ] } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.put(url, json=payload, headers=headers) print(response.json()) ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/tiers/tier_00000000-0000-0000-0000-000000000000" payload := strings.NewReader("{\n \"name\": \"Gold\",\n \"description\": \"Our premium tier with exclusive benefits\",\n \"prices_attributes\": [\n {\n \"id\": \"price_00000000-0000-0000-0000-000000000000\",\n \"currency\": \"usd\",\n \"amount_cents\": 500,\n \"interval\": \"month\",\n \"interval_display\": \"Monthly\",\n \"cta\": \"Subscribe Now\",\n \"features\": [\n \"Exclusive content\"\n ],\n \"delete\": true\n }\n ]\n}") req, _ := http.NewRequest("PUT", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/tiers/tier_00000000-0000-0000-0000-000000000000") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Put.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"name\": \"Gold\",\n \"description\": \"Our premium tier with exclusive benefits\",\n \"prices_attributes\": [\n {\n \"id\": \"price_00000000-0000-0000-0000-000000000000\",\n \"currency\": \"usd\",\n \"amount_cents\": 500,\n \"interval\": \"month\",\n \"interval_display\": \"Monthly\",\n \"cta\": \"Subscribe Now\",\n \"features\": [\n \"Exclusive content\"\n ],\n \"delete\": true\n }\n ]\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.put("https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/tiers/tier_00000000-0000-0000-0000-000000000000") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"name\": \"Gold\",\n \"description\": \"Our premium tier with exclusive benefits\",\n \"prices_attributes\": [\n {\n \"id\": \"price_00000000-0000-0000-0000-000000000000\",\n \"currency\": \"usd\",\n \"amount_cents\": 500,\n \"interval\": \"month\",\n \"interval_display\": \"Monthly\",\n \"cta\": \"Subscribe Now\",\n \"features\": [\n \"Exclusive content\"\n ],\n \"delete\": true\n }\n ]\n}") .asString(); ``` ```php request('PUT', 'https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/tiers/tier_00000000-0000-0000-0000-000000000000', [ 'body' => '{ "name": "Gold", "description": "Our premium tier with exclusive benefits", "prices_attributes": [ { "id": "price_00000000-0000-0000-0000-000000000000", "currency": "usd", "amount_cents": 500, "interval": "month", "interval_display": "Monthly", "cta": "Subscribe Now", "features": [ "Exclusive content" ], "delete": true } ] }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/tiers/tier_00000000-0000-0000-0000-000000000000"); var request = new RestRequest(Method.PUT); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"name\": \"Gold\",\n \"description\": \"Our premium tier with exclusive benefits\",\n \"prices_attributes\": [\n {\n \"id\": \"price_00000000-0000-0000-0000-000000000000\",\n \"currency\": \"usd\",\n \"amount_cents\": 500,\n \"interval\": \"month\",\n \"interval_display\": \"Monthly\",\n \"cta\": \"Subscribe Now\",\n \"features\": [\n \"Exclusive content\"\n ],\n \"delete\": true\n }\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "name": "Gold", "description": "Our premium tier with exclusive benefits", "prices_attributes": [ [ "id": "price_00000000-0000-0000-0000-000000000000", "currency": "usd", "amount_cents": 500, "interval": "month", "interval_display": "Monthly", "cta": "Subscribe Now", "features": ["Exclusive content"], "delete": true ] ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/tiers/tier_00000000-0000-0000-0000-000000000000")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PUT" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```