Open eBay Apps
|
This document explains how to implement subscription and billing for your app. For an explanation of how Open eBay billing works, see the Managed Billing Platform Guide.
Note: You can manage subscriptions manually, using the Embedded Applications tab. See Manually Viewing Subscription Data and Managing Subscribers.
To enable subscription, you use the OpeneBayParticipantInterface (OEPI) to write a subscription listener. A subscription listener receives subscription-related calls from eBay. There are several calls made by eBay to your application; please see below, and see all the calls in the OpeneBayParticipantInterface, in the OEPI Call Reference.
For example, eBay sends the updateSubscriber call when a change occurs in the state of a user's subscription to your application, as occurs when you update a user's subscription state with the User Management Tool (on the Embedded Applications tab).
The updateSubscriber request contains the old and new states of the user's
subscription (in subscriptionStateChangeInfo containers).
The request also contains a note field, containing the reason that eBay
sent you this particular updateSubscriber request.
Examples of states in the call request are:
If you provide a plan that is nonprorated-at-end: If a user clicks the Unsubscribe button for the plan, the user remains in the Active state until the date of their term end (although, on the user's Applications tab, the user sees "Pending Cancellation...Your subscription will end on [date of term end]"). Thus, if the bill start date for a monthly plan was 09/20, the term end is always the 20th of the month; if the user clicks Unsubscribe on 12/02, the subscription remains in an Active state until 12/19. On 12/19, the subscription goes into the Cancelled state. If the plan is yearly, then the plan term is one year rather than one month, and the user could potentially remain in the Active state for several months after clicking Unsubscribe. You can retrieve a user's subscription end date, and/or cancel a subscription immediately, with the User Management Tool (on the Embedded Applications tab).
Note: You may want to avoid receiving subscription calls (e.g., addSubscriber calls) from eBay. The Implements tag in the deployment descriptor has a default value of subscription, which means that by default, eBay sends addSubscriber and removeSubscriber calls to your application.
Remove the subscription value if your application has not implemented a subscription listener, and eBay will not send your application (or expect your application to respond to) subscription calls.
To enable users to subscribe or unsubscribe to your application, you must implement the OpeneBayParticipantInterface (OEPI) service. When you do so, you are in effect writing a "subscription listener" that receives calls such as addSubscriber. This subscription listener is an application that receives subscription requests, e.g. addSubscriber requests, from eBay. eBay makes an addSubscriber call to your OEPI service if a user goes to My eBay and subscribes to your application.
See the OpeneBayParticipantInterface Call Reference, which includes samples. Also see the following Java sample: Open eBay Apps event listener.
Your application's response can include the errorMessages
node, for your use. It is ignored by eBay.
In your deployment descriptor,
find the Link field
whose rel attribute is EndPoint.Management.
Set its href to the URL of your OEPI listener.
eBay sends subscription calls to the URL that you specify.
eBay recommends HTTPS.
When eBay sends subscription calls to the URL that you specified,
eBay includes a cmd parameter in the URL. Your application should check the value
of this cmd parameter in the URL, because the value is the name of the call. For
example, eBay might use the following URL and parameter:
https://SampleCompany.com/Listener/IntegrationManagement?cmd=addSubscriber
The subscription calls from
eBay include signature and tokenValue.
To ensure that the request is from eBay, use
tokenValue as the verification string for
signature. For more information, see Verifying a Request Signature.
Although tokenValue is
used for signature verification, the encrypted
contents of tokenValue, such as the token expiration date, is not
relevant for signature verification.
However, to subscribe or unsubscribe a user,
you must decrypt tokenValue, because the user name is
encrypted as part of
tokenValue.
See Decrypting to Obtain User Information.
When a user clicks Subscribe in My eBay, eBay sets
the subscription state to Pending and sends an addSubscriber request to your application.
After you process the request, your application sends
an addSubscriber response containing a status value
(Approved, Rejected, etc.).
When a user's subscription ends, eBay revokes the user's token and sends a removeSubscriber request to your application.
The User Management tool, accessible from the Embedded Applications tab, enables you to manually view information about subscribers. You also can manually change their subscription states. (To instead use an API to retrieve information about subscribers and change their subscription states, see the Open eBay Subscription Service.)
With the User Management tool, you can view (and export to Excel) the following information for users subscribed to your application:
subscriptionInfo.planId field. 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. To access the User Management tool, go to the Embedded Applications tab (accessible from the My Account page). In the section of the page under Sandbox Applications or under Production Applications, click the link that contains the number of users (next to the words Active Subscribers). The User Management tool is displayed (at the bottom of the page), enabling you to retrieve data for users and change users' subscription states. The User Management tool is run when you click the Search button. Users are retrieved based on criteria that you can specify in the tool, e.g. status, subscription date range, and/or user ID.
You can manually change a user's subscription state by clicking the current subscription state (in the Status column). An option for plans that are prorated-at-end is to change the state to "Canceled," ending the subscription. Note that for plans that are nonprorated-at-end, "Canceled" sets the end date to the term end (it does not result in immediate cancellation). If you want to cancel a subscription immediately for a nonprorated-at-end plan, you can change the state to "Cancel Immediately." This causes the subscription to end immediately, instead of at the end of the term. (For a plan that is nonprorated-at-end, a user who unsubscribes will normally remain in the Active state until the term end; see Enabling Subscription.) When you use the Cancel Immediately option, the user's authentication token is revoked (preventing any API calls on their behalf), their billing agreement is ended, and your application is removed from their Applications tab.
You can enable the option for users to upgrade and downgrade their plan, e.g. from a free plan to a paid plan. When this option is turned on for your application, users see the Change Plan option, in My eBay, for your application. Users then can change their plan if they are active or their plan is expired.
Before you enable this option for your users, you must first enable your subscription listener to
handle the changeSubscriptionPlan call (see the OpeneBayIdentityProvider Call Reference). The changeSubscriptionPlan call is 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.
The call request contains the new external plan ID, subscription ID, and related values.
If you want to enable the Change Plan option for your users, you must do the following:
changeSubscriptionPlan call in your subscription listener in the sandbox.
getSubscribers call (in OESS) for confirming that your subscription database is correct.
In the case of a changed plan, the original plan is prorated-at-end. The following kinds of 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.
Use the SubscriberRegistrationGlobalId tag in your app's deployment descriptor to allow users from other international sites to access your US app. Currently, the Hong Kong site is the only non-US site available.
By default, US and Motors registered users have access to your US apps. If you do not want to add international subscribers, you do not need to add the SubscriberRegistrationGlobalId tag to your app's deployment descriptor. If you do want to add international subscribers, however, the SubscriberRegistrationGlobalId tag needs to include all sites for which your app will accept subscriptions.
To enable Hong Kong users, update your app's deployment descriptor above the gadget tag and at the same level, with the following.
<SubscriberRegistrationGlobalIdList>
<SubscriberRegistrationGlobalId>EBAY-US</SubscriberRegistrationGlobalId>
<SubscriberRegistrationGlobalId>EBAY-MOTOR</SubscriberRegistrationGlobalId>
<SubscriberRegistrationGlobalId>EBAY-HK</SubscriberRegistrationGlobalId>
</SubscriberRegistrationGlobalIdList>
After you have uploaded your deployment descriptor with the Hong Kong tag, Hong Kong users who view the application directory on the US site will be able to subscribe to your app through the normal subscription flow.
After Hong Kong subscribers go through the subscription flow for your app on the US site, they will be able to view their statements and balances for your app in their My Seller Account and View Account Statements on the Hong Kong site, and see Hong Kong user statements and email communication in the local language.
For users to subscribe to your production application, you must set up at least one subscription plan. By default, you can submit a maximum of four subscription plans per application (four in the Sandbox and four in Production, that is). If you have business reasons for needing more than four plans, you should present them during your app's vetting process.
Note: The Subscription Plan tool, on the Embedded Applications tab, must be used to set up a new plan (free or paid). However, to edit an existing plan (i.e., a plan that is in the submitted or active state), please continue to use the Billing Plan spreadsheet (see the Managed Billing Platform Guide).
When users view information about your production application, they see the subscription plans that you offer. After a user selects a plan, the user can complete the subscription process. The user is asked to agree to eBay's Terms of Use, agree to the Developer's Terms and Privacy Policy, and, unless the plan is free, provide payment information. After subscribing, a user can run the application in My eBay on the Application tab.
You receive 80 percent of the revenue from your application, through the following process:
When you're ready to test your plans, enter them in production, in a "hidden" mode (so other users cannot see them), and test them.
Please see the Managed Billing Platform (MBP) Guide for the following:
To receive revenue, you must set up at least one billing plan for your application.
The Managed Billing Platform Guide includes subscription options, plan requirements, and information about invoicing.
When you are ready to verify that a billing plan works as expected, submit the plan for your production application. It will be in a "hidden" mode, so you can begin testing it in production.
Note: A free plan in the sandbox is automatically created for you when you submit your sandbox deployment descriptor. If you decide to move a free application to production, you must create a subscription plan using the steps below. The conditions that affect whether users can see your plan are the following: whether the plan is visible, whether it is active, and whether today's date falls within the active dates of the plan.
Before submitting a billing plan, please do the following:
Only use the Billing Plan spreadsheet to edit an existing plan, i.e. a plan in the submitted or active state. The Subscription Plan tool (on the Embedded Applications tab) must be used to set up a new plan (free or paid).
The Subscription Plan tool (on the Embedded Applications tab) is used to set up a new plan. You can enter a maximum of four plans in the production environment. However, you also can enter a plan in the sandbox, to see how the plan is displayed (plan name, description, etc.) in the subscription flow. In the sandbox, no actual billing occurs. If you use a sandbox test user to try to subscribe to a sandbox plan, the subscription status will be in "Pending" until the user is made active.
For the data needed for a subscription plan, see the following section of the Managed Billing Platform Guide: "Appendix - Billing Plan Definition Information."
Please note the following:
You can offer multiple plans for your application. For example, your application could allow users to choose one of the following plans:
A plan with a recurring charge must offer a free trial period (minimum 7 days), have a completely free option, or have a free plan. Note that in the case of a billable (non-free) plan, if a user unsubscribes from the free trial in less than 7 days, and then resubscribes, the user is ineligible for the free trial and is charged.
A plan with a usage-only charge must have a reasonable free trial that is based on usage. After the user exceeds the free-usage limit, usage charges are incurred.
For more information, see the Managed Billing Platform Guide.
Note that a "free trial period" is different from a "free plan."
There are two types of free plans: limited duration and unlimited duration. For both, you can offer users the ability to easily upgrade:
If you offer a promotional plan, users can subscribe to it knowing that they won't be billed if they forget to unsubscribe. Additionally, a promotional plan makes it easier for users to upgrade their plans.
Note: To enable users to easily upgrade, you must enable the Change Plan option for your users. This includes an addition to your subscription listener. If you enable the Change Plan option, then when a user clicks Upgrade, a changeSubscriptionPlan call is made to your application and the user can be put into a billable plan. There is no need for the user to unsubscribe and then resubscribe. See Enabling Users To Easily Change Plans.
In the case of a promotional plan, if the plan has been expired for 30 days, a removeSubscriber call is made to your application. The application is listed as cancelled, the token is revoked, and the plan isn't shown in the user's Active applications.
Also see the Managed Billing Platform Guide.
The subscription plan lifecycle is used to track when the plan is submitted, configured (in the Managed Billing Platform), and available to users.
Each month, each user gets a billing statement of expected charges.
There are two billing cycles each month. Before subscribing to any Open eBay app, each user already has been assigned to one of the following two cycles:
For all users (BC0 and BC15 users), the following occurs: about 15 days after a statement is received, the user's PayPal account is debited for charges listed in the statement, and the money is credited to the third-party developer's PayPal account.
There is a variable amount of time between when a user comes out of a free trial and when the first billing statement is created. For example, if a user comes out of a free trial on August 3, but they are on BC0, their first statement isn't received until about September 1st. If they are on BC15, their first statement is received on about August 15th.
If a payment failure occurs, the user is requested, through email and My Messages, to correct their payment information. If the user takes no action, then 3 days after the payment failure, the user is suspended (see the Past-Due Accounts section, below this section). If the user still takes no action, then 4 days later, the user's subscription is cancelled.
For more information related to billing cycles, see the Managed Billing Platform Guide. For information about retrieving billing statement information, see Retrieve Billing Statement Information.
This section describes suspended subscriptions and one-time payments.
Note: The information in this section about suspensions applies to a future release of Open eBay Apps.
If a user of your application has a past-due balance for 18 days, the user's subscription is suspended. An example of a suspended user is below. It is expected that a user with a past-due balance is aware of the past-due balance (see the Billing Statements section, above this section).
A past-due balance usually results from a payment failure. A user is notified by email when a payment failure occurs, and has 3 days to correct the payment failure. Specifically, if the suspended user makes a one-time payment, and the account balance is no longer past-due, then within a few minutes, the user's subscription is made active.
However, if a suspended user takes no action (for 3 days after the suspension), then the user's subscription may be cancelled. You are notified of these events by an updateSubscriber call made to your application. If a subscription is cancelled, then to use your application, the user must resubscribe. If a user's subscription is cancelled, it is recommended that you maintain the user's data for a short period of time to allow the user to resubscribe without losing their settings.
If a user's subscription is suspended, then in My eBay, on the user's Applications tab, the Start button for your application is disabled. The user can click the Make a Payment link, as in the following example, resulting in an updateSubscriber call to your application:
If a user notifies you that on the Applications tab, the Start button is disabled, as in the above example, you can assist them by instructing them as follows:
For calls made by your application for subscriptions and plans, you use the OpeneBaySubscription service (OESS). The calls in the OpeneBaySubscription service are described in this section of the Users Guide. Please use the OpeneBaySubscription service rather than the OpeneBayApplicationIntegration service.
Note: the OpeneBaySubscription service will completely replace the OpeneBayApplicationIntegration service by September 2010.
OpeneBaySubscription calls require that an Open eBay Identity Provider (OEIDP) token
is passed in the header
of the call. You use the login call in the OpeneBayIdentityProvider service to obtain the OEIDP token. For information about using the OEIDP login call (and
the associated authenticate call),
see the OpeneBayIdentityProvider Call Reference.
The addUsage call is used to add charges for a subscriber, including some nonusage types of charges, e.g. a monthly subscription fee. For a description of all of the options available, and a sample call, see addUsage.
Note that you can charge your subscribers not just for usage but also for setup fees, one-time fees, and recurring fees. For recurring fees, this call is an alternative to having the Managed Billing Platform manage charges on your behalf. See the Managed Billing Platform Guide for more information.
If desired, you can set up a usage-based billing plan: Decide on the usage charges that you will include in your plan; see the Managed Billing Platform Guide. Also see Offering Subscription Plans. When you create your plan, affirm that you plan to bill for usage and select your desired usage categories.
If you use the addUsage call to report usage, then you include the amount of the charge
in the call request. Usage records will appear on the subscriber's billing statement and the associated usage charges will be included in the billing statement total amount due, where applicable.
As in other Subscription service calls, you include the OEIDP token in the header of the request.
The following calls retrieve billing statement information:
The getBillingStatements call retrieves the available billing statements for a subscriber.
Thus, if a subscriber contacts you with questions about a charge or a statement, you can refer to the subscriber's
billing statements.
The getBillingStatements response includes information for each billing statement, such as the statement ID, statement date, statement total, new charges total, credits total, payments total, and balance due.
After you call getBillingStatements and identify a statement you want more information about,
you can use getBillingRecords to get line-item details.
For example, if your plan includes a base monthly cost and additional usage, getBillingRecords returns the line items that correspond to these charges. Specifically, you will see a "subscription" fee line item and "usage fee" line item, including the date, description, charge details, charge amount, and other information for a line-item.
The billing information retrieved by getBillingStatements and getBillingRecords matches what is displayed in the billing statements that a subscriber sees on the My eBay page. You can incorporate these calls into a tool for managing end-user inquiries. The tool could display statement data for your use.
The getBillingStatementImage response contains the image of a billing statement.
You can use this call if you want to see an actual image of the statement as it is displayed to a subscriber
on the My eBay page.
After you have retrieved an ID of a billing statement using getBillingStatements, you can
call getBillingStatementImage to retrieve the image of the billing statement.
The data returned by getBillingStatementImage
usually must be decompressed and decoded; see getBillingStatementImage.
The getSubscribers call retrieves information about an application's subscribers.
The getSubscriptionPlans call retrieves information about subscription plans.
You can change the state of a user's subscription, e.g. cancel the subscription, using the setSubscriptionState call.
The setBillingStartDate request lets you start a user's subscription before the end of the mandatory free trial period, at the subscriber's request. The call can only be made during the free trial period, and only once per subscription. The call is designed to meet the needs of applications that offer restricted access during the free trial period. If a user in a free trial period wants to switch to full access, use this call to set the user's start date so you can submit an addUsage request or begin the full-access subscription and charges. The billing start date needs to be in the present or the past before the subscriber can be charged for usage or can begin to be subjected to subscription charges.
You may want to have setBillingStartDate triggered by a button in the user interface, which can be clicked by a free-trial user who intends to upgrade to a full-access subscription.
Using the addRefund call, you can make a refund to a subscriber's PayPal account. The refund will be reflected on subscriber's billing account. Using the getRefundStatus call, you can retrieve records of refunds.
This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.
© 2008–2010 eBay Inc. All rights reserved.
eBay and the eBay logo are registered trademarks of eBay Inc.
All other brands are the property of their respective owners.