OpeneBayParticipantInterface
|
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 this call and setting up a subscription listener.
| Output Samples Change History User Notes |
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" 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> <subscriptionStateChangeInfo> OpeneBaySubscriptionStateChangeInfoType <newState> OpeneBaySubscriptionStateType </newState> <note> string </note> <previousState> OpeneBaySubscriptionStateType </previousState> <reasonCode> OpeneBaySubscriptionReasonCode </reasonCode> </subscriptionStateChangeInfo> <userInfo> OpeneBaySubscriberInfoType <userName> string </userName> </userInfo> </updateSubscriberRequest>
| 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. |
| 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. 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. |
|
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. If a user unsubscribed themselves, this field contains a statement that the user unsubscribed using the Manage Applications page. |
|
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. 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. |
|
subscriptionStateChangeInfo .reasonCode |
OpeneBaySubscriptionReasonCode | 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.
Applicable values: • AccountNotPaidInTime (in) Following the suspension of a past due subscription, if the account remains unpaid, eBay will put the subscription in the AccountNotPaidInTime state and cancel the the subscription. • AccountPastDue (in) Subscription is pending on eBay internal billing processing. • BillingPending (in) • CancelledByDeveloper (in) The subscription has been cancelled by the developer. • CancelledByEbay (in) eBay has cancelled the subscription, possibly because the account remained unpaid for 22 days following a billing statement. • CancelledBySubscriber (in) User has cancelled the subscription. If this occurs during the free trial period, the subscription is cancelled immediately. If the user requests immediate cancellation from a paid subscription, see Cancel Immediately in the Managed Billing Platform Guide for steps you should take. • EPIPending (in) Subscription is pending an OEPI response. eBay has made the corresponding OEPI call to your application's listener but has not received a response, or has received a response with a Pending status. Or eBay has not yet made the OEPI call. • RejectedByDeveloper (in) Developer has declined to accept the subscription. • RejectedByEbay (in) eBay has declined to accept the subscription. • SuspendedByDeveloper (in) User has been billed, and a payment failure has occurred. The subscription is still active. User will be suspended by eBay if the account balance is greater than one dollar and more than 18 days have elapsed since the last billing statement. eBay will cancel the subscription at 22 days after the last billing statement. • SuspendedByEbay (in) Developer has suspended the subscription. |
| 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 User Notes |
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 User Notes |
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.
Description
A third-party application is sent a request that the 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 Users 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.
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 User Notes |
| Version | Description |
|---|---|
| 1.4.0 2010-03-03 |
|
| 1.3.0 2009-09-30 |
|
| Input Output Samples Change History User 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.