Update Subscriber’s State

The UpdateSubscriberState API in OCS.io allows for updating the state of a subscriber using their Ref ID or External ID, providing essential functionality for managing subscriber states and their associated reasons and validity periods.

API Overview

Fields Required for Subscriber State update

Field	Description
subscriber	ID (Ref ID / External ID) of the Subscriber.
state.state	State of the subscriber.
state.stateReason	Reason for the subscriber’s state.
state.stateValidFrom	Date from when the state is valid.
state.pending	Indicates whether the state is pending, with a future state valid from date.
subordinateUpdated	Indicates whether updates to the state should also apply to subordinate entities such as all Subscriptions.

Field

Description

subscriber

ID (Ref ID / External ID) of the Subscriber.

state.state

State of the subscriber.

state.stateReason

Reason for the subscriber’s state.

state.stateValidFrom

Date from when the state is valid.

state.pending

Indicates whether the state is pending, with a future state valid from date.

subordinateUpdated

Indicates whether updates to the state should also apply to subordinate entities such as all Subscriptions.

Detailed API documentation and endpoint specifics are available here.

Request Validations

The following validations are performed when updating a subscriber’s state:

Subscriber must be provided in the request, it must be already created in the system and must not be in Deactivated State.
State Reason must be provided in the request, it must be configured in the system for given State.

Update Subscriber’s State Examples

1. Update Subscriber’s State to Suspended

Use the following request’s body to update a subscriber’s state to Suspended:

{
  "requestId": "{{$guid}}",
  "subscriber": {
    "externalId": "subscriber_external_id"
  },
  "state": {
    "state": "SUSPENDED",
    "stateReason": "dfltSuspended",
    "stateValidFrom": "2024-05-01T00:00:00+02:00"
  }
}

The outcome of the API call is as follows:

The state of the subscriber with external ID subscriber_external_id is updated to SUSPENDED.
The reason for the state change is dfltSuspended.
The new state is valid from 2024-05-01T00:00:00+02:00.

2. Update Subscriber’s State to Suspended with Pending

Use the following request’s body to update a subscriber’s state to Suspended with Pending:

{
  "requestId": "{{$guid}}",
  "account": {
    "externalId": "account_external_id"
  },
  "state": {
    "state": "SUSPENDED",
    "stateReason": "dfltSuspended",
    "stateValidFrom": "2024-05-01T00:00:00+02:00",
    "pending": true
  }
}

The outcome of the API call is as follows:

The state of the subscriber with external ID subscriber_external_id is planned to be updated to SUSPENDED.
The reason for the state change is dfltSuspended.
The new state is valid from 2024-05-01T00:00:00+02:00.
The state change is pending and will not be applied until it is confirmed or cancelled.

3. Confirm Pending Subscriber’s State

Use the following request’s body to confirm a pending subscriber’s state update:

{
  "requestId": "{{$guid}}",
  "subscriber": {
    "externalId": "subscriber_external_id"
  },
  "state": {
    "state": "SUSPENDED",
    "stateReason": "dfltSuspended",
    "stateValidFrom": "2024-04-15T00:00:00+02:00",
    "pending": false
  }
}

The outcome of the API call is as follows:

The pending state of the subscriber with external ID subscriber_external_id is confirmed.
The provided reason for the state change dfltSuspended is validated against scheduled record.
The new state is valid from 2024-04-15T00:00:00+02:00.
The state change is no longer pending and has been applied.

4. Cancel Pending Subscriber’s State

Use the following request’s body to cancel a pending subscriber’s state update:

{
  "requestId": "{{$guid}}",
  "subscriber": {
    "externalId": "subscriber_external_id"
  },
  "state": {
    "state": "SUSPENDED",
    "stateReason": "dfltSuspended",
    "stateValidFrom": null,
    "pending": true
  }
}

The outcome of the API call is as follows:

The pending state of the subscriber with external ID subscriber_external_id is cancelled.
The provided reason for the state change dfltSuspended is validated against scheduled record.
The previously planned state change is cancelled and will not be applied.