Update Customer’s State

The UpdateCustomerState API in OCS.io allows for updating the state of a customer, providing flexibility to manage customer statuses effectively.

API Overview

Fields Required for Customer State update

Field Description

customer

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

state.state

State of the customer.

state.stateReason

Reason for the customer’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 Accounts with all Subordinate Accounts, Subscribers, and all Subscriptions.
Detailed API documentation and endpoint specifics are available here.

Request Validations

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

Update Customer’s State Examples

1. Update Customer’s State to Suspended

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

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

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

{
  "requestId": "{{$guid}}",
  "customer": {
    "externalId": "customer_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 customer with external ID customer_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 Customer’s State

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

{
  "requestId": "{{$guid}}",
  "customer": {
    "externalId": "customer_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 customer with external ID customer_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 Customer’s State

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

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