# 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][retrieve-a-subscription-change].

<Note type="info">

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

</Note>

## 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][create-a-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]:

<CodeGroup title="Create a subscription change">

```shell
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"
  }'
```

</CodeGroup>

<Note type="info">

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.

</Note>

The response will contain the newly created subscription change:

<CodeGroup title="A pending SIM subscription change">

```json
{
  "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"
}
```

</CodeGroup>

### 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][retrieve-a-subscription-change] to view its status:

<CodeGroup title="Retrieve a subscription change">

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

</CodeGroup>

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

<CodeGroup title="An applied SIM subscription change">

```json
{
  "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"
}
```

</CodeGroup>

## Subscription change lifecycle

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

### Initiated

Indicates that the subscription change is waiting for another action (such as an invoice payment) to succeed before the subscription change can be processed.

### 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][].

## Updating a subscription directly

Some properties of a subscription can be updated directly without the use of a subscription change.

### User Address

In some regions this address is used as a service address for the subscription. It should be kept up to date for regulatory compliance and correct tax calculations.

You can update the subscription directly with the `userAddress` property and the ID of the [new user address][create-a-user-address].

<CodeGroup title="Update subscription service address">

```shell
curl --request "PATCH" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptions/${SUBSCRIPTION_ID}" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT"
  }'
```

</CodeGroup>

<Note type="info">

Once a subscription has a user address, it cannot be removed, only updated to a different user address. This feature is only available for active subscriptions.

</Note>

[create-a-subscription-change]: /core/subscription-changes#create-a-subscription-change
[retrieve-a-subscription-change]: /core/subscription-changes#retrieve-a-subscription-change
[create-a-user-address]: /core/user-addresses#create-a-user-address
[support@gigs.com]: mailto:support@gigs.com