Update Subscription Details

post https://{host}/v2/customers/{userId}/subscriptions

You can also use this API endpoint to update subscription details: /lookup/subscriptions?{queryParams}

This API allows updating (opt-in or opt-out) subscription status of transactional and bulk messaging services for a customer.

Transaction Messages: These are personalized messages sent to a customer instantly. For example, a new transaction details, points or coupon redeemed, send birthday or anniversary wishes and so on.
Bulk Messages: These are promotion messages sent to a list of customers. For example, through campaigns.

📘
Note
Make sure communication channels like Mobile and Email are configured in InTouch for subscription.

API Endpoint example

https://eu.api.capillarytech.com/v2/customers/565039505/subscriptions?format=json

curl --location --globoff 'https://eu.api.capillarytech.com/v2/customers/{userId}/subscriptions?format=json' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Basic cnV0dWphX2NhcGlsbGFyeTpkMTNlMmEyYmY4OWRkNDAxN2U0Y2EwOTk1MGI0NzZjNg==' \
--header 'Cookie: _cfuvid=rxRpkG0ZaHhqCspOGoNMJ1Zw3B.833ToyoOw1GvD6HU-1750747343765-0.0.1.1-604800000' \
--data '
{
  "communicationId": -1,
  "campaignId": -1,
  "reason": "This is V2 subscription api",
  "scope": {
    "scope": "USER",
    "subScope": "NONE"
  },
  "subscriptions": [
    {
      "channel": "EMAIL",
      "priority": "BULK",
      "type": "OPTOUT",
      "orgUnitId": 200031782,
      "sourceName": "FACEBOOK",
      "accountId": "01"
    },
    {
      "channel": "MOBILE",
      "accountId": "01",
      "priority": "BULK",
      "type": "OPTIN",
      "orgUnitId": 200031782,
      "sourceName": "FACEBOOK"
    },
    {
      "channel": "EMAIL",
      "accountId": "01",
      "priority": "TRANS",
      "type": "OPTIN",
      "orgUnitId": 200031782,
      "sourceName": "FACEBOOK"
    },
    {
      "channel": "MOBILE",
      "accountId": "01",
      "priority": "TRANS",
      "type": "OPTOUT",
      "orgUnitId": 200031782,
      "sourceName": "FACEBOOK"
    }
  ]
}
'

Request Body Parameters

Parameter (Parameters marked with * are mandatory)	Datatype	Description
communicationId	long	Communication ID. Pass `-1` when not applicable or when updating general subscription preferences.
campaignId	long	Campaign ID. Pass `-1` when not applicable.
reason	string	Reason for updating the subscription.
scope	object	Scope details for the subscription update.
scope	string	Main scope of the subscription. Example: `USER`.
subScope	string	Sub-scope of the subscription. Example: `NONE`.
subscriptions*	array	List of subscription objects defining detailed preferences. At least one object is required.
channel*	enum	Communication channel. Values: `MOBILE`, `EMAIL`, `wechat`, `whatsapp`, `ios`, `android`, `line`.
accountId*	string	Account identifier for the given channel.
priority*	enum	Type of message. `TRANS` for transactional/personalized messages, `BULK` for campaign or promotional messages.
type*	enum	Subscription type. `OPTIN` to subscribe, `OPTOUT` to unsubscribe.
orgUnitId*	long	Org unit or concept ID where the subscription should be updated.
sourceName	enum	Source in which the identifier is registered. Values: `INSTORE`, `FACEBOOK`, `WEB_ENGAGE`, `WECHAT`, `MARTJACK`, `TMALL`, `TAOBAO`, `JD`, `ECOMMERCE`, `WEBSITE`, `LINE`, `MOBILE_APP`.

Response Parameter

Parameter	Type	Description
scope.scope	String	The scope of the subscription (e.g., "USER").
scope.subScope	String	The sub-scope of the subscription (e.g., "NONE").
subscriptions	Array of Objects	A list of subscription objects.
campaignId	Integer	The ID of the campaign associated with the subscription.
communicationId	Integer	The ID of the communication associated with the subscription.
reason	String	A description or reason for the response.
warnings	Array	A list of warnings, if any.

Subscription Object Details:

Each object in the subscriptions array has the following parameters:

Parameter	Type	Description
channel	String	The communication channel (e.g., "EMAIL", "MOBILE").
accountId	String	The account ID associated with the subscription.
priority	String	The priority level of the subscription (e.g., "BULK", "TRANS").
type	String	The subscription type (e.g., "OPTOUT", "OPTIN").
orgUnitId	Integer	The organizational unit ID associated with the subscription.
sourceName	String	The source of the subscription (e.g., "FACEBOOK").

Note: An update to the subscription status of a customer doesn’t generate or trigger event notifications.

{
    "scope": {
        "scope": "USER",
        "subScope": "NONE"
    },
    "subscriptions": [
        {
            "channel": "EMAIL",
            "accountId": "01",
            "priority": "BULK",
            "type": "OPTOUT",
            "orgUnitId": 200031782,
            "sourceName": "FACEBOOK"
        },
        {
            "channel": "MOBILE",
            "accountId": "01",
            "priority": "BULK",
            "type": "OPTIN",
            "orgUnitId": 200031782,
            "sourceName": "FACEBOOK"
        },
        {
            "channel": "EMAIL",
            "accountId": "01",
            "priority": "TRANS",
            "type": "OPTIN",
            "orgUnitId": 200031782,
            "sourceName": "FACEBOOK"
        },
        {
            "channel": "MOBILE",
            "accountId": "01",
            "priority": "TRANS",
            "type": "OPTOUT",
            "orgUnitId": 200031782,
            "sourceName": "FACEBOOK"
        }
    ],
    "campaignId": -1,
    "communicationId": -1,
    "reason": "This is V2 subscription api",
    "warnings": []
}

API specific error code

Error code	Description	Reason
1012	Cannot find customer for provided mobile/external-id/e-mail/id	Mobile/Email id/External-id invalid
1000	Customer Subscriptions could not be added	Invalid customer details or missing data
400	Bad Request	The request is malformed or missing required parameters (e.g., invalid format).
401	Unauthorized	Authentication failed or the user lacks valid credentials.
500	Internal Server Error	An unexpected server error occurred.

Language

Credentials

Basic

base64

URL

Click Try It! to start a request and see the response here!