Bulk toggle the current user’s subscription states

curl --request PATCH \
  --url https://apix.spotzee.com/api/client/subscriptions/me \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Spotzee-User-Token: <api-key>' \
  --data '
[
  {
    "subscription_id": 7,
    "state": 1
  }
]
'

import requests

url = "https://apix.spotzee.com/api/client/subscriptions/me"

payload = [
    {
        "subscription_id": 7,
        "state": 1
    }
]
headers = {
    "Authorization": "Bearer <token>",
    "X-Spotzee-User-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer <token>',
    'X-Spotzee-User-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify([{subscription_id: 7, state: 1}])
};

fetch('https://apix.spotzee.com/api/client/subscriptions/me', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://apix.spotzee.com/api/client/subscriptions/me"

	payload := strings.NewReader("[\n  {\n    \"subscription_id\": 7,\n    \"state\": 1\n  }\n]")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("X-Spotzee-User-Token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "results": [
    {
      "subscription_id": 7,
      "state": 1,
      "name": "Weekly newsletter",
      "channel": "email"
    }
  ],
  "nextCursor": "<string>",
  "prevCursor": "<string>",
  "limit": 123
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

Subscriptions

Bulk toggle the current user’s subscription states

Unavailable through the public API: current access controls reject this preference-centre operation. Use PATCH /users//subscriptions from a trusted server with a project secret key instead. The intended contract subscribes or unsubscribes the user bound to the calling session token across one or more subscription types. Designed for browser-side preference-centre opt-out flows: pass a publishable key (pk_…) plus a user session token (see POST /users/{userId}/sessions) in the X-Spotzee-User-Token header. Up to 100 toggles per request. Toggling to the current state is a no-op (idempotent).

Idempotent — pass an Idempotency-Key header to make safely retryable. On a replay the original response is returned with Idempotent-Replayed: true. See the API conventions guide for the full state machine, TTL, and mismatch behaviour.

PATCH

subscriptions

curl --request PATCH \
  --url https://apix.spotzee.com/api/client/subscriptions/me \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Spotzee-User-Token: <api-key>' \
  --data '
[
  {
    "subscription_id": 7,
    "state": 1
  }
]
'

import requests

url = "https://apix.spotzee.com/api/client/subscriptions/me"

payload = [
    {
        "subscription_id": 7,
        "state": 1
    }
]
headers = {
    "Authorization": "Bearer <token>",
    "X-Spotzee-User-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer <token>',
    'X-Spotzee-User-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify([{subscription_id: 7, state: 1}])
};

fetch('https://apix.spotzee.com/api/client/subscriptions/me', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://apix.spotzee.com/api/client/subscriptions/me"

	payload := strings.NewReader("[\n  {\n    \"subscription_id\": 7,\n    \"state\": 1\n  }\n]")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("X-Spotzee-User-Token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "results": [
    {
      "subscription_id": 7,
      "state": 1,
      "name": "Weekly newsletter",
      "channel": "email"
    }
  ],
  "nextCursor": "<string>",
  "prevCursor": "<string>",
  "limit": 123
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

Authorizations

Authorization

string

header

required

Project-scoped publishable key (pk_…). Safe for browser use. Allowed only on a strict allow-list of endpoints.

X-Spotzee-User-Token

string

header

required

Short-lived signed token that scopes the call to one user. Mint via POST /users/{userId}/sessions (sk_-only). Required alongside a publishable key on the preference-centre endpoints.

Body

application/json

Required array length: 1 - 100 elements

subscription_id

integer

required

Numeric subscription-type identifier to toggle.

Example:

7

state

required

Subscription state: 0 unsubscribed, 1 subscribed, 2 explicit double-opt-in. Reads return the current state; writes accept any of the three values to set it.

Available options:

0

Example:

1

Response

The refreshed subscription states for the user bound to the session.

Paginated response of UserSubscriptionList.

results

object[]

required

Page of results, ordered per the request’s sort and direction.

Hide child attributes

results.subscription_id

integer

required

Numeric subscription-type identifier.

Example:

7

results.state

required

Subscription state: 0 unsubscribed, 1 subscribed, 2 explicit double-opt-in. Reads return the current state; writes accept any of the three values to set it.

Available options:

0

Example:

1

results.name

string

required

Subscription-type name as shown to the caller.

Example:

"Weekly newsletter"

results.channel

string

required

Delivery channel the subscription type covers.

Example:

"email"

nextCursor

string | null

required

Opaque cursor for the next page. null when no further pages exist.

prevCursor

string | null

required

Opaque cursor for the previous page. null when on the first page.

limit

integer

required

Page size used to build this response.

Overview

Projects

Users

CRM

Source Sync

Events

Lists

Subscriptions

Templates

Campaigns

Journeys

Tags

API keys

Organisation

Webhooks

Billing recovery

Form definitions

Form submissions

Bulk toggle the current user’s subscription states

Authorizations

Body

Response