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.
128
addSubscriber
changeSubscriptionPlan
removeSubscriber
updateSubscriber
updateSubscriberCredentials
updateSubscriberPaymentMethod
Yes
Container for signature and tokenValue.
1000
addSubscriber
changeSubscriptionPlan
removeSubscriber
updateSubscriber
updateSubscriberCredentials
updateSubscriberPaymentMethod
Yes
Used to specify whether a token is passed by value or by reference.
Applications should expect it to be passed by value.
The token is passed by reference; reserved for future use.
The token is passed by value.
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.
2000
addSubscriber
changeSubscriptionPlan
removeSubscriber
updateSubscriber
updateSubscriberCredentials
updateSubscriberPaymentMethod
Yes
../../open-ebay-apps/Concepts/UsersGuideLandingPage.html
User Guide
values contained in tokenValue, and instructions on decrypting and parsing tokenValue
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.
addSubscriber
changeSubscriptionPlan
removeSubscriber
updateSubscriber
updateSubscriberCredentials
updateSubscriberPaymentMethod
Yes
../../open-ebay-apps/Concepts/UsersGuideLandingPage.html
User Guide
instructions on using this field
The base type for tokens.
1000
addSubscriber
changeSubscriptionPlan
removeSubscriber
updateSubscriber
updateSubscriberCredentials
updateSubscriberPaymentMethod
Yes
Base type for the request container for service operations.
Container for signature and tokenValue.
addSubscriber
changeSubscriptionPlan
removeSubscriber
updateSubscriber
updateSubscriberCredentials
updateSubscriberPaymentMethod
Yes
Base response container for service operations.
Indicates whether there are any errors or warnings associated with the
processing of the request.
Always
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.
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.
Conditionally
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.
Always
Indicates whether the issue is an error (causing the request to fail)
or a warning.
The request was processed successfully, but something occurred that may
affect your application or the user.
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.
The request that triggered the error was processed successfully but with
some warnings.
The request that triggered the error was processed successfully but with
some warnings.
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.
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.
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.
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.
Subscription is pending on eBay internal billing processing.
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.
Developer has suspended the subscription.
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.
The subscription has been cancelled by the developer.
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.
eBay has cancelled the subscription, possibly because the account remained
unpaid for 22 days following a billing statement.
Developer has declined to accept the subscription.
eBay has declined to accept the subscription.
Container for the user name of an eBay member. Provided in
the call request for convenience.
Instead using the value in this container, use the value in tokenValue.
The user name of an eBay user, provided for convenience.
Instead of using this value for the user name, use the value in tokenValue.
64
addSubscriber
changeSubscriptionPlan
removeSubscriber
updateSubscriber
updateSubscriberCredentials
Yes
Container for information about a change in the state of a subscription.
The state that the subscription was in, before eBay detected that a change
occurred.
updateSubscriber
Yes
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.
updateSubscriber
Yes
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.
updateSubscriber
Yes
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.
updateSubscriber
Yes
The subscription status of an eBay user.
Subscription status is approved, according to your application.
If you specify this value, eBay sets the user's
subscription to Active.
Subscription status is pending, according to your application.
If you specify this value, eBay takes no action.
Subscription status is rejected, according to your application.
If you specify this value in an addSubscriber response,
it means that, for whatever reason, your application is not
accepting the subscription specified by eBay in the addSubscriber request.
If eBay receives an addSubscriber response with
a status of Rejected, eBay will set the user's subscription status to Rejected.
The subscription state of an eBay user.
Reserved for future use.
Pending state. The subscription is not yet in the Active state.
Active state, i.e. actively subscribed to an application.
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.
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.
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.
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.
Expired state.
Container for subscription-related information.
For a particular application, the subscriptionId
uniquely identifies a user's subscription.
38
addSubscriber
changeSubscriptionPlan
removeSubscriber
updateSubscriber
updateSubscriberCredentials
Yes
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.
38
addSubscriber
changeSubscriptionPlan
removeSubscriber
updateSubscriber
updateSubscriberCredentials
Yes
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.
128
addSubscriber
changeSubscriptionPlan
removeSubscriber
updateSubscriber
updateSubscriberCredentials
Yes
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.
128
addSubscriber
changeSubscriptionPlan
removeSubscriber
updateSubscriber
updateSubscriberCredentials
Yes
Reserved for future use.
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.
128
addSubscriber
removeSubscriber
updateSubscriber
updateSubscriberCredentials
No
changeSubscriptionPlan
previousSubscriptionInfo
Cancelled, Expired
Yes
changeSubscriptionPlan
subscriptionInfo
Active, Pending, Rejected
Yes
The date when the user subscribed to the plan, e.g. the start of the free trial.
128
changeSubscriptionPlan
removeSubscriber
updateSubscriber
updateSubscriberCredentials
No
Start date of the user's term for purposes of billing.
128
changeSubscriptionPlan
removeSubscriber
updateSubscriber
updateSubscriberCredentials
No
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."
128
changeSubscriptionPlan
removeSubscriber
updateSubscriber
updateSubscriberCredentials
No
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.
128
changeSubscriptionPlan
removeSubscriber
updateSubscriber
updateSubscriberCredentials
No
Sent by eBay to request that you add an eBay member to
your subscription database. eBay sends this request
after the member completes the subscription flow.
<br>
<br>
Your application must use a subscription listener
to receive addSubscriber requests from eBay.
When your application receives an addSubscriber request, your application
must respond with a status value indicating the
subscription status in your database.
Specifically, your application must respond with a status of approved, pending, or rejected,
so eBay can set the state accordingly.
<br>
<br>
Note that if a subscriber changes from one of your plans to another,
a changeSubscriptionPlan request is sent, rather than an addSubscriber request.
<br>
<br>
If your application doesn't respond after eBay has sent 6 retries (across a day),
then after 24 hours, the retries are stopped and the subscription is
put in a cancelled state.
Sent by eBay to request that you add an eBay member to
your subscription database.
../../open-ebay-apps/Concepts/UsersGuideLandingPage.html
User Guide
information about a subscription listener
samples
Container for a field that indicates the user name of an eBay user.
addSubscriber
Yes
Container for subscription-related information.
addSubscriber
Yes
Contains a response to an addSubscriber call.
For a particular application, the subscriptionId
uniquely identifies a user's subscription.
addSubscriber
Conditionally
The status of the subscription, according to
your application (if ack is success).
For example, when you receive an addSubscriber request,
your application's response includes this field to indicate the
latest subscription status of the user, according to your database.
This status value initially is
set by your application, unlike the
subscriptionStateChangeInfo.newState
value, which is set by eBay. When eBay receives this status value from
your application, eBay sets the subscription to Active, Pending,
or Rejected, depending on the status value you send in the response.
addSubscriber
Always
Message about the subscription status.
addSubscriber
Always
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.
<br>
<br>
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.
Sent by eBay to request that you update information about an eBay member in
your subscription database.
../../open-ebay-apps/Concepts/UsersGuideLandingPage.html
User Guide
information about this call and setting up a subscription listener
samples
Container for a field that indicates the user name of an eBay user.
updateSubscriber
Yes
Container for subscription-related information.
updateSubscriber
Yes
Container for subscription-related information.
updateSubscriber
Yes
Contains a response to an updateSubscriber call.
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.
<br>
<br>
Your application must use a subscription listener
to receive removeSubscriber requests from eBay.
<br>
<br>
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.
<br>
<br>
Note that if a subscriber changes from one of your plans to another,
a changeSubscriptionPlan request is sent instead of a removeSubscriber request.
Sent by eBay to request that you remove an eBay member from
your subscription database.
../../open-ebay-apps/Concepts/UsersGuideLandingPage.html
User Guide
information about a subscription listener
samples
Container for a field that indicates the user name of an eBay user.
removeSubscriber
Yes
Container for subscription-related information.
removeSubscriber
Yes
Contains a response to a removeSubscriber call.
Sent by eBay when a subscriber has chosen the option of changing
from one of your subscription plans to another, on the
Applications tab in My eBay. For example, a user may upgrade
from a free plan to a paid plan.
<br>
<br>
The changeSubscriptionPlan request contains
the new external plan ID, subscription ID, and related values.
<br>
<br>
This functionality is available for an application in sandbox or production
only if a third party
notified eBay that they are opting in for this functionality.
The third party can opt in after initial testing in the sandbox.
<br>
<br>
In the case of a changed plan, the original plan is prorated-at-end.
The following changes are supported: changing from free to paid
(prorated or non-prorated); changing from paid to paid
(prorated or non-prorated); and changing from paid to free
(if paid plan is prorated).
The following change is not supported: changing from a non-prorated
plan to a free plan. In that case, the user would need to cancel the
non-prorated plan and then wait until the plan ends before
subscribing to the free plan.
Sent by eBay when a subscriber has changed their subscription plan, e.g. upgraded or
downgraded their plan.
samples
Container for a field that indicates the user name of an eBay user.
changeSubscriptionPlan
Yes
Container for subscription-related information.
changeSubscriptionPlan
Yes
Container for subscription-related information.
changeSubscriptionPlan
Yes
Contains a response to a changeSubscriptionPlan call.
Sent by eBay when a subscriber's payment method has changed.
<br>
<br>
A payment method is either manual or automatic.
If the payment method is manual, the subscriber doesn't have a recurring
payment method set up.
If the payment method is automatic, the subscriber has a recurring
payment method set up (currently, only PayPal is available).
<br>
<br>
For example, a payment method can become
manual upon cancellation of a pre-approval agreement.
Or, a payment method can become
manual when PayPal sets a subscriber's payment method to manual
after a problem collecting payment from the account
(e.g. due to an expired pre-approval agreement or a PayPal restriction on the account).
<br>
<br>
The updateSubscriberPaymentMethod request specifies true in the
manualPayment field if the payment method has been changed to manual. Otherwise it is false.
If the payment method has been changed to manual, the reason field can
be PAYPAL_USER_AGREEMENT_CANCELED, PAYPAL_HARD_DECLINED, INVALID, or
NONE.
Sent by eBay to notify you of a change in a subscriber's payment method.
samples
A payment method is either manual or automatic.
If true, indicates that there is no longer a recurring payment method.
If false, indicates that a recurring payment method (currently, only PayPal)
is set up for the subscriber.
If the payment method is manual, the subscriber doesn't have a recurring
payment method set up. If the payment method is automatic, the subscriber has a recurring
payment method set up (currently, only PayPal is available).
updateSubscriberPaymentMethod
Yes
The reason for the change in payment method.
If the payment method has been changed to manual,
the reason field can be PAYPAL_USER_AGREEMENT_CANCELED,
PAYPAL_HARD_DECLINED, INVALID, or NONE.
updateSubscriberPaymentMethod
Yes
Contains a response to an updateSubscriberPaymentMethod call.
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.
<br>
<br>
A user's Auth token (that is, the Auth and Auth token used in the
Trading API) expires after 18 months.
<br>
<br>
Use the eventCode field to determine the current status of a user's Auth token.
The field contains one of the following two values:
<ul>
<li>TokenRenewed: The token expired and was automatically renewed (no user consent is necessary),
or the token was revoked but the user has consented to creation of a new token.
In your database, replace the old token with the token delivered as part of the
updateSubscriberCredentials request.</li>
<li>TokenRevoked: The token was revoked. No token is in the call request.</li>
</ul>
Either way, use the
other data in the call request to identify the user.
Sent by eBay to notify you that a user's token has been revoked or renewed.
samples
Container for a field that indicates the user name of an eBay user.
updateSubscriberCredentials
Yes
Container for subscription-related information.
updateSubscriberCredentials
Yes
Contains the event that triggered the updateSubscriberCredentials call.
For more information, see the description of the updateSubscriberCredentials call.
If the value is TokenRevoked, the user's token was revoked.
If the value is TokenRenewed, the user's token has changed.
updateSubscriberCredentials
Always
Contains a response to a updateSubscriberCredentials call.
1.5.0