Subscribe with Amazon Getting Started Guide

Subscribe with Amazon Getting Started Guide

Last updated May 15, 2017

1

Change log 5/15/2017 : Added business reports section. 5/15/2017 : Added customer service section. 4/10/2017 : Updated Seller Central references. 10/24/2016 : Added supported HTML notes. 12/14/2016 : Added API call throttling notes. 10/24/2016 : Added Sample Seller section. 10/24/2016 : Added Sandbox section.

9/1/2016 : Updated Get Subscription API response format. 7/14/2016 : Updated LWA setup instructions. 6/15/2016 : Updated API endpoint to v3. Introduced beneficiaryType in API calls and the beneficiaries

parameter in API responses. 6/15/2016 : Updated push notifications to notificationVersion 2. Introduced the beneficiaries pa-

rameter in push notifications.

2

Contents

1 Overview

5

1.1 What is Subscribe with Amazon? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.2 How does Subscribe with Amazon work? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2 Getting Started

6

2.1 Integration checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2.2 Bank account and tax setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2.3 Adding your Product listing details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2.3.1 Create a Product listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.3.2 Add Product information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.3.3 Add Tiers & Offers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2.3.4 Add images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.3.5 Add a Compare Tiers chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2.3.6 View your product detail page in preview mode . . . . . . . . . . . . . . . . . . . . . . 10

2.4 Setting up your Login with Amazon application . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2.5 Setting your push notification preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2.6 (Optional) Setting up Sample Seller, an example storefront . . . . . . . . . . . . . . . . . . . 12

3 Integrating with Login with Amazon

12

3.1 Adding the Login with Amazon button to your website . . . . . . . . . . . . . . . . . . . . . 12

3.2 Addding the Login with Amazon button to your iOS app . . . . . . . . . . . . . . . . . . . . 12

3.3 Adding the Login with Amazon button to your Android app . . . . . . . . . . . . . . . . . . 12

3.4 Integrating with your existing account system . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

4 Integrating with Subscribe with Amazon

13

4.1 Website and/or app integration with the SWA APIs: Overview . . . . . . . . . . . . . . . . . 13

4.1.1 How a subscription gets created . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

4.1.2 Caching Subscriptions from SWA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

4.1.3 Required changes to user account management . . . . . . . . . . . . . . . . . . . . . . 15

4.1.4 CS/CRM/Operations integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4.2 Website and/or app integration with the SWA APIs: Full specification . . . . . . . . . . . . . 15

4.2.1 Security API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4.2.2 Pagination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

4.2.3 Response codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4.2.4 The subscription object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4.2.5 List Subscriptions API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

4.2.6 Get Subscription API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

4.2.7 Get Pricing Terms API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

4.3 Website and/or app integration with the SWA APIs: Push notification specification . . . . . 22

4.3.1 Push notification overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

4.3.2 Why use push notifications? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

4.3.3 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

4.3.4 Retries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

4.3.5 Message format for the ACTIVATED event . . . . . . . . . . . . . . . . . . . . . . . . . . 23

4.3.6 Message format for the RENEWED event . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

4.3.7 Message format for the CANCELLED event . . . . . . . . . . . . . . . . . . . . . . . . . . 23

3

5 Testing and Submitting your Product

24

5.1 (Optional) Testing in the Sandbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

5.1.1 Making a direct Sandbox API call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

5.1.2 Simulating a customer login with the Sandbox . . . . . . . . . . . . . . . . . . . . . . 25

5.2 Testing your integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

5.2.1 Test scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

5.3 Submitting your Product for approval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

5.3.1 Submission process overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

5.3.2 How to submit your Product for approval . . . . . . . . . . . . . . . . . . . . . . . . . 26

6 Business Reports and Customer Service

27

6.1 Business reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

6.1.1 Transaction report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

6.1.2 Payment report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

6.1.3 Tax report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

6.1.4 Subscription report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

6.2 Customer service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

6.2.1 Use cases resolved by Amazon customer service . . . . . . . . . . . . . . . . . . . . . . 28

6.2.2 How to refer a customer to Amazon customer service . . . . . . . . . . . . . . . . . . . 28

6.2.3 Amazon customer service referrals to your CS department . . . . . . . . . . . . . . . . 28

4

1 Overview

1.1 What is Subscribe with Amazon?

Subscribe with Amazon (SWA) is a cross-industry subscription management service targeted at a broad variety of sellers engaged in subscription commerce. It offers a convenient way for customers to sign up for and manage subscriptions on , and then use their Amazon account information to access those subscriptions on the sellers sites and/or apps via the Login with Amazon (LWA) button.

1.2 How does Subscribe with Amazon work?

SWA allows customers to subscribe to your products on using their Amazon account. Amazon manages the billing relationship with customers, as well as managing subscription lifecycle events such as activation, renewal, and cancellation. Sellers are responsible for allowing customers to log in with their Amazon accounts and providing service to active subscribers based on the subscription status maintained by Amazon.

Figure 1: First, the customer purchases the subscription on from an SWA seller.

Figure 2: Then, the customer logs into the subscription provider's website or app using Login with Amazon. The subscription provider checks if a subscriber has active SWA subscriptions and serves the appropriate content or experience.

5

2 Getting Started

In this guide we will show you how to set up a Subscribe with Amazon Product detail page on , add the Login with Amazon button to your website and/or app, complete integration so you can authenticate and grant access to SWA subscribers, and publish your Product live to .

2.1 Integration checklist

As you proceed through the setup and integration process, please consult the following checklist of integration activities:

Provide the required banking and 1099K tax information (section 2.2).

Create your Product listing(s) and reviewed the detail page in preview mode (section 2.3).

Add the Login with Amazon button to all locations in your website and app(s) where a customer can log in (section 2.4, 3.1 - 3.3).

Enable customers with existing accounts on your website or app to link those accounts to their Amazon accounts (section 3.4).

Set your push notification preferences and provided a valid HTTPS endpoint if you choose to receive push notifications (section 2.5).

Perform technical integration with the SWA APIs to grant access to Amazon customers when they log in (section 4.1 - 4.3).

Modify your account management links to direct the customer to Amazon's subscription manager (section 4.1.3).

Update your CS/CRM/Operations tools so they can look up the account status of the customer (section 4.1.4).

Test your LWA and SWA integration (section 5).

Submit your Product to Amazon for approval (section 5.3).

Ensure that your internal customer service processes and public-facing help content are updated to support SWA customers (section 6.2).

2.2 Bank account and tax setup

If you are a new SWA seller, you will need to provide bank account and 1099K tax information before you can publish a Product listing. Log in to your SWA seller account at , and then click the "Provide banking and tax information" button and follow the instructions on the screen.

2.3 Adding your Product listing details

As an SWA seller, you will create one or more subscription Product listings. A listing is represented by a product detail page on , where customers can discover, learn about, and purchase your subscription offerings. Customers can find your listings by searching or browsing the Amazon catalog, viewing on-site recommendations, or navigating directly to a product detail page URL. Creating a listing also allows your Amazon customers to view their subscriptions in Your Digital Subscriptions. A complete listing contains a Product, Tier, and Offers.

6

2.3.1 Create a Product listing

Log in to your SWA seller account at , and then click the yellow Get started button in the "Add product details" section to create a Product listing. You must provide the information below to create a complete Product listing.

2.3.2 Add Product information

A Subscribe with Amazon listing starts with a Product. Generally, a Product is a grouping that represents an overall subscription service or app that may contain different Tiers (i.e. service levels). Customers will see the Product name in search results, product detail pages, orders, and in Your Digital Subscriptions. Creating a Product generates an product detail page, to which you will later add Tiers, Offers, images, and product information. Follow the instructions on the screen to provide the required Product information as described below.

Product name: Your Product name will appear at the top of the product detail page, in search results, in Your Memberships & Subscriptions, and on order confirmation screens. Your Product name should match how you refer to your subscription offering on your website or app, if applicable. Do not include details about specific Tiers or Offers in your Product name.

Login URL: The default webpage where users log in to your website to access their subscription, once their account has been successfully created or linked. This page will be displayed during the post-purchase flow and also accessible from Your Memberships & Subscriptions. If you prefer to use a separate log in page for mobile devices, please provide this URL by checking the box next to I have a dedicated page for mobile devices.

Category and subcategory: Categorization will affect placement in search and browse, and help Amazon customers discover your listings. Each category contains a different set of subcategories, so make sure to select the right category before browsing subcategories. You should choose the most specific available subcategory that matches your Product, though note that not all categories include subcategories. If you cannot find an appropriate category or subcategory, select Other.

Product description: This description will appear in the Product details section of the Amazon detail page. It is recommended that you utilize this field to describe the Product and its benefits. Your Product description may not contain any URLs. This field supports the following HTML tags: , , , , , , , , , , , and .

The fine print/important restrictions: Use this field to describe any access restrictions for your Product (e.g. ``requires a minimum 3G connection for mobile access''). By default, your Product will only be available on to US-based customers, so you should not repeat that restriction here. Do not use this field to describe Product benefits or features. This field supports the following HTML tags: , , , , , , , , , , , and .

Communication preferences URL: A webpage where customers customize their communication preferences and unsubscribe from emails.

Terms of use URL: A webpage where customers access the terms of use for your Product. Must not require customers to log in.

Privacy policy URL: A webpage where customers access the privacy policy for your Product. Must not require customers to log in.

7

Customer service email address: An email address where SWA subscribers can access customer service for your Product. Amazon will instruct customers to contact your customer service department only when necessary. You must provide an email address or a phone number, or both.

Customer service phone number: A phone number where SWA subscribers can access customer service for your Product. Amazon will instruct customers to contact your customer service department only when necessary. You must provide an email address or a phone number, or both.

At any time, you may click Save without publishing in the bottom left corner to return to the Seller Central home page. When finished with the Product tab, click Continue to proceed to the Tiers & Offers tab.

2.3.3 Add Tiers & Offers Once youve created a Product, you will add one to three Tiers. A Tier is a specific level of service that a customer can subscribe to within your subscription Product. For example, you might offer a ``Premium Tier'' and a ``Basic Tier'' that provide different sets of benefits to subscribers. Customers will be able to select from your available Tiers on a single Product detail page (maximum three Tiers).

You must add one to three Offers to each Tier. An Offer is a specific pricing and payment option for customers to subscribe to a Tier (maximum three Offers per Tier). For example, you might offer your Premium Tier for either $99/year or $10/month, each of which is represented as an Offer within that Tier. Customers will be able to choose from your available Offers from the Buy Box in the upper right section of the product detail page after selecting a Tier. An Offer includes a base price (required), a free trial (optional), and an introductory pricing period (optional).

Follow the instructions on the screen to provide the required Tier and Offer information as described below.

Tiers

Tier name: Your Tier name will be selectable on the Amazon detail page and viewable in search results. Your Tier name should match how you refer to this level of service on your website or app, if applicable. Do not include details about pricing in the Tier name. At times, Amazon will represent a Tier by concatenating the Product name with the Tier name (i.e. ``Product Name: Tier Name'') so please do NOT include the Product name within the Tier name.

productId: The Tier productId is the 10-character alphanumeric identifier that Amazon will use in API calls when referencing a customers subscription. A productId must be unique across Products and Tiers within your SWA seller account, as they describe the subscription you grant to customers when they log in to your website or app. Please see section 4.2.4 for more details.

Tier description: The Tier description will appear immediately below the main product images on the product detail page. It is recommended that you utilize this field to describe the Tier and its benefits. This field supports the following HTML tags: , , , , , , , , , , , and .

Product tax code (optional): The tax code that Amazon will use to calculate sales tax on sales of this Tier (only if you have enabled Amazon Tax Collection Services; refer to . com/gp/tax-manager/dashboard.html for more details).

8

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download