> ## Documentation Index > Fetch the complete documentation index at: https://www.courier.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Update or create user Preferences for a Subscription Topic > Sets a user's opt-in status and channel choices for one subscription topic, overriding the tenant default for that topic only. ## OpenAPI ````yaml /openapi-specs/openapi.documented.yml put /users/{user_id}/preferences/{topic_id} openapi: 3.0.1 info: title: Courier description: The Courier REST API for sending and managing notifications across channels. version: 0.0.1 servers: - url: https://api.courier.com description: Production security: [] tags: - name: Send description: >- Send a message to one or more recipients — users, lists, audiences, or tenants — across every channel you have configured. - name: Templates description: >- Create, update, version, publish, and localize notification templates and their content. - name: Brands description: >- Manage the logos, colors, and layout that give the templates you send a consistent look. - name: Routing Strategies description: >- Define reusable channel routing and failover strategies, and see which templates use them. - name: Journeys description: >- Build, version, publish, invoke, and cancel multi-step notification workflows, along with the templates scoped to them. - name: Broadcasts description: >- Create a one-off send to a list or audience, author its content, then send it immediately or schedule it for later. - name: User Profiles description: >- Store the contact information Courier delivers to for each user — email, phone number, push tokens, and any custom data you send to. - name: Tenants description: >- Manage tenants — the organizations, teams, or accounts your users belong to — along with their users and default preferences. - name: Audiences description: >- Define filter-based groups whose membership Courier recalculates as user profiles change. - name: Lists description: >- Manage static groups of users that you subscribe explicitly, and send to them by list id or list pattern. - name: Providers description: >- Configure the channel providers Courier delivers through, and browse the provider types it supports. - name: Preference Topics description: >- Manage the workspace catalog of subscription topics, the sections that group them, and publishing the preference page. - name: User Preferences description: >- Read and write a single user's notification preferences, per topic and per channel. - name: Messages description: >- Look up the messages Courier has accepted, inspect their delivery history and rendered output, and cancel, resend, or archive them. - name: Device Tokens description: >- Register and manage the APNS and FCM device tokens Courier delivers push notifications to. - name: Tenant Memberships description: >- Associate a user with one or more tenants, and read or remove those associations. - name: Tenant Templates description: >- Manage the templates and template versions scoped to a single tenant, including the ones authored in the embedded designer. - name: Automations description: >- Invoke a stored automation template or an ad hoc automation defined in the request. - name: Digests description: >- Inspect what has accumulated in a digest schedule and release a digest ahead of its next scheduled delivery. - name: Translations description: >- Store and retrieve the translation strings Courier uses to render localized template content. - name: Track Events description: >- Record an inbound event that triggers the journeys and automations mapped to it. - name: Audit Events description: >- Read the audit trail of configuration and access changes in your workspace. - name: Authentication description: >- Issue scoped, short-lived JWTs so client-side SDKs — Inbox, Preferences, and the embedded designer — can call Courier as a single user. Server-side requests authenticate with your workspace API key instead. paths: /users/{user_id}/preferences/{topic_id}: put: tags: - User Preferences summary: Update or create user Preferences for a Subscription Topic description: >- Sets a user's opt-in status and channel choices for one subscription topic, overriding the tenant default for that topic only. operationId: users_preferences_update parameters: - name: user_id in: path description: >- A unique identifier associated with the user whose preferences you wish to retrieve. required: true schema: type: string examples: Example1: value: abc-123 - name: topic_id in: path description: A unique identifier associated with a subscription topic. required: true schema: type: string examples: Example1: value: pt_01kx4h2jdafq8bk996nn92357r - name: tenant_id in: query description: Update the preferences of a user for this specific tenant context. required: false schema: type: string nullable: true requestBody: required: true content: application/json: schema: type: object properties: topic: $ref: '#/components/schemas/UsersTopicPreferenceUpdate' required: - topic examples: Example1: value: topic: status: OPTED_IN has_custom_routing: true custom_routing: - inbox - email responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/UsersUserPreferencesUpdateResponse' examples: Example1: value: message: success '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error security: - BearerAuth: [] x-codeSamples: - lang: JavaScript source: >- import Courier from '@trycourier/courier'; const client = new Courier({ apiKey: process.env['COURIER_API_KEY'], // This is the default and can be omitted }); const response = await client.users.preferences.updateOrCreateTopic('topic_id', { user_id: 'user_id', topic: { status: 'OPTED_IN', has_custom_routing: true, custom_routing: ['inbox', 'email'], }, }); console.log(response.message); - lang: Python source: |- import os from courier import Courier client = Courier( api_key=os.environ.get("COURIER_API_KEY"), # This is the default and can be omitted ) response = client.users.preferences.update_or_create_topic( topic_id="topic_id", user_id="user_id", topic={ "status": "OPTED_IN", "has_custom_routing": True, "custom_routing": ["inbox", "email"], }, ) print(response.message) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/trycourier/courier-go/v4\"\n\t\"github.com/trycourier/courier-go/v4/option\"\n\t\"github.com/trycourier/courier-go/v4/shared\"\n)\n\nfunc main() {\n\tclient := courier.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.Users.Preferences.UpdateOrNewTopic(\n\t\tcontext.TODO(),\n\t\t\"topic_id\",\n\t\tcourier.UserPreferenceUpdateOrNewTopicParams{\n\t\t\tUserID: \"user_id\",\n\t\t\tTopic: courier.UserPreferenceUpdateOrNewTopicParamsTopic{\n\t\t\t\tStatus: shared.PreferenceStatusOptedIn,\n\t\t\t\tHasCustomRouting: courier.Bool(true),\n\t\t\t\tCustomRouting: []shared.ChannelClassification{shared.ChannelClassificationInbox, shared.ChannelClassificationEmail},\n\t\t\t},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Message)\n}\n" - lang: Java source: >- package com.courier.example; import com.courier.client.CourierClient; import com.courier.client.okhttp.CourierOkHttpClient; import com.courier.models.PreferenceStatus; import com.courier.models.users.preferences.PreferenceUpdateOrCreateTopicParams; import com.courier.models.users.preferences.PreferenceUpdateOrCreateTopicResponse; public final class Main { private Main() {} public static void main(String[] args) { CourierClient client = CourierOkHttpClient.fromEnv(); PreferenceUpdateOrCreateTopicParams params = PreferenceUpdateOrCreateTopicParams.builder() .userId("user_id") .topicId("topic_id") .topic(PreferenceUpdateOrCreateTopicParams.Topic.builder() .status(PreferenceStatus.OPTED_IN) .build()) .build(); PreferenceUpdateOrCreateTopicResponse response = client.users().preferences().updateOrCreateTopic(params); } } - lang: Ruby source: |- require "courier" courier = Courier::Client.new(api_key: "My API Key") response = courier.users.preferences.update_or_create_topic( "topic_id", user_id: "user_id", topic: {status: :OPTED_IN} ) puts(response) - lang: PHP source: >- users->preferences->updateOrCreateTopic( 'topic_id', userID: 'user_id', topic: [ 'status' => PreferenceStatus::OPTED_IN, 'customRouting' => [ ChannelClassification::INBOX, ChannelClassification::EMAIL ], 'hasCustomRouting' => true, ], tenantID: 'tenant_id', ); var_dump($response); } catch (APIException $e) { echo $e->getMessage(); } - lang: C# source: >- using System; using TryCourier; using TryCourier.Models; using TryCourier.Models.Users.Preferences; CourierClient client = new(); PreferenceUpdateOrCreateTopicParams parameters = new() { UserID = "user_id", TopicID = "topic_id", Topic = new() { Status = PreferenceStatus.OptedIn, CustomRouting = [ ChannelClassification.Inbox, ChannelClassification.Email ], HasCustomRouting = true, }, }; var response = await client.Users.Preferences.UpdateOrCreateTopic(parameters); Console.WriteLine(response); - lang: CLI source: |- courier users:preferences update-or-create-topic \ --api-key 'My API Key' \ --user-id user_id \ --topic-id topic_id \ --topic '{status: OPTED_IN}' components: schemas: UsersTopicPreferenceUpdate: title: UsersTopicPreferenceUpdate type: object properties: status: allOf: - $ref: '#/components/schemas/PreferenceStatus' description: >- The subscription status to set: OPTED_IN or OPTED_OUT. REQUIRED is a topic-level default, not a user choice; the API rejects opting a user out of a REQUIRED topic. custom_routing: type: array items: $ref: '#/components/schemas/ChannelClassification' nullable: true description: >- The channels to deliver this topic on when has_custom_routing is true. One or more of: direct_message, email, push, sms, webhook, inbox. has_custom_routing: type: boolean nullable: true description: >- Set to true to route this topic to the channels in custom_routing instead of the topic's default routing. required: - status UsersUserPreferencesUpdateResponse: title: UsersUserPreferencesUpdateResponse type: object properties: message: type: string example: success required: - message BadRequest: title: BadRequest type: object properties: type: type: string enum: - invalid_request_error required: - type allOf: - $ref: '#/components/schemas/BaseError' PreferenceStatus: title: PreferenceStatus type: string enum: - OPTED_IN - OPTED_OUT - REQUIRED ChannelClassification: title: ChannelClassification type: string enum: - direct_message - email - push - sms - webhook - inbox BaseError: title: BaseError type: object properties: message: type: string description: A message describing the error that occurred. required: - message securitySchemes: BearerAuth: type: http scheme: bearer ````