TBBNMerchantDocs
Available

Notifications

get/v1/notifications

Your notifications, newest first — what happened and where it opens

curl -X GET https://api.tbbnetwork.com/v1/notifications \
  -H "Authorization: Bearer <session access token>" \

Response (200)

Example 200 response
[
  {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "type": "type",
    "title": "title",
    "body": null,
    "href": null,
    "readAt": "2026-07-01T12:00:00Z",
    "createdAt": "2026-07-01T12:00:00Z"
  }
]
get/v1/notifications/unread-count

How many of your notifications are unread

curl -X GET https://api.tbbnetwork.com/v1/notifications/unread-count \
  -H "Authorization: Bearer <session access token>" \

Response (200)

FieldTypeRequired
countinteger—
Example 200 response
{
  "count": 1
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}
post/v1/notifications/read-all

Mark all your notifications read

curl -X POST https://api.tbbnetwork.com/v1/notifications/read-all \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \

Response (201)

FieldTypeRequired
countinteger—
Example 201 response
{
  "count": 1
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}
post/v1/notifications/{id}/read

Mark a notification read

curl -X POST https://api.tbbnetwork.com/v1/notifications/{id}/read \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \

Parameters

idpathrequired

Response (201)

FieldTypeRequired
idstring (uuid)—
typestring—
titlestring—
bodystringnull—
hrefstringnull—
readAtstring,null (date-time)—
createdAtstring (date-time)—
Example 201 response
{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "type": "type",
  "title": "title",
  "body": null,
  "href": null,
  "readAt": "2026-07-01T12:00:00Z",
  "createdAt": "2026-07-01T12:00:00Z"
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}
get/v1/notifications/unsubscribe

Public unsubscribe-center status (no auth) — pre-fills which categories an email is already opted out of. `token` (from an emailed unsubscribe link) only improves this prefill UX; without a valid one the form just shows nothing pre-ticked, since unsubscribe itself never requires one. 

curl -X GET https://api.tbbnetwork.com/v1/notifications/unsubscribe \
  -H "Authorization: Bearer sk_sandbox_..." \

Parameters

emailqueryrequired
tokenqueryoptional

Response (200)

FieldTypeRequired
optedOutCategoriesstring[]—
Example 200 response
{
  "optedOutCategories": [
    "ACCOUNT"
  ]
}
post/v1/notifications/unsubscribe

Opt an email out of the given categories (no auth — this is how every public unsubscribe link works, logged in or not). SECURITY mail can never be opted out of. Submitting an empty array re-subscribes to everything. 

curl -X POST https://api.tbbnetwork.com/v1/notifications/unsubscribe \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "you@example.com",
  "categories": [
    "ACCOUNT"
  ]
}'

Request body

FieldTypeRequired
emailstring (email)yes
categoriesstring[]yes

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}
get/v1/notifications/preferences

The authenticated, stronger override the public unsubscribe form doesn't expose — the caller's own email is resolved server-side from their principal, never client-supplied. 

curl -X GET https://api.tbbnetwork.com/v1/notifications/preferences \
  -H "Authorization: Bearer <session access token>" \

Response (200)

FieldTypeRequired
emailstringnull—
allNonEssentialEmailOptOutboolean—
optedOutCategoriesstring[]—
Example 200 response
{
  "email": null,
  "allNonEssentialEmailOptOut": false,
  "optedOutCategories": [
    "ACCOUNT"
  ]
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}
patch/v1/notifications/preferences

Set the authenticated caller's own category opt-outs, plus the allNonEssentialEmailOptOut master switch (checked first, ahead of any per-category opt-out, and automatically covers a category added in the future). 

curl -X PATCH https://api.tbbnetwork.com/v1/notifications/preferences \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "categories": [
    "ACCOUNT"
  ],
  "allNonEssentialEmailOptOut": false
}'

Request body

FieldTypeRequired
categoriesstring[]yes
allNonEssentialEmailOptOutbooleanyes

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}