removeSubscriber - Call Reference - OpeneBayParticipantInterface API

removeSubscriber

Sent by eBay to request that you remove an eBay member from your subscription database. eBay sends the request when a user clicks the Unsubscribe button in My eBay.

Your application must use a subscription listener to receive removeSubscriber requests from eBay.

Decrypt the data in credentials.token.tokenValue in order to obtain the user name of the eBay member to remove from your subscription database. You must use the user name from credentials.token.tokenValue, not the auth token, because in a removeSubscriber request, the credentials.token.tokenValue field does not contain a token.

Note that if a subscriber changes from one of your plans to another, a changeSubscriptionPlan request is sent instead of a removeSubscriber request.

See User Guide for information about a subscription listener.

removeSubscriber Input

The box below lists all fields that could be included in the call request. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

See also Samples.

<?xml version="1.0" encoding="utf-8"?>
<removeSubscriberRequest xmlns="http://www.ebay.com/marketplace/services">
  <!-- Standard Input Fields -->
  <credentials appId="string" appId="string"> OpeneBayRequestCredentialsType (OpeneBayPrincipalIdentifierType)
    <token type="OpeneBayTokenType"> OpeneBaySecurityTokenType (OpeneBayBaseSecurityTokenType)
      <signature> string </signature>
      <tokenValue> string </tokenValue>
    </token>
  </credentials>
  <!-- Call-specific Input Fields -->
  <subscriptionInfo> OpeneBaySubscriptionInfoType
    <billStartDate> date </billStartDate>
    <cancelDate> date </cancelDate>
    <endDate> date </endDate>
    <externalPlanId> string </externalPlanId>
    <planId> string </planId>
    <planName> string </planName>
    <startDate> date </startDate>
    <subscriptionId> string </subscriptionId>
    <subscriptionState> OpeneBaySubscriptionStateType </subscriptionState>
  </subscriptionInfo>
  <userInfo> OpeneBaySubscriberInfoType
    <userName> string </userName>
  </userInfo>
</removeSubscriberRequest>

Argument	Type	Occurrence	Meaning

Standard Input Fields [Jump to call-specific fields]

credentials	OpeneBayRequestCredentialsType (OpeneBayPrincipalIdentifierType)	Required	Container for signature and tokenValue.
credentials [ attribute appId ]	string	Required	The AppID of the receiving application. When you upload a deployment descriptor for your application, you provide a value (as myapp.mycompany.com) that becomes your AppID in the keys that are issued for your application. For information about uploading a deployment descriptor, see the Users Guide.
credentials [ attribute appId ]	string	Required	The AppID of the receiving application. When you upload a deployment descriptor for your application, you provide a value (as myapp.mycompany.com) that becomes your AppID in the keys that are issued for your application. For information about uploading a deployment descriptor, see the Users Guide.
credentials.token	OpeneBaySecurityTokenType (OpeneBayBaseSecurityTokenType)	Required	Container for signature and tokenValue.
credentials.token [ attribute type ]	OpeneBayTokenType	Required	The base type for tokens. For a list of possible enumeration values, see OpeneBayTokenType.
credentials.token.signature	string	Required	An RSA-encrypted string by which you can verify that the request is from eBay. You decrypt this string with the public eBay key. For more information, and the location of the public key, see the link below. See User Guide for instructions on using this field.
credentials.token.tokenValue	string	Required	A base64-encoded string that you must decrypt before extracting values. In the case of addSubscriber, the values that you extract include the following for the user to be added as a subscriber to your application: the user name and the user Auth token (that is, the Auth and Auth token used in the Trading API). In the case of removeSubscriber, values that you extract (for the user to remove) include the user name. Max length: 2000. See User Guide for values contained in tokenValue, and instructions on decrypting and parsing tokenValue.

Call-specific Input Fields

subscriptionInfo	OpeneBaySubscriptionInfoType	Required	Container for subscription-related information.
subscriptionInfo.billStartDate	date	Optional	Start date of the user's term for purposes of billing.
subscriptionInfo.cancelDate	date	Optional	The date on which the user or developer requested cancellation of the subscription. For example, in the case of a prorated-at-end plan, the cancelDate can be the date of when the third party changed the subscription state to "Canceled" or to "Cancel Immediately." For a nonprorated-at-end plan, the cancelDate can be the the date of when the third party changed the state to "Cancel Immediately."
subscriptionInfo.endDate	date	Optional	End date of the user's subscription. Specifically, the endDate is the date on which the subscription actually ends. That is, for a prorated-at-end plan, it is the date when the user unsubscribed. (For prorated-at-end plans, the cancel and end dates are the same.) For a nonprorated-at-end plan, it is the date of the term end.
subscriptionInfo .externalPlanId	string	Required	When you create a subscription plan, you provide a Developer Plan ID. That Developer Plan ID is contained in this externalPlanId field. (For users to subscribe to your application, you must create at least one subscription plan.) In this call, the externalPlanId identifies the plan to which a user has subscribed. Note that if you are running an application in the sandbox, a subscription plan, and an associated value for the Developer Plan ID, are created for you. You can create others plans, if desired, with different Developer Plan IDs. Max length: 128.
subscriptionInfo.planId	string	Required	A planId is assigned by eBay to each subscription plan. Your application often uses this value in calls to the Open eBay Application Integration Service. Note that the planId is diffrent from the externalPlanId. In contrast to the planId, the externalPlanId is the value that you provide, as a "Developer Plan ID," when you create a subscription plan. Max length: 38.
subscriptionInfo.planName	string	Required	The plan name that you provided for your subscription plan when you created the plan. This plan name is provided in the call request to help you read log files, during debugging. Instead of using this value for programmatically identifying the subscription plan, use value in the externalPlanId field. Max length: 128.
subscriptionInfo.startDate	date	Optional	The date when the user subscribed to the plan, e.g. the start of the free trial.
subscriptionInfo .subscriptionId	string	Required	For a particular application, the subscriptionId uniquely identifies a user's subscription. Max length: 38.
subscriptionInfo .subscriptionState	OpeneBaySubscriptionStateType	Optional	The state of an eBay member's subscription. The following are examples: The user may be in an active state, i.e. actively subscribed to your application. The user may be in a suspended state, as in the case of a payment failure, so the user cannot start your application. The user may be in a cancelled state, i.e. the user may no longer have access to your application. Applicable values: • Active (in) Active state, i.e. actively subscribed to an application. • Cancelled (in) Cancelled state, i.e. unsubscribed from an application. When a user clicks the "unsubscribe" link to unsubscribe from your non-prorated plan, eBay sends an updateSubscriber call to your application with the the subscription end date in the note field. The subscriptionStateChangeInfo.newState field may still be Active, but the user's status in in your Active Subscribers list will be CancelledPending. If you want to cancel the user's subscription immediately, use the control in the embedded applications tab in your My Account page as follows. In the embedded applications tab, select Active Users, and search for the user. Pull down the Status selection list, select Cancel Immediately, and then click Submit. • CancelledPending (in) When a user clicks the "unsubscribe" link to unsubscribe from your non-prorated plan, eBay sends an updateSubscriber call to your application with the the subscription end date in the note field. The subscriptionStateChangeInfo.newState field may still be Active, but the user's status in in your Active Subscribers list will be CancelledPending. If you want to cancel the user's subscription immediately, use the control in the embedded applications tab in your My Account page as follows. In the embedded applications tab, select Active Users, and search for the user. Pull down the Status selection list, select Cancel Immediately, and then click Submit. • Created (in) Reserved for future use. • Expired (in) Expired state. • Pending (in) Pending state. The subscription is not yet in the Active state. • Rejected (in) Rejected state. One of the following has occurred: your application rejected the subscription (after receiving an addSubscriber call), or the subscription was manually changed (by the third-party application developer) to the rejected state. • Suspended (in) Suspended state, e.g. due to a payment failure or past due account. There is a block (that can be removed) on the user's access to the application. That is, the user cannot start the application.
userInfo	OpeneBaySubscriberInfoType	Required	Container for a field that indicates the user name of an eBay user.
userInfo.userName	string	Required	The user name of an eBay user, provided for convenience. Instead of using this value for the user name, use the value in tokenValue. Max length: 64.

removeSubscriber Output

The box below lists all fields that might be returned in the response. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

See also Samples.

<?xml version="1.0" encoding="utf-8"?>
<removeSubscriberResponse xmlns="http://www.ebay.com/marketplace/services">
  <!-- Standard Output Fields -->
  <ack> AckValueType </ack>
  <errorMessage> string </errorMessage>
  <errorSeverity> ErrorSeverityType </errorSeverity>
  <timestamp> dateTime </timestamp>
</removeSubscriberResponse>

Return Value	Type	Occurrence	Meaning

Standard Output Fields

ack	AckValueType	Always	Indicates whether there are any errors or warnings associated with the processing of the request. Applicable values: • Failure (out) The request that triggered the error was not processed successfully. When a serious application-level error occurs, an error is returned instead of business data. • PartialFailure (out) The request that triggered the error was processed successfully but with some warnings. • Success (out) The request was processed successfully, but something occurred that may affect your application or the user. • Warning (out) The request that triggered the error was processed successfully but with some warnings.
errorMessage	string	Conditionally	After you decide how your implementation of this service will define errors, you can decide whether to use this container. eBay does not inspect the value of this errorMessage field.
errorSeverity	ErrorSeverityType	Conditionally	Indicates whether the error is a severe error (causing the request to fail) or an informational error (a warning) that should be communicated to the user. Applicable values: • Error (out) The request that triggered the error was not processed successfully. When a serious application-level error occurs, the error is returned instead of the business data. • Warning (out) The request was processed successfully, but something occurred that may affect your application or the user. For example, eBay may have changed a value the user sent in. In this case, eBay returns a normal, successful response and also returns the warning.
timestamp	dateTime	Always	The date and time the request was processed. The time zone of this value is GMT and the format is the ISO 8601 date and time format (YYYY-MM- DDTHH:MM:SS.SSSZ). See Time Values in the eBay Web Services guide for information about this time format and converting to and from the GMT time zone.

removeSubscriber Samples

New to making API calls? Please see Making an API Call.

Note: Some item IDs, user IDs, or other data in these samples might no longer be active on eBay. If necessary, you can substitute current eBay data in your requests.

Sample: Basic Call

Requests removal of a subscriber.

Description

A request that a third-party application remove a user from the third-party application's subscription database.

Input

Your application must decrypt the string in the tokenValue field to determine the username to remove from your application's subscription database. For more information, see the Users Guide.

XML format (HTTP POST). Also available is the .txt version of this XML.

<?xml version="1.0" encoding="UTF-8"?>
<removeSubscriber xmlns="http://www.ebay.com/marketplace/services">
  <credentials appId="your_app_id">
    <token type="Value">
      <tokenValue>token_value</tokenValue>
      <signature>signature_value</signature>
    </token>
  </credentials>
  <userInfo>
    <userName>magicalbookseller</userName>
  </userInfo>
  <subscriptionInfo>
    <subscriptionId>5000004267</subscriptionId>
    <planId>5000000627</planId>
    <planName>EasyBill</planName>
    <externalPlanId>ARKLS3</externalPlanId>
  </subscriptionInfo>
</removeSubscriber>

Output

The third-party application responds with an Ack field containing Success.

XML format. Also available is the .txt version of this XML.

<?xml version="1.0" encoding="UTF-8"?>
<removeSubscriberResponse xmlns="http://www.ebay.com/marketplace/services">
  <ack>Success</ack>
  <timestamp>2009-05-18T16:34:09.423-0700</timestamp>
</removeSubscriberResponse>

removeSubscriber Change History

Version	Description
1.4.0 2010-03-03	Various (added): See the Release Notes for this version, and the new sample for this call.
1.3.0 2009-09-30	Various (doc change): Documentation updates based on changes to Selling Manager Applications.
1.2.0 2009-06-24	(various) Adding billing-plan information, and other updates.
1.1.0 2009-04-01	(added) New call.

User-Contributed Notes

OpeneBayParticipantInterface Call Reference Version 1.5.0

OpeneBayParticipantInterface
Call Reference Version 1.5.0