# User management

User Management is a comprehensive service designed to assist third-party applications in efficiently handling user-related operations. This service supports user activation, password resets, subscription management, and order handling tasks, offering a standard interface with user-based authentication. It ensures secure and seamless management of user information hosted by Digital River.

## User management details

The table below lists the various user management tasks that third-party applications can perform using specific request and response types. This collection of operations ensures seamless user management, from activation and password resets to subscription and order handling.

| Task                                                                   | Request Type                   | Response Type                   |
| ---------------------------------------------------------------------- | ------------------------------ | ------------------------------- |
| Activate a user                                                        | `ActivateShopperRequest`       | `ActivateShopperResponse`       |
| Inactivate a user                                                      | `InactivateShopperRequest`     | `InactivateShopperResponse`     |
| Reset user password                                                    | `ResetShopperPasswordRequest`  | `ResetShopperPasswordRequest`   |
| Retrieve user information                                              | `GetShopperRequest`            | `GetShopperResponse`            |
| Add/modify users, including updating the user's default billing method | `AddUpdateShopperRequest`      | `AddUpdateShopperResponse`      |
| Cancel a user's subscription                                           | `CancelSubscriptionRequest`    | `CancelSubscriptionResponse`    |
| [Activate a user's subscription](#activate-a-users-subscription)       | `ActivateSubscriptionRequest`  | `ActivateSubscriptionResponse`  |
| Modify a subscription's renewal date                                   | `ModifyRenewalDateRequest`     | `ModifyRenewalDateResponse`     |
| Modify a subscription's renewal mechanism (manual or auto)             | `ModifyAutoRenewalRequest`     | `ModifyAutoRenewalResponse`     |
| Search for a user's orders and get the order details                   | `SearchOrderRequest`           | `SearchOrderResponse`           |
| Cancel a user's order                                                  | `CancelOrderRequest`           | `CancelOrderResponse`           |
| Return a user's order                                                  | `ReturnOrderRequest`           | `ReturnOrderResponse`           |
| Add or modify extended attributes on a user's order and line items     | `UpdateOrderAttributesRequest` | `UpdateOrderAttributesResponse` |

All tasks mentioned above can use user-based basic authentication. You can configure this authentication per client integration. All the complex types mentioned above inherit `CommonRequest` and `CommonResponse`.

## Activate a user's subscription

When you activate a user's subscription, you must meet the necessary validations to enable the subscription effectively. This process requires specific information about the user and their subscription details. It involves multiple checks to confirm the validity and ownership of the subscription, the associated product, and the activation key. Here, we outline the steps and validation tasks necessary for successful subscription activation and handling potential errors that may arise during the process.

To activate a subscription, you must send an `ActivateSubscriptionRequest` to the relevant endpoint. This request must include all necessary details, such as the user ID, subscription ID, product information, and activation date.

Here is a sample `ActivateSubscriptionRequest`:

{% tabs %}
{% tab title="Activate subscription request example" %}

```json
{
	"ActivateSubscriptionRequest": {
		"shopperKey": {
			"userID": "26593336708",
			"siteID": "tmamer"
		},
		"SubscriptionID": "4343240414",
		"subscriptionProductKey": {
			"productID": "55551800",
			"companyID": "tmamer",
			"externalReferenceID": ""
		},
		"activationDate": "2009-02-03",
		"renewalDate": "2009-08-08",
		"subscriptionKey": {
			"subscriptionID": "463301709"
		}
	}
}
```

{% endtab %}
{% endtabs %}

Remember to verify all validation tasks for successful subscription activation to avoid errors. Refer to the validation table for specific requirements.

There are restrictions for an `ActivateSubscriptionRequest`. When sending an `ActivateSubscriptionRequest`, the request does not verify factors such as payment type and auto/manual. The following table lists the validations that occur during an `ActivateSubscriptionRequest`.

| Validation Task                                                                                                          | Error Information                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The user identified in the `shopperKey` element is valid                                                                 | <p><strong>Error Code</strong>: 200<br><strong>Message</strong>: Shopper Not Found</p>                                                                                                                                                                                                                                                                                                                                                                                            |
| The subscription identified in the 'SubscriptionID\` element is valid                                                    | <p><strong>Error Code</strong>: 710<br><strong>Message</strong>: Subscription order \[888888] pending activation was not found<br><strong>Details</strong>: Where the <code>\<SubscriptionID></code> element passes the <code>888888</code> value.</p>                                                                                                                                                                                                                            |
| The specified `Subscription` belongs to the given user                                                                   | <p><strong>Error Code</strong>: 720<br><strong>Message</strong>: Subscription order \[888888] does not belong to shopper \[loginID =12345, externalReferenceID = 54321]<br><strong>Details</strong>: Where the<code>\<SubscriptionID></code> element passes the <code>888888</code> value. The values <code>12345</code> and <code>54321</code> are the Digital River <code>loginID</code> and <code>externalReferenceID</code> for the shopper.</p>                              |
| The specified Subscription contains a given product                                                                      | <p><strong>Error Code</strong>: 730<br><strong>Message</strong>: No subscription products found for the order \[888888]<br><strong>Details</strong>: Where<code>888888</code> is the value passed in the <code>\<subscriptionProductKey></code> element</p>                                                                                                                                                                                                                       |
| The product identified in the \`' element is valid                                                                       | <p><strong>Error Code</strong>: 730<br><strong>Message</strong>: No subscription products found for the order <code>\[productID=22222externalReferenceID= 33333companyID=44444locale=55555]</code><br><strong>Details</strong>: Where <code>\<subscriptionProductKey> element provides the values</code>22222<code>,</code>33333<code>,</code>44444<code>,</code>55555\`.</p>                                                                                                     |
| The activation key supplied in the `<activatioKey>` element is valid for the given Subscription                          | <p><strong>Error Code</strong>: 750<br><strong>Message</strong>: Activation Key \[activationKey=111] for provided productKey \[productID=22222externalReferenceID=<br>33333companyID=44444locale=55555] was not found<br><strong>Details</strong>: Where <code>111</code> is the activation key supplied in the <code>\<acivtionKey></code> element and <code>22222</code>, <code>33333</code>, <code>44444</code>, <code>55555</code> are the values provided in the element</p> |
| The activation date supplied in the `<activationDate>` element is valid                                                  | <p><strong>Error Code</strong>: Not applicable<br><strong>Message</strong>: Not applicable<br><strong>Details</strong>: If invalid, the activation date will be set to the current date</p>                                                                                                                                                                                                                                                                                       |
| The activation key supplied in the `<activationKey>` element has not previously been activated                           | <p><strong>Error Code</strong>: 770<br><strong>Message</strong>: The subscription for the provided Activation Key \[activationKey=111] has already been activated<br><strong>Details</strong>: Where <code>111</code> is the <code>\<activationKey></code> activation key supplied in the element</p>                                                                                                                                                                             |
| The subscription line item has not already been refunded                                                                 | <p><strong>Error Code</strong>: 780<br><strong>Message</strong>: Order \[888888] has been refunded<br><strong>Details</strong>: Where <code>888888</code> is the value passed in the <code>\<SubscriptionID></code> element</p>                                                                                                                                                                                                                                                   |
| The subscription line item has not already been cancelled                                                                | <p><strong>Error Code</strong>: 790<br><strong>Message</strong>: Order \[888888] was cancelled<br><strong>Details</strong>: Where <code>888888</code> is the value passed in the <code>\<SubscriptionID></code> element</p>                                                                                                                                                                                                                                                       |
| Your subscription `<SubscriptionID>` was renewed on *renewal date* which is before so your message cannot be processed\* | <p><strong>Error Code</strong>: 851<br><strong>Message</strong>: Requested renewal date is before the subscription activation date<br><strong>Details</strong>: Not applicable</p>                                                                                                                                                                                                                                                                                                |
| Nothing invalid                                                                                                          | <p><strong>Error Code</strong>: 0<br><strong>Message</strong>: Your request was carried out successfully.<br><strong>Details</strong>: Not applicable</p>                                                                                                                                                                                                                                                                                                                         |

## Cancel a subscription request

You must provide specific details about the subscription and the user to cancel a subscription request. The process involves constructing a `CancelSubscriptionRequest` object with the required elements and sending it to the appropriate endpoint. This section will guide you through the steps necessary to cancel a subscription successfully.

To cancel a subscription request, follow these steps:

1. Construct a `CancelSubscriptionRequest` object with the necessary details:
   * `shopperKey` including `userID` and `siteID`.
   * `SubscriptionID` for the subscription you want to cancel.
   * `subscriptionProductKey` with `productID`, `companyID`, and `externalReferenceID`.
   * Set `suppressCancelNotification` as needed.
   * Provide `subscriptionKey` with `subscriptionID`.
   * Send the request using the appropriate endpoint.
2. Here is a sample `CancelSubscriptionRequest`:

{% tabs %}
{% tab title="Cancel subscription request example" %}

```json
{
	"CancelSubscriptionRequest": {
		"shopperKey": {
			"userID": "26593336708",
			"siteID": "tmamer"
		},
		"SubscriptionID": "4343240414",
		"subscriptionProductKey": {
			"productID": "55551800",
			"companyID": "tmamer",
			"externalReferenceID": ""
		},
		"suppressCancelNotification": "false",
		"subscriptionKey": {
			"subscriptionID": "463301709"
		}
	}

```

{% endtab %}
{% endtabs %}

## Modify auto-renewal request

Modifying an auto-renewal request allows you to change the settings related to a subscription's automatic renewal. It can include switching between manual and automatic renewal, updating the renewal date, or changing other relevant details. The following section outlines the steps to successfully modify an auto-renewal request, ensuring that your subscription preferences are up-to-date and accurate.

To modify an auto-renewal request, follow these steps:

1. Construct a `ModifyAutoRenewalRequest` object with the necessary details:
   * `shopperKey` including `userID` and `siteID`.
   * `SubscriptionID` for the subscription you want to modify.
   * `subscriptionProductKey` with `productID`, `companyID`, and `externalReferenceID`.
   * Provide the `activationKey`.
   * Set the `autoRenewalAction` to either "Manual" or "Auto".
   * Specify the `autoRenewalDate` in the `YYYY-MM-DD` format.
   * Provide the `subscriptionKey` with `subscriptionID`.
2. Send the request using the appropriate endpoint.

Here is a sample `ModifyAutoRenewalRequest`:

{% tabs %}
{% tab title="Modify auto-renewal request example" %}

```javascript
{
	"ModifyAutoRenewalRequest": {
		"shopperKey": {
			"userID": "26593336708",
			"siteID": "tmamer"
		},
		"SubscriptionID": "4343240414",
		"subscriptionProductKey": {
			"productID": "55551800",
			"companyID": "tmamer",
			"externalReferenceID": ""
		},
		"activationKey": "22222",
		"autoRenewalAction": "Manual",
		"autoRenewalDate": "2009-08-08",
		"subscriptionKey": {
			"subscriptionID": "463301709"
		}
	}
}
```

{% endtab %}
{% endtabs %}

## Suspending subscriptions

Suspending a subscription temporarily halts the services and products associated with that subscription without completely canceling it. This function allows users to pause their subscription for a specific period or indefinitely. The process involves generating a unique suspension key and setting start and end dates for the suspension, with options for immediate suspension and indefinite end dates. Below, we outline the necessary steps and requirements for successfully suspending a subscription and handling any potential errors that may arise during the process.

To suspend a subscription, follow these steps:

1. Ensure the system generates a unique suspension key for the subscription.
2. Specify the start and end dates for the suspension in the `YYYY:mm:ddTHH:mm:ssZ` format.
   * If you want the suspension to start immediately, omit the start date.
   * To make the suspension's end date indefinite, set the `noEndDate` value to `true`.
3. Specify the type of suspension you want to create. Do not provide both a suspension end date and no suspension date without a suspension type, as this will result in an error.
4. When modifying an existing suspension date, supply the subscription key, suspension type, and new suspension date. To begin the suspension immediately, use the current date. Set `noEndDate` to `true` to make the suspension indefinite.

To end an existing or future suspension, you must supply the subscription key, suspension type, and the current date in the End Date field. This action removes the suspension.

The following image shows the process flow for modifying a suspension.

![Modifying a suspension](https://files.readme.io/492a5d4-User_Management.png)

## User management schemas

The user management schema is a structured framework that defines the organization, attributes, and relationships of user data within a system. It typically includes versions outlining various components and configurations, essential for integration and effective user management. The table below lists the versions available:

| Version     | Scheme Components Table                                                                  | Raw Schema                                                                  | Sample XML    |
| ----------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------- |
| 26 (Current | [View](https://drhadmin.digitalriver.com/integration/isg/schematable/UserManagement/26)  | [View](https://drhadmin.digitalriver.com/integration/xsd/UserManagement/26) | Not available |
| 25          | [View](https://drhadmin.digitalriver.com/integration/isg/schematable/UserManagement/25)  | [View](https://drhadmin.digitalriver.com/integration/xsd/UserManagement/25) | Not available |
| 24          | [View ](https://drhadmin.digitalriver.com/integration/isg/schematable/UserManagement/24) | [View](https://drhadmin.digitalriver.com/integration/xsd/UserManagement/24) | Not available |

These versions help understand and manage how user-related data is handled, ensuring consistency and compliance across different system integrations.