# Upzelo Configuration Object

Upzelo requires a configuration object to be passed into it to initialise. 

It can be passed into `window.upzelo.init` and/or `window.upzelo.open`.

{% hint style="info" %}
Parameters in <mark style="color:red;">red</mark> are required. <mark style="color:yellow;">Yellow</mark> is required conditionally.
{% endhint %}

## Configuration Parameters

<details>

<summary><mark style="color:red;">customerId</mark></summary>

**Type**: `String`.

The payment provider ID for the currently logged-in user.

```javascript
customerId: 'cus_1234',
```

</details>

<details>

<summary><mark style="color:red;">subscriptionId</mark></summary>

**Type**: `String`

The payment provider ID of the subscription that is to be modified or actioned against.

```javascript
subscriptionId: 'sub_1234',
```

</details>

<details>

<summary><mark style="color:yellow;">hash</mark></summary>

**Type**: `String`

**Required**: If `mode` = `full`

**Usage**: This is for providing the server-side hash

```javascript
hash: 'bd9d2eca979333103b3d93a80e8efcbd0f8421813fdb9feefffde2206b4115e8',
```

</details>

<details>

<summary>addressId (Recharge Only)</summary>

**Type**: `String`

**Required**: No

**Usage**: **This is only used for Recharge**. This is used to be able to apply offers or cancel all subscriptions under a single address.

```javascript
addressId: '234897sdjknf',
```

</details>

<details>

<summary>mode</summary>

**Type**: `String`

**Options**: `live`, `test`

**Default**: `live`

**Usage**: Test mode will utilise the data available while using Upzelo's test mode. This means that it will use Flows, Audiences, and payment provider data that has been imported using your test key.

```javascript
mode: 'test',
```

</details>

<details>

<summary>type</summary>

**Type**: `String`

**Options**: `full`, `minimal`

**Default**: `full` if `hash` supplied, otherwise `minimal`

**Usage**: This determines if you want Upzelo to action things on your behalf with your payment provider. If set to minimal, offboarding requests will appear in the Requests section of the dashboard for you to action yourself.

```javascript
type: 'minimal',
```

</details>

<details>

<summary>selector</summary>

**Type**: `String`

**Default**: `button#cancel, a#cancel`

**Usage**: A CSS selector to select which elements on the page should launch Upzelo when clicked.

```javascript
selector: 'button#cancelButton, a.endSubscription
```

</details>

<details>

<summary>provider</summary>

Type: String

Usage: Only set this if you have been advised by Upzelo support to do so.

```javascript
provider: 'stripe',
```

</details>

## Callbacks

There are some available callbacks that you can use to further extend the functionality of Upzelo. They run alongside what Upzelo does and do not replace that functionality, therefore they are optional.

{% hint style="info" %}
Where a callback has the `responses` argument, it will be an array of Actions that the user saw (not all of the actions in the Flow), and whether an Action was accepted or not.

You should always check if it is defined before using it as there are a small number of cases where it might not be.
{% endhint %}

<details>

<summary>onCancel</summary>

**Type**: `Function`

**Default**: `null`

**Arguments**: `{ customerId, subscriptionId, responses }`

**Usage**: A function that runs at the end of a flow when the customer confirms that they wish to cancel.

```
onCancel: ({ customerId, subscriptionId, responses }) => {
    window.location.replace(`https://www.example.com/goodbye?customer=${customerId}`);
}
```

</details>

<details>

<summary>onSave</summary>

**Type**: `Function`

**Default**: `null`

**Arguments**: `{ customerId, subscriptionId, responses, couponId, offerType, externalCouponId, planId, externalPlanId, offerDuration, offerDurationType }`

Usage: A function that runs when a customer accepts an offer.

You can use `offerType` to change how you respond based on the offer type. Possible values are:

* `discount`
* `pause`
* `trial_extension`
* `free_period`
* `plan_change`

```javascript
onSave: ({ customerId, offerType }) => {
    console.log(customerId, offerType);
    alert("Thanks for staying with us. Your account has been updated");
},
```

</details>

<details>

<summary>onClose</summary>

**Type**: `Function`

**Default**: `null`

**Arguments**: `{ customerId }`

**Usage**: A function that runs when the user closes the modal via the `X` button, clicking outside of it, or pressing the `esc` key.

```
onClose: ({ customerId }) => {
    apiCall.logAbandonedSession(customerId);
},
```

</details>

<details>

<summary>onError</summary>

**Type**: `Function`

**Default**: `null`

**Arguments**: `{ customerId, error }`

**Usage**: If Upzelo throws an error message to the user, it is available through this callback

```javascript
onError: ({ error }) => {
    console.log(error);
},
```

</details>