updateSubscriberCredentials

Sent by eBay to notify you that a user's Auth token was renewed or revoked. If a user's token is revoked, an OpeneBayUpdateSubscriberCredentials call is made to your listener, indicating that the token was revoked. At later time, if the user has consented to creation of a new token (e.g. in My eBay, using a link next to your application), another OpeneBayUpdateSubscriberCredentials call is made to your listener, indicating that the token was renewed. The subscription status remains as Subscribed.

A user's Auth token (that is, the Auth and Auth token used in the Trading API) expires after 18 months.

Use the eventCode field to determine the current status of a user's Auth token. The field contains one of the following two values:

Either way, use the other data in the call request to identify the user.



Back to top

Input Output Samples Change History User Notes
updateSubscriberCredentials 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"?>
<updateSubscriberCredentialsRequest 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>
</updateSubscriberCredentialsRequest>
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.



Back to top

Input Output Samples Change History User Notes
updateSubscriberCredentials 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"?>
<updateSubscriberCredentialsResponse xmlns="http://www.ebay.com/marketplace/services">
  <!-- Standard Output Fields -->
  <ack> AckValueType </ack>
  <errorMessage> string </errorMessage>
  <errorSeverity> ErrorSeverityType </errorSeverity>
  <timestamp> dateTime </timestamp>
</updateSubscriberCredentialsResponse>
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.



Back to top

Input Output Samples Change History User Notes
updateSubscriberCredentials 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

A third party application is notified that a user's token has been revoked.

Description

eBay is notifying a third-party application that a user's token has been revoked.

Input

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

<?xml version="1.0" encoding="UTF-8"?>
<updateSubscriberCredentialsRequest 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>
    <subscriptionState>Active</subscriptionState>
    <startDate>2010-02-10Z</startDate>
  </subscriptionInfo>
  <eventCode>TokenRevoked</eventCode>
</updateSubscriberCredentialsRequest>

Output

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

<?xml version="1.0" encoding="UTF-8"?>
<updateSubscriberCredentialsResponse xmlns="http://www.ebay.com/marketplace/services">
  <ack>Success</ack>
  <timestamp>2010-02-09T06:03:55.237-0700</timestamp>
</updateSubscriberCredentialsResponse>



Back to top

Input Output Samples Change History User Notes
updateSubscriberCredentials Change History
Version Description
1.4.0
2010-03-03
  • (added) New call.



Back to top

Input Output Samples Change History User Notes
User-Contributed Notes
   
 
 
 

© 2009–2010 eBay, Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.