# Transition Service

## Request

If you only require Transition API functionality, you can import the module separately to the main SDK.

For example:

```javascript
const { Transition } = require('n-membership-sdk');
const transitionSDK = new Transition(config);
```

## Table of Contents

* [Config](#config)
	* [How to obtain a key](#how-to-obtain-a-key)
* [Methods](#methods)
	* [getUserTransitionInfo](#getUserTransitionInfo)
	* [applyTransition](#applyTransition)
	* [cancelSubscription](#cancelSubscription)
	* [undoCancelSubscription](#undocancelsubscription)
	* [undoStepUp](#undoStepUp)
	* [scheduleStepUp](#scheduleStepUp)
	* [getDowngradeOptions](#getDowngradeOptions)
* [Documentation](#documentation)

## Config

* See common configuration options in the [README file](./README.doc)

```javascript
const config = new ProductionConfiguration({
	transitionApiKey: 'secret',
});
```

### `TransitionApiKey`

To obtain a key, do one of the following:

1. Check in Doppler for your app to see if a transition service API key already exists.
2. Contact #membership-support slack channel for a transition service key.

## Methods

### getUserTransitionInfo

```javascript
const transitionInfo = transitionSDK.getUserTransitionInfo(userId, offerId, countryCode, type);
```

| Parameters     | Required | Type   | Example | Description   |
| -------------- | -------- | -------| --------| ------------- |
| userId         | Yes      | String | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx | The user's ID. This can be retrieved from [graphql.getUserDetails](GRAPHQL.md#getUserDetails)  |
| offerId        | Yes      | String | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx | The ID of the offer to see transition options for |
| countryCode    | Yes      | String | GBR | Three letter ISO 3166-1 country code of the user |
| type           | Yes      | String | immediate | When to transition the user from current to requested offer (immediate / end of term) |
| isInStepUp     | No      | Boolean | true | Whether the user is in a "stepped up" state |

**Response**:
```javascript
{
	"subscriptionNumber": "A-XXXXXXXXXXX",
	"productName": "Standard FT.com",
	"currentTerm": "P1Y",
	"currentPrice": 270.00,
	"accountNumber": "A00000000",
	"balancePreview": -270.00,
	"currency": "GBP",
	"symbol": "£",
	"billingAccount": {
			"id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
			"userId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
			"currencyCode": "GBP",
			"status": "Active",
			"paymentMethod": {
					"id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
					"type": "CREDITCARD",
					"creditCard": {
							"expirationMonth": "1",
							"expirationYear": "2025",
							"type": "Visa",
							"maskedNumber": "************1111"
					}
			}
	},
	"upgradeType": "Upgrade",
	"upgradeTypeReason": "Upgrade supported",
	"upgradeOptions": [
			{
					"offerId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
					"term": "P1Y",
					"name": "FT.com Premium - RRP",
					"price": 356.00,
					"cost": 86.00,
					"annualSavings": 160.00
			}
	]
}
```

### applyTransition

- If a user has a subscription eligible for transition, this will update the subscription with a new offer.
- Call `getUserTransitionInfo` to get the transition options.

```javascript
const transitionInfo = transitionSDK.applyTransition(subscriptionNumber, offerId, term, type, countryCode, isSingleTerm, fulfilmentOption, hidePaymentMethod);
```

| Parameters          | Required | Type   | Example | Description   |
| ------------------- | -------- | -------| --------| ------------- |
| subscriptionNumber  | Yes      | String | A-XXXXXXXXXXX | User's subscription number. |
| offerId             | Yes      | String | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx | The ID of the offer to transition to |
| term | Yes | String | Annual | Payment/billing term - how often the user will make a payment |
| type           | Yes      | String | immediate | type of transition (immediate / end of term) |
| countryCode    | Yes      | String | GBR | Three letter ISO 3166-1 country code of the user |
| isSingleTerm    | No      | Boolean | false | Optional boolean parameter to indicate whether the new subscription is single term or auto renew |
| fulfilmentOption    | No      | String | HD | Two letter string to indicate delivery option for user |
| hidePaymentMethod    | No      | Boolean | true | Optional boolean parameter for single term users to indicate whether new payment method should be deleted |
| cancelFutureAmendments    | No      | Boolean | true | Boolean parameter defaulting to false to apply transitions for subscriptions with scheduled cancellations |

**Response**:
```javascript
{
	"subscriptionNumber": "A-SCXNCOHHNVX",
	"accountNumber": "A00435658",
	"subscriptionAfter": {
		"subNumber": "A-SCXNCOHHNVX",
		"productName": "Standard FT.com",
		"products": [
			"P1"
		],
		"price": {
			"currency": "GBP",
			"value": 270,
			"symbol": "£"
		},
		"term": "P1Y",
		"productType": "Digital"
	},
	"cost": {
		"currency": "GBP",
		"value": 270,
		"symbol": "£"
	},
	"effectiveStartDate": "2019-09-19",
	"renewalDate": "2020-09-19"
}
```

### cancelSubscription

```javascript
const cancelSubscription = subscriptionSdk.cancelSubscription(userId, subscriptionNumber, cancellationReason, isCustomerServiceAgent);
```

| Parameters             | Required | Type    | Example           | Description |
| ---------------------- | ---------| ------- | ----------------- | ----------- |
| userId                 | yes      | String  | 'decafbc4-335...' | The user's ID |
| subscriptionNumber     | yes      | String  | 'A-SRYNVS60HWA'   | The subscription reference number |
| cancellationReason     | no       | String  | 'not-read-enough' | The user's  reason for cancelling (freetext, purely informative, not used by systems) |
| isCustomerServiceAgent | no       | Boolean | true              | Whether this is a customer service agent doing the cancellation. Can be based off of req.cookies.FT_SessionHelpdesk. |
| cancellationEffectiveDate | no    | String  | '2020-11-25'      | The date when the cancellation should take effect |
| sendEmail              | no       | Boolean | false             | Whether to send the customer care email that is sent after a user cancels their subscription
| cancellationType       | no       | String  | 'endOfTerm'       | Type of cancellation, defaults to 'endOfTerm', possible values: endOfTerm|ImmediateNoRefund|ImmediatePartialRefund|ImmediateFullRefund |

**Response**:
```javascript
	{
		success: true,
		cancellationEffectiveDate: '2012-02-16T00:00:00.000Z',
		subscriptionKey: 'A-SRYNVS60HWA'
	}
```

### undoCancelSubscription

```javascript
const undoCancelSubscription = subscriptionSdk.undoCancelSubscription(userId, subscriptionNumber, isCustomerServiceAgent);
```

| Parameters             | Required | Type    | Example           | Description |
| ---------------------- | ---------| ------- | ----------------- | ----------- |
| userId                 | yes      | String  | 'decafbc4-335...' | The user's ID |
| subscriptionNumber     | yes      | String  | 'A-SRYNVS60HWA'   | The subscription reference number |
| isCustomerServiceAgent | no       | Boolean | true              | Whether this is a customer service agent doing the cancellation. Can be based off of req.cookies.FT_SessionHelpdesk. |

**Response**:
```javascript
	{
		success: true
	}
```


### undoStepUp

```javascript
const undoStepUpDetails = subscriptionSdk.undoStepUp(subscriptionNumber);
```

| Parameters             | Required | Type    | Example           | Description |
| ---------------------- | ---------| ------- | ----------------- | ----------- |
| subscriptionNumber     | yes      | String  | 'A-SRYNVS60HWA'   | The subscription reference number  |


**Response**:
```javascript
	{
			"subscriptionAfter": {
					"subNumber": "A-SXXZDODHPK3",
					"productName": "Premium FT.com",
					"products": [
							"P2"
					],
					"price": {
							"currency": "GBP",
							"value": 43,
							"symbol": "£"
					},
					"term": "P1M"
			},
			"stepUpEffectiveDate": "2020-06-11"
	}
```

### scheduleStepUp

```javascript
const stepUpDetails = subscriptionSdk.scheduleStepUp(userDetails);
```

| Parameters             | Required | Type    | Example           | Description |
| ---------------------- | ---------| ------- | ----------------- | ----------- |
| subscriptionNumber     | yes      | String  | 'A-SRYNVS60HWA'   | The subscription reference number  |
| offerId                | yes      | String  | 'UUID'            | The offer ID to change to          |
| countryCode            | yes      | String  | 'GBR'             | The user's country code            |
| term                   | yes      | String  | 'P1M'             | The chosen offer term              |
| minDaysToStepUp        | yes      | String  | 90                | Days until the step up takes place |

**Response**:
```javascript
	{
			"subscriptionAfter": {
					"subNumber": "A-SXXZDODHPK3",
					"productName": "Premium FT.com",
					"products": [
							"P2"
					],
					"price": {
							"currency": "GBP",
							"value": 43,
							"symbol": "£"
					},
					"term": "P1M"
			},
			"stepUpEffectiveDate": "2020-06-11"
	}
```

### getDowngradeOptions

```javascript
const getDowngradeOptions = subscriptionSdk.getDowngradeOptions(subscriptionNumber, userInStepUp);
```

| Parameters             | Required | Type    | Example           | Description |
| ---------------------- | ---------| ------- | ----------------- | ----------- |
| subscriptionNumber     | yes      | String  | 'A-SRYNVS60HWA'   | The subscription reference number  |
| checkForStepUpOptions  | no       | Boolean | true              | Whether to return options for users in stepup  |
**Standard responses**:


```javascript
		{
			"offerId": "some-uuid-goes-here",
			"percent": 25,
			"friendlyName": "Friendly Offer Name"
		}
```

## Documentation

| Documentation     | Description | Owner |
| -------------- | -------- | -------- |
| [Transition API](https://subs-transition-svc-us-prod.memb.ft.com/swagger) | Swagger documentation for the Transition API | FT Core - Membership |
| [Transitions Restrictions](https://confluence.ft.com/display/MEMB/Transitions+Restrictions)         | Restrictions applied by the backend when a user try to transit to a different plan | FT Core - Membership |