Merchant Discord

All routes require:

Authorization: Bearer mk_live_<your_key>

The caller must be able to access that store. A key with store scope SELECTED must include that store. Access mode FULL skips the scope list and still requires dashboard permission configureStorefront. Access mode RESTRICTED must include the scope on the route and that same permission. discord:write also satisfies discord:read.

GET   /api/merchant/v1/stores/{storeId}/discord
PATCH /api/merchant/v1/stores/{storeId}/discord
PUT   /api/merchant/v1/stores/{storeId}/discord

PUT calls the same handler as PATCH. clientSecret and botToken are never returned. The response uses hasClientSecret and hasBotToken.

Discord settings

GET, PATCH, and PUT return this object. PATCH and PUT also fill applicationSync. GET sets applicationSync to null. When no integration is saved, configured and enabled are false, the id fields are null, both arrays are empty, showCheckoutLink is true, and inviteUrl is null. The three URL fields are still set.

string

Store record id.

boolean

true when an integration row exists.

boolean

Stored flag. A successful PATCH or PUT saves enabled as true.

string | null

Discord application client id, or null.

boolean

true when a client secret is stored.

boolean

true when a bot token is stored.

string | null

Discord application id, or null.

string | null

Discord application public key, or null.

string[]

Guild ids the bot is in.

string[]

Discord user snowflakes allowed to manage the bot.

string | null

Role snowflake given to customers, or null.

string | null

Discord invite URL shown to customers, or null.

boolean

Whether checkout shows the Discord link.

string | null

ISO time of the last command sync, or null.

string

{storePublicUrl}/discord/callback

string

{storePublicUrl}/discord/link/callback

string

{dashboardUrl}/api/discord/interactions

string | null

Bot invite URL when clientId and a bot token are both stored. Otherwise null.

object | null

null on GET. On PATCH and PUT, the result of pushing the application description, OAuth redirects, and (on a public HTTPS dashboard) the interactions endpoint to Discord.

Show properties

boolean

true after a save.

boolean

true when Discord accepted the update.

string | null

Sync result text.

{
  "storeId": "STORE_ID",
  "configured": true,
  "enabled": true,
  "clientId": "123456789012345678",
  "hasClientSecret": true,
  "hasBotToken": true,
  "applicationId": "123456789012345678",
  "publicKey": "abcdef",
  "connectedGuildIds": ["223456789012345678"],
  "authorizedDiscordUserIds": ["323456789012345678"],
  "customerRoleId": "423456789012345678",
  "customerInviteUrl": "https://discord.gg/joinmarkt",
  "showCheckoutLink": true,
  "commandsSyncedAt": null,
  "redirectUri": "https://acme.joinmarkt.com/discord/callback",
  "buyerLinkRedirectUri": "https://acme.joinmarkt.com/discord/link/callback",
  "interactionsUrl": "https://dash.joinmarkt.com/api/discord/interactions",
  "inviteUrl": "https://discord.com/api/oauth2/authorize?client_id=123456789012345678&permissions=268437504&response_type=code&scope=bot+applications.commands&redirect_uri=https%3A%2F%2Facme.joinmarkt.com%2Fdiscord%2Fcallback&state=STATE",
  "applicationSync": null
}

inviteUrl uses that path when a client id and bot token are stored. The query is client_id, permissions (default 268437504), response_type=code, scope bot applications.commands, redirect_uri (the store redirectUri), and state.

Get Discord settings

GET /api/merchant/v1/stores/{storeId}/discord

Scope: discord:read. No body and no query parameters.

string

required

Store record id.

curl https://dash.joinmarkt.com/api/merchant/v1/stores/STORE_ID/discord \
  -H "Authorization: Bearer mk_live_<your_key>"

Update Discord settings

PATCH /api/merchant/v1/stores/{storeId}/discord
PUT   /api/merchant/v1/stores/{storeId}/discord

Scope: discord:write. JSON object. The path storeId is the store that is saved. A storeId property in the body is discarded. Client id, client secret, and bot token must all be present after the save, using stored values for any secret you omit. Saving sets enabled to true. Omit clientSecret or botToken to keep the stored secret. A string of only • characters keeps it as well. The bot token is checked with Discord. The client id must match the application id or that application’s bot user id. Guild ids are refreshed from Discord when that call succeeds, and commands are synced per guild.

string

required

Store record id.

string

Discord client id, trimmed, 5–64 characters.

string

Client secret, trimmed, 1–256 characters.

string

Bot token, trimmed, 1–256 characters.

boolean

Accepted on the body. The stored integration is saved with enabled true.

string[]

Up to 50 snowflakes. Each snowflake is 5–32 digits. Replaces the stored list when sent.

string | null

Role snowflake, or null to clear it.

string | null

Discord invite URL, max 500 characters, or null. An empty string clears it. The host must be discord.gg, discord.com, discordapp.com, or a host ending in .discord.com.

boolean

Checkout Discord link. Omitted values keep the stored flag, or true when nothing is stored yet.

{
  "clientId": "123456789012345678",
  "clientSecret": "secret",
  "botToken": "token",
  "authorizedDiscordUserIds": ["323456789012345678"],
  "customerRoleId": "423456789012345678",
  "customerInviteUrl": "https://discord.gg/joinmarkt",
  "showCheckoutLink": true
}

curl -X PATCH https://dash.joinmarkt.com/api/merchant/v1/stores/STORE_ID/discord \
  -H "Authorization: Bearer mk_live_<your_key>" \
  -H "Content-Type: application/json" \
  -d "{\"clientId\":\"123456789012345678\",\"clientSecret\":\"secret\",\"botToken\":\"token\"}"

400 messages from this handler:

`error`	When
`Invalid JSON`	Body is not JSON
`JSON body must be an object`	Body is not a JSON object
`No updatable Discord fields provided`	Object has no fields after `storeId` is removed
`Client ID, Client Secret, and Bot Token are required`	The three credentials are still incomplete
`Client ID does not match the Discord application for this bot token`	Client id matches neither the application id nor the bot user id
Discord `message`, or `Discord API <status>`	The bot-token lookup threw an `Error`. That covers a Discord rejection and a network failure. The HTTP status of this route stays `400`.
`Invalid bot token`	The bot-token lookup threw a value that is not an `Error`.
`Customer invite must be a Discord invite URL`	`customerInviteUrl` host is not a Discord invite host
`Must be a Discord snowflake ID`	A user id or role id is not 5–32 digits

Zod messages are joined with ; .

Errors

Failed responses use { "success": false, "error": "...", "code": "..." }. A 500 also includes errorId.

Status	Code	When
400	`BAD_REQUEST`	Invalid JSON, empty update, credentials, Discord validation, or field validation
401	`UNAUTHORIZED`	Missing, invalid, or revoked token. `error` is `Unauthorized`. Expired keys use `API key expired`.
403	`FORBIDDEN`	Key cannot access this store, or the scope / `configureStorefront` is missing. `error` is `Forbidden`.
404	`NOT_FOUND`	`Store not found`
429	`RATE_LIMITED`	More than 120 requests in 60 seconds for this client IP, on the shared `merchant-api` bucket. The limit is checked before the key. `error` is `Too many requests`.
500	`INTERNAL_ERROR`	Unexpected failure. `error` is `Failed to load Discord settings` or `Failed to update Discord settings`.

Get started

Analytics

Checkout

Dashboard

Merchant API

Merchant API playground

Orders

Public catalog

Reference

Webhooks

Discord settings

Get Discord settings

Update Discord settings

Errors

​Discord settings

​Get Discord settings

​Update Discord settings

​Errors

​Related

Discord settings

Get Discord settings

Update Discord settings

Errors

Related