Making changes to an existing subscription

After a subscription has been created on Gigs, a user may wish to make changes to certain attributes of the subscription, such as changing the plan or the SIM. This is enabled through an entity known as a subscription change.

A subscription change can be created to change a subscription's plan or SIM.

Subscription change process

The example steps below show the process for changing a subscription's SIM. The steps are identical for a plan change, the parameters supplied when creating the subscription change are the only difference. See the API docs for creating a new subscription change for more detail.

1. Create a new subscription change

To change the SIM associated to a subscription, create a new subscription change:

Create a subscription change

curl --request "POST" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptionChanges" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "sim": "auto",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "when": "now"
  }'

Note that specifying the desired sim to be "auto" will automatically allocate a new eSIM to the subscription. Should you wish to assign a specific SIM to the subscription, the SIM's unique identifier must be specified.

The response will contain the newly created subscription change:

A pending SIM subscription change

{
  "object": "subscriptionChange",
  "id": "sch_0SNlurA049MEWV3bE0SMtbIEJApp",
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    ...
  },
  "status": "pending",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "appliedAt": null,
  "createdAt": "2021-01-21T19:12:28Z",
  "scheduledAt": "2021-01-21T19:12:28Z"
}

2. Monitor subscription change status

After the subscription change has been created, the changes will be applied asynchronously once when the scheduled time is reached. Once a subscription change has been applied, the status will change from "pending" to "applied". Retrieve the subscription change to view its status:

Retrieve a subscription change

curl --request "GET" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptionChanges/${ID}" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}"

The subscription change (with its current status) will be returned:

An applied SIM subscription change

{
  "object": "subscriptionChange",
  "id": "sch_0SNlurA049MEWV3bE0SMtbIEJApp",
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    ...
  },
  "status": "applied",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "appliedAt": "2021-01-21T19:12:35Z",
  "createdAt": "2021-01-21T19:12:28Z",
  "scheduledAt": "2021-01-21T19:12:28Z"
}

Subscription change lifecycle

stateDiagram-v2 direction LR [*]-->pending pending-->applied pending-->failed applied-->[*] failed-->[*]

Pending

Indicates that the subscription change is waiting to be processed by our system. This will happen at the scheduledAt time.

Applied

Indicates that the subscription change has been applied successfully. The desired changes will be reflected on the subscription at this point.

Failed

Indicates that the subscription change could not be applied, in which case the subscription change will include a failureCode. Should you require assistance with a failed subscription change, please reach out to support@gigs.com.