OpeneBayParticipantInterface
|
Sent by eBay to request that you update information about an eBay member in your subscription database. This call always applies to an existing subscription. eBay sends an updateSubscriber call to your application when eBay detects a change in a subscription state for a user. For example, if an SM Apps developer changes a user's subscription state using the Embedded Applications tab (at the Developers Program website), eBay sends an updateSubscriber call to your application.
See User Guide for information about a subscription listener.
| Output Samples Change History |
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"?>
<updateSubscriberRequest xmlns="http://www.ebay.com/marketplace/services">
<!-- Standard Input Fields -->
<credentials appId="string"> OpeneBayRequestCredentialsType
<token> OpeneBaySecurityTokenType
<signature> string </signature>
<tokenValue> string </tokenValue>
</token>
</credentials>
<!-- Call-specific Input Fields -->
<subscriptionInfo> OpeneBaySubscriptionInfoType
<externalPlanId> string </externalPlanId>
<planId> string </planId>
<planName> string </planName>
<subscriptionId> string </subscriptionId>
</subscriptionInfo>
<subscriptionStateChangeInfo> OpeneBaySubscriptionStateChangeInfoType
<newState> OpeneBaySubscriptionStateType </newState>
<note> string </note>
<previousState> OpeneBaySubscriptionStateType </previousState>
</subscriptionStateChangeInfo>
<userInfo> OpeneBaySubscriberInfoType
<userName> string </userName>
</userInfo>
</updateSubscriberRequest>
| Argument | Type | Occurrence | Meaning |
|---|
| Standard Input Fields [Jump to call-specific fields] |
| credentials | OpeneBayRequestCredentialsType | 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 Selling Manager 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 User's Guide. |
| credentials.token | OpeneBaySecurityTokenType | Required | Container for signature and tokenValue. |
| 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 signature. |
| 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 .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 | Optional |
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 .subscriptionId |
string | Required |
For a particular application, the subscriptionId uniquely identifies a user's subscription. Max length: 38. |
| subscriptionStateChangeInfo | OpeneBaySubscriptionStateChangeInfoType | Required | Container for subscription-related information. |
|
subscriptionStateChangeInfo .newState |
OpeneBaySubscriptionStateType | Required |
The new state of a subscription. This value is sent by eBay; eBay sends an updateSubscriber request to your application when a change in a user's subscription state is detected. For example, eBay sends an updateSubscriber request to your application if, due to a payment failure, a user's subscription goes into a suspended state.
Applicable values: • Active (in) Active state, i.e. actively subscribed to an application. • Cancelled (in) Cancelled state, i.e. unsubscribed from an application. • CancelledPending (in) Reserved for future use. • Created (in) Reserved for future use. • 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. |
|
subscriptionStateChangeInfo .note |
string | Required | A message about the reason for the change in state of the subscription. Depending on how the subscription state was changed, this message may have been manually entered (as part of the change) or may have been auto-generated. |
|
subscriptionStateChangeInfo .previousState |
OpeneBaySubscriptionStateType | Required |
The state that the subscription was in, before eBay detected that a change occurred.
Applicable values: • Active (in) Active state, i.e. actively subscribed to an application. • Cancelled (in) Cancelled state, i.e. unsubscribed from an application. • CancelledPending (in) Reserved for future use. • Created (in) Reserved for future use. • 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. |
| Input Samples Change History |
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"?> <updateSubscriberResponse xmlns="http://www.ebay.com/marketplace/services"> <!-- Standard Output Fields --> <ack> AckValueType </ack> <errorMessage> string </errorMessage> <errorSeverity> ErrorSeverityType </errorSeverity> <timestamp> dateTime </timestamp> </updateSubscriberResponse>
| 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. |
| Input Output Change History |
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.
Requests that a suspended subscriber be made active in a Selling Manager application.
Description
Selling Manager Applications is requesting that a third-party application set a user to Active in the third-party application's subscription database.
Input
Your application must decrypt the string in the tokenValue field to determine the username. For more information, see the User Guide. Your application should set that user to an Active state in your application's database. For convenience, the userName input field specifies the name of the eBay user, magicalbookseller, who should be added. However, you should use the string in tokenValue to determine the user name.
XML format (HTTP POST). Also available is the .txt version of this XML. <?xml version="1.0" encoding="UTF-8"?> <updateSubscriberRequest 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> <subscriptionStateChangeInfo> <previousState>Suspended</previousState> <newState>Active</newState> <note>This user is an active subscriber and not suspended</note> </subscriptionStateChangeInfo> </updateSubscriberRequest>
Output
The third-party application responds with a status of Success, indicating that the user has been set to an Active state in your application's database.
XML format. Also available is the .txt version of this XML. <?xml version="1.0" encoding="UTF-8"?> <updateSubscriberResponse xmlns="http://www.ebay.com/marketplace/services"> <ack>Success</ack> <timestamp>2009-09-10T06:03:55.237-0700</timestamp> </updateSubscriberResponse>
| Input Output Samples |
| Version | Description |
|---|---|
| 1.3.0 2009-09-30 |
|
This document was generated with a customized version of the apireferencedocs tool.
© 2009 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.