Update Account’s State

The UpdateAccountState API in OCS.io allows for the seamless modification of an account’s state, providing flexibility to align with evolving business needs.

API Overview

Fields Required for Updating Account’s State

The following table lists and describes the fields required to update an account’s state through the UpdateaccountState API:

Field	Description
account	ID (Ref ID / External ID) of the Account.
state.state	State of the account.
state.stateReason	Reason for the account’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 Subordinate Accounts, Subscribers, and all Subscriptions.

Field

Description

account

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

state.state

State of the account.

state.stateReason

Reason for the account’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 Subordinate Accounts, Subscribers, and all Subscriptions.

Detailed API documentation and endpoint specifics are available here.

Request Validations

The following validations are performed when updating an account’s state:

Account 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 Account’s State Examples

1. Update Account’s State to Suspended

Use the following request’s body to update an account’s state to Suspended:

{
  "requestId": "{{$guid}}",
  "account": {
    "externalId": "account_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 account with external ID account_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 Account’s State to Suspended with Pending

Use the following request’s body to update an account’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 account with external ID account_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 Account’s State

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

{
  "requestId": "{{$guid}}",
  "account": {
    "externalId": "account_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 account with external ID account_external_id is confirmed to be updated to SUSPENDED.
The reason for the state change is dfltSuspended.
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 Account’s State

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

{
  "requestId": "{{$guid}}",
  "account": {
    "externalId": "account_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 account with external ID account_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.