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 in * are mandatory)	Datatype	Description
userId*	long	Unique ID of the customer whose subscription details you want to modify
mobile/email/external_id/id*	string	Provide any of the customer identifiers to update subscription details.
channel	enum	Pass the communication channel that you want to update. Values: `mobile`, `email`, `wechat`, `whatsapp`, `ios`, `android`, and `line`.
priority	enum	Type of service for which you want to modify the subscription details.`TRANS` for personalized messages and `BULK` for campaign or bulk messages
type	enum	`OPTIN` to subscribe and `OPTOUT` to unsubscribe.
orgUnitId	long	Concept ID or org unit ID to update subscription details of for an org unit.
sourceName	enum	Source in which the identifier is registered. Values: `INSTORE`, `FACEBOOK`, `WEB_ENGAGE`, `WECHAT`, `INSTORE`, `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!