User management

Learn how to manage users.

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

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	`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`

Activate a user

ActivateShopperRequest

ActivateShopperResponse

Inactivate a user

InactivateShopperRequest

InactivateShopperResponse

Reset user password

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

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:

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

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

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

The user identified in the shopperKey element is valid

Error Code: 200 Message: Shopper Not Found

The subscription identified in the 'SubscriptionID` element is valid

Error Code: 710 Message: Subscription order [888888] pending activation was not found Details: Where the <SubscriptionID> element passes the 888888 value.

The specified Subscription belongs to the given user

Error Code: 720 Message: Subscription order [888888] does not belong to shopper [loginID =12345, externalReferenceID = 54321] Details: Where the<SubscriptionID> element passes the 888888 value. The values 12345 and 54321 are the Digital River loginID and externalReferenceID for the shopper.

The specified Subscription contains a given product

Error Code: 730 Message: No subscription products found for the order [888888] Details: Where888888 is the value passed in the <subscriptionProductKey> element

The product identified in the `' element is valid

Error Code: 730 Message: No subscription products found for the order [productID=22222externalReferenceID= 33333companyID=44444locale=55555] Details: Where <subscriptionProductKey> element provides the values22222,33333,44444,55555`.

The activation key supplied in the <activatioKey> element is valid for the given Subscription

Error Code: 750 Message: Activation Key [activationKey=111] for provided productKey [productID=22222externalReferenceID= 33333companyID=44444locale=55555] was not found Details: Where 111 is the activation key supplied in the <acivtionKey> element and 22222, 33333, 44444, 55555 are the values provided in the element

The activation date supplied in the <activationDate> element is valid

Error Code: Not applicable Message: Not applicable Details: If invalid, the activation date will be set to the current date

The activation key supplied in the <activationKey> element has not previously been activated

Error Code: 770 Message: The subscription for the provided Activation Key [activationKey=111] has already been activated Details: Where 111 is the <activationKey> activation key supplied in the element

The subscription line item has not already been refunded

Error Code: 780 Message: Order [888888] has been refunded Details: Where 888888 is the value passed in the <SubscriptionID> element

The subscription line item has not already been cancelled

Error Code: 790 Message: Order [888888] was cancelled Details: Where 888888 is the value passed in the <SubscriptionID> element

Your subscription <SubscriptionID> was renewed on renewal date which is before so your message cannot be processed*

Error Code: 851 Message: Requested renewal date is before the subscription activation date Details: Not applicable

Nothing invalid

Error Code: 0 Message: Your request was carried out successfully. Details: Not applicable

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:

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.
Here is a sample CancelSubscriptionRequest:

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

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:

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.
Send the request using the appropriate endpoint.

Here is a sample ModifyAutoRenewalRequest:

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

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:

Ensure the system generates a unique suspension key for the subscription.
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.
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.
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.

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: