Pause Subscription

post

https://{Host}/v2/partnerProgram/pauseSubscription

Pauses a customer's active subscription (supplementary partner program) for a fixed date range.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Brands often need to temporarily suspend a member's subscription without canceling it outright, for example when a member goes on leave, disputes a charge, or asks for a break from a paid program. This API pauses a customer's active subscription to one or more supplementary partner programs for a specified date range. While paused, the customer's benefits under that program are suspended. Use the Resume Subscription API to reactivate the subscription.

An organization can pause up to 50 customers in a single request.

Example request

curl -X POST "https://eu.api.capillarytech.com/v2/partnerProgram/pauseSubscription" \
  -H "Authorization: Basic <base64-encoded-credentials>" \
  -H "Content-Type: application/json" \
  -d '{
    "pauseCustomers": [
      {
        "customer": {
          "id": 382741349
        },
        "pausePartnerPrograms": [
          {
            "partnerProgramName": "jotest08",
            "pauseStartDate": "2026-07-22T16:00:00+05:30",
            "pauseEndDate": "2026-07-22T16:30:00+05:30"
          }
        ]
      }
    ]
  }'

Prerequisites

Authentication: Basic or OAuth credentials
Access group resource: Write access to the Partner Program resource. For more information, see the access group documentation.

Body parameters

Field	Type	Required	Description
`pauseCustomers`	array	Required	Batches multiple customers into a single call, so an operational change affecting many subscribers can be applied at once. Max 50 entries per request.
`.customer`	object	Required	Identifies which customer's subscription to pause. Object containing exactly one of `id`, `mobile`, `email`, or `externalId`, whichever identifier you have on hand for this customer.
`..id`	integer	Conditional	The customer's unique ID.
`..mobile`	string	Conditional	The customer's mobile number.
`..email`	string	Conditional	The customer's email address.
`..externalId`	string	Conditional	The customer's external ID.
`.pausePartnerPrograms`	array	Required	Lets you pause more than one of the customer's supplementary programs in the same call. List of subscriptions to pause for this customer.
`..partnerProgramName`	string	Required	Identifies which of the customer's supplementary subscriptions to pause. A customer can be linked to more than one program, so only the one named here is affected. No length limit is enforced by this API. Find the partner program names a customer is currently linked to via the Get customer activity history API; filter its response for `partnerProgramType: SUPPLEMENTARY` and `linked: true`.
`..pauseStartDate`	string	Required	Defines when the pause window begins. The customer's benefits under this program stay active until this moment. ISO 8601 format with a UTC offset (`YYYY-MM-DDTHH:MM:SS+HH:MM`), for example `2026-08-01T00:00:00+05:30`. Must not be in the past. A malformed value is rejected with HTTP 400 and an empty response body.
`..pauseEndDate`	string	Required	Defines when the pause window ends. ISO 8601 format with a UTC offset (`YYYY-MM-DDTHH:MM:SS+HH:MM`). Must be after `pauseStartDate`. A malformed value is rejected with HTTP 400 and an empty response body.

API Quick Reference

pauseCustomers[] (array, required)
  customer (object, required)
    id (integer, conditional)
    mobile (string, conditional)
    email (string, conditional)
    externalId (string, conditional)
  pausePartnerPrograms[] (array, required)
    partnerProgramName (string, required)
    pauseStartDate (string, required)
    pauseEndDate (string, required)

Example response

{
  "pauseCustomers": [
    {
      "customer": {
        "id": 382741349,
        "mobile": "919876543210",
        "email": "[email protected]",
        "externalId": "X916215000000",
        "status": {
          "status": true,
          "message": "Customer successfully retrieved",
          "code": 1000
        }
      },
      "pausePartnerPrograms": [
        {
          "partnerProgramName": "jotest08",
          "pauseStartDate": "2026-07-22T10:30:00Z",
          "pauseEndDate": "2026-07-22T11:00:00Z",
          "partnerPauseStatus": {
            "status": true,
            "message": "Success",
            "code": 200
          }
        }
      ]
    }
  ],
  "warnings": []
}

Response parameters

Field	Type	Description
`pauseCustomers`	array	Echoes the requested customers, with a status attached to each subscription entry.
`.customer`	object	Object containing the full resolved customer record. Lets you confirm exactly which customer the pause was applied to.
`..id`	integer	The customer's unique ID, resolved from the identifier submitted in the request. Populated regardless of which of `id`/`mobile`/`email`/`externalId` was actually sent.
`..mobile`	string	The customer's mobile number, resolved the same way as `id` above.
`..email`	string	The customer's email address, resolved the same way as `id` above.
`..externalId`	string	The customer's external ID, resolved the same way as `id` above.
`..status`	object	Object containing the outcome of the customer lookup. If lookup fails (for example, an unrecognized mobile number), this failure status is copied onto every one of this customer's `partnerPauseStatus` entries below and the pause does not run.
`...status`	boolean	`true` if the customer was found, `false` otherwise. Check this before trusting `partnerPauseStatus` below.
`...message`	string	Human-readable outcome message, for example "Cannot find customer for provided mobile/external-id/e-mail/id".
`...code`	integer	Numeric status code for the lookup; `1000` indicates success.
`.pausePartnerPrograms`	array	Echoes the subscriptions submitted for this customer, with a pause outcome attached to each. Check each entry, since one customer's programs can succeed or fail independently.
`..partnerProgramName`	string	Echoes the partner program name that was submitted.
`..pauseStartDate`	string	Echoes the pause start date submitted, normalized to UTC (`Z`) regardless of the offset used in the request.
`..pauseEndDate`	string	Echoes the pause end date submitted, normalized to UTC (`Z`) regardless of the offset used in the request.
`..partnerPauseStatus`	object	Object containing the outcome of the pause request for this subscription. Check this to confirm the pause actually took effect.
`...status`	boolean	`true` if the pause succeeded, `false` otherwise.
`...message`	string	Human-readable outcome message; `"Success"` on success, or the message from Error and warning codes on failure.
`...code`	integer	Numeric status code; `200` indicates success. See Error and warning codes below for failure codes.
`warnings`	array	Always empty for this endpoint. No current condition populates it.
`errors`	array	Present only for a batch-level failure, for example exceeding the 50-customer limit. When present, no customer in the batch is processed.

Error and warning codes

Code	Error number	Type	Description
`ERR_PARTNER_PROGRAM`	2001	Error	Generic failure processing the pause event. HTTP 200 with an error on the affected subscription's `partnerPauseStatus`.
`ERR_PARTNER_PROGRAM_FIELD`	2002	Error	`partnerProgramName` is missing or empty. Set on the affected subscription's `partnerPauseStatus`. HTTP 200.
`ERR_PARTNER_PROGRAM_MAX_LIMIT_EXCEED`	2008	Error	More than 50 customers in `pauseCustomers`. HTTP 200 with a top-level `errors` entry; no customer in the batch is processed.
—	1012	Error	Customer not found for the given `id`/`mobile`/`email`/`externalId`. Set on the customer's `status`, and copied onto every `partnerPauseStatus` for that customer. HTTP 200.
`ERR_INVALID_PAUSE_DATE`	2030	Error	`pauseStartDate` or `pauseEndDate` is missing. HTTP 200.
`ERR_PAUSE_START_DATE_IN_PAST`	2031	Error	`pauseStartDate` is in the past. HTTP 200.
`ERR_PAUSE_END_BEFORE_START`	2032	Error	`pauseEndDate` is not after `pauseStartDate`. HTTP 200.
`ERR_PAUSE_SUBSCRIPTION_NOT_ACTIVE`	2033	Error	The customer's subscription to `partnerProgramName` is not currently active, so it cannot be paused. HTTP 200.
`ERR_PAUSE_ALREADY_IN_PROGRESS`	2034	Error	The subscription already has a pause that has started; it cannot be paused again until resumed. HTTP 200.
—	400	Error	Malformed `pauseStartDate`/`pauseEndDate` value (not parseable as an ISO 8601 timestamp). The request is rejected at the JSON layer with an empty response body, before any field is checked.

Responses

200

Successful response

400

Malformed request body (e.g. unparseable date)

Language

Credentials

Basic

base64

URL

Loading…

Response

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