Update Subscription’s State

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

API Overview

Fields Required for Subscription State update

Field Description

subscription

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

state.state

State of the subscription.

state.stateReason

Reason for the subscription’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.
Detailed API documentation and endpoint specifics are available here.

Request Validations

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

Update Subscription’s State Examples

1. Update Subscription’s State to Suspended

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

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

Use the following request’s body to update a subscription’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 subscription with external ID subscription_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 Subscription’s State

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

{
  "requestId": "{{$guid}}",
  "subscription": {
    "externalId": "subscription_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 subscription with external ID subscription_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 Subscription’s State

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

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