Languages
Pages
Legal
Amazon SaaS Integration Guide
Subscriptions (SaaS)
2
TABLE OF CONTENTS
1. INTRODUCTION ...................................................................................................................................................................... 3
2. SUBSCRIPTION PRODUCT OFFERINGS ...................................................................................................................................... 4
3. API OVERVIEW AND SPECIFICATIONS ...................................................................................................................................... 5
ACCOUNT LINKING ENDPOINT ............................................................................................................................................................. 6
ACCOUNT REGISTRATION PAGE ........................................................................................................................................................... 7
FULFILLMENT (SERVICE) ENDPOINT ..................................................................................................................................................... 8 1. Subscription Activation ............................................................................................................................................................. 8 2. Subscription Deactivation ....................................................................................................................................................... 10 3. Subscription Update ................................................................................................................................................................ 11 4. Subscription Retrieval (Get) .................................................................................................................................................... 13 5. Free Trial Subscriptions ........................................................................................................................................................... 14
LICENSE MANAGEMENT PAGE ........................................................................................................................................................... 15
REQUEST AUTHORIZATION................................................................................................................................................................. 16
IP WHITELISTING ................................................................................................................................................................................ 17
VENDOR SLA ....................................................................................................................................................................................... 17
REQUEST RETRY POLICY ..................................................................................................................................................................... 17
4. DEVELOPER PORTAL ............................................................................................................................................................. 18
CREATING A NEW VENDOR PROFILE .................................................................................................................................................. 19
CHALLENGE ......................................................................................................................................................................................... 20
FULFILLMENT INTEGRATION TESTS .................................................................................................................................................... 21
ACCOUNT REGISTRATION PAGE REDIRECTION TEST.......................................................................................................................... 22
UPDATING AN EXISTING VENDOR PROFILE ........................................................................................................................................ 22
QUALITY ASSURANCE ......................................................................................................................................................................... 23
5. SDK DOCUMENTATION ......................................................................................................................................................... 24
JAVA SDK............................................................................................................................................................................................. 24
C# (.NET) SDK ...................................................................................................................................................................................... 25
PHP SDK .............................................................................................................................................................................................. 26
RUBY SDK ............................................................................................................................................................................................ 28
6. CUSTOMER EXPERIENCE ....................................................................................................................................................... 28
EXAMPLE CUSTOMER FLOW – SINGLE USER SUBSCRIPTIONS (SUS).................................................................................................. 29
EXAMPLE CUSTOMER FLOW – TEAM SUBSCRIPTIONS ...................................................................................................................... 32
REDIRECTING CUSTOMERS BACK TO AMAZON .................................................................................................................................. 38
7. FAQ ..................................................................................................................................................................................... 39
3
1. INTRODUCTION Welcome to Amazon Instant Access! This guide describes the steps you, as a third-party vendor, must take to integrate with Amazon’s
Instant Access offerings for Software Subscriptions (SaaS). A typical integration process is pictorially represented below:
After reviewing this guide (Step 1 in the diagram), you must create an account on Amazon Developer Portal and build a web service
to communicate with our Instant Access platform using the API discussed later. Our business team ([email protected]) will
then follow up and go through QA before launching the product detail page on the Amazon website. The integration process typically
© 2016 Amazon Confidential
Amazon SaaS Business Set-up Guide
Last updated: Mon May 22 2017 | Version 1
Integration Setup Overview
1: Profile Configuration
Review Integration GuideStep 1 Integrate with Amazon APIsStep 2 Enable QAStep 3 Launch on AmazonStep 4
Read complete integration guide including FAQs.
http://s3-us-west-2.amazonaws.com/dtg-docs/overv...
Amazon Instant Access
Integration Guide
Setup payment information in Developer Portal
https://amazon.com
Create Product Detail Page
Launch on Amazon
Payment Information
SaveCancel
1: Profile Configuration
2: Integration Test
3: Account Linking Redirection Test
Amazon.com Sign In
E-mail or mobile number:
What is your email (phone for mobile accounts)?
I am a new customer
I am a returning customer and my password is
Do you have an Amazon.com password?
Sign in using our secure server
Create a developer portal account
Push to production QA
1: Profile Configuration
2: Integration Test
3. Account Linking Redirection Test Amazon create ticket for QA
Email Amazon to include the
following 4 items:
QA takes about 2 weeks
XLS
Configuration Profile Name
Primary email address for developer portal account
Link to product images or zip file
New item setup template
ITEM 2
ITEM 3
ITEM 4
vendorProfileName1278
ITEM 1
Send
3: Account Linking Redirection Test
2: Integration Test
Your profile has been saved
successfully.
Instant Access
Instant Access
Instant Access
4
takes around 2–3 days with additional 7–10 days for testing. Please contact [email protected] at any time for assistance and
include the company name in the email subject line to make tracking easier.
2. SUBSCRIPTION PRODUCT OFFERINGS There are 2 categories of subscription products that may be offered to the customers through Amazon Instant Access:
1. Single User Subscription (SUS): This category targets customers who purchase software meant for individual use. Customers can purchase subscriptions, cancel subscriptions and set up renewal options on the Amazon website. Each SUS purchase results in one subscription for a single user.
2. Team Subscription: This category targets customers who purchase software meant for teams, where the software would typically allow users to collaborate with their colleagues and perform group activities. Contrary to SUS, each team subscription contains one or more licenses assignable to multiple users. Customers can purchase subscriptions, cancel subscriptions, set up renewal options, and purchase additional licenses for subscriptions on the Amazon website. You must provide an external web page where customers can assign and un-assign the licenses to users (more details provided in the LICENSE MANAGEMENT PAGE section later). If applicable, all role management-related functions should be provided through the page as well.
5
3. API OVERVIEW AND SPECIFICATIONS When a customer performs a key action on the Amazon website such as purchasing a subscription, we send you an HTTP request with a JSON payload to notify you of the event. Depending on the customer’s action and whether the product is an SUS or Team Subscription, the content of the payload varies. You must set up a web service to receive these incoming requests, adjust the offerings to the customers accordingly, and return HTTP responses per specification. This communication is designed to be completely synchronous. To help with the implementation, we provide SDKs in the following programming languages (more details provided in the SDK DOCUMENTATION section later):
Product Type Supported Programming Languages Single User Subscriptions (SUS) Java, Ruby, .Net and PHP
Team Subscriptions Java and Ruby
Here is an overview of the API endpoints and web pages your service must support:
• Account Linking Endpoint: This endpoint links the customers’ Amazon accounts with their third-party vendor accounts. We prompt the customers for one or more account-identifying information fields for your software/website such as username or email. The fields are configured during vendor on-boarding (more details provided in DEVELOPER PORTAL section later). We send you the field values, and you send back the user ID.
• Account Registration Page: To facilitate account linking, you must provide an external registration page where customers can create new accounts (or login with their existing ones) for your software/website. When a customer initiates the one-time setup process to activate a new subscription, we display your page in a 600 x 500 popup window. The page must redirect back to the Amazon website after the registration is complete.
• Fulfillment (Service) Endpoint: This endpoint is for fulfilling purchases. For SUS products, we call this endpoint when a customer activates or deactivates a product. For Team Subscription products, we call this endpoint in the following scenarios:
o A customer activates a new subscription o An active subscription is cancelled o New licenses are added to an existing subscription o License details for a subscription need to be displayed o Unassigned licenses need to be removed during subscription renewal
• License Management Page: This page is for Team Subscription products only. You must provide an external web page to let customers assign and un-assign licenses for your product. The page must not allow activities which affect billing (e.g. changing the number of licenses tied to subscriptions, cancelling subscriptions, renewing subscriptions or licenses). Instead, we recommend using links redirecting back to the Amazon website (see REDIRECTING CUSTOMERS BACK TO AMAZON for more details).
The URLs and endpoints are set during vendor on-boarding (more details provided in DEVELOPER PORTAL section later). You must use HTTPS and have a valid SSL certificate issued by a trusted certificate authority. We recommend purchasing the certificate from reputable sources like GoDaddy, DigiCert, Comodo and Symantec. To verify whether your SSL certificate is valid, use an online tool such as like this one: https://sslshopper.com/ssl-checker.html. Note: Please avoid certificates from Let’s Encrypt as we do not recognize them currently. In the next few pages, we cover the required components of the web service in more detail. We also go over the vendor SLAs, request authentication and retry policies.
6
ACCOUNT LINKING ENDPOINT This endpoint links the customers’ Amazon accounts with their third-party vendor accounts. We prompt the customers for one or more account-identifying information fields for your software/website such as username or email. Once we obtain the fields, we send to the endpoint an HTTP POST request with a JSON payload containing the following fields:
You must always return a response with a status code 200 (any other code is regarded as a failure) and a JSON body containing the following fields:
Field Type Required Description
response String Yes Valid response values are:
• “OK”
• “FAIL_ACCOUNT_INVALID”
userId String Yes The immutable ID on the vendor side for subsequent fulfillment API calls.
Example
HTTP POST request from Amazon to your service: { "operation": "GetUserId", "infoField1": "[email protected]", "infoField2": "MyGameCharacter" }
Response from your service back to Amazon: { "response": "OK", "userId": "550e8400" }
Health Check
Every five minutes, we call the account linking endpoint with dummy values to see if your service is running. This ensures the products on our detail pages are purchasable. Please note the extra load these periodic calls may place on the endpoint. The health check sends an HTTP POST request with the following JSON payload: { "operation":"GetUserId", "infoField1": "TESTVALUE" }
To pass the health check, your service must return a status code 200 with an “OK” response. The “userId” field is ignored.
If we do not receive the expected response, we assume the service is down and make the products unavailable for
purchase by disabling the buy button. We also send an alert email to the all-hours support email address set during the
initial vendor on-boarding. If the health check succeeds at a subsequent point, we automatically make the product
available for purchase again, and send a success notification email.
Field Type Required Description
operation String Yes The name of the operation. The value is always set to “GetUserId” in this case.
infoField1 String Yes The username or other account identifier. This field is required.
infoField2 String No An optional second identifier field configured by the vendor.
infoField3 String No An optional third identifier field configured by the vendor.
7
ACCOUNT REGISTRATION PAGE To facilitate account linking, you must provide an external registration page where the customers can create new accounts (or login with their existing ones) for the third-party software/website. When a customer initiates the one-time setup required before using a new subscription, we display the page to the customer in a 600 x 500 popup window. Once the account registration is complete, the page must redirect the customer back to the redirection URL which we provide in the query string. The page must also append to the redirection URL up to three account-identifying information fields using the “infoField1”, “infoField2” and “infoField3” query parameters.
Example Here is a sample account registration page URL: https://www.vendor.com/signup
We open the page and provide our redirection URL in the query string (note the URL encoding): https://www.vendor.com/signup?redirectUrl=https%3A%2F%2Famazon.com%3FrequestId%3D1%26subId%3D2 The value of “redirectUrl” query parameter must be decoded: https%3A%2F%2Famazon.com%3FrequestId%3D1%26subId%3D2 → https://amazon.com?requestId=1&subId=2 The redirection URL may already contain some query parameters such as “requestId” and “subId”. These parameters are subject to change and must not be altered in any way. Append the account-identifying info fields to the query string: https://amazon.com?requestId=1&subId=2&infoField1=john%40example.com&infoField2=MyGameCharacter Here are some important notes:
• Minimum of one account-identifying information field is required. This means “infoField1” is mandatory.
• The values for the information fields must be URL encoded:
o Good: &infoField1=john%40example.com o Bad: &[email protected]
• The information fields must be appended to the query string in the same order as what was configured during the initial on-boarding step (more details provided in the CREATING A NEW VENDOR PROFILE section later).
8
FULFILLMENT (SERVICE) ENDPOINT The fulfillment endpoint is for multiple fulfillment operations. For SUS products, we call this endpoint whenever a customer activates or deactivates a product. For Team Subscription products, we call this endpoint in the following scenarios:
o A customer activates a new subscription o An active subscription is cancelled o New licenses are added to an existing subscription o License details for a subscription need to be displayed o Unassigned licenses need to be removed during subscription renewal
The content of the request payload differs depending on the operation and the product type. The following operations must be supported: subscription activation, deactivation, retrieval (get) and update.
1. Subscription Activation We send a subscription activation (HTTP POST) request to the fulfillment endpoint when a customer initiates the one-time setup process required for using the newly purchased subscription. The JSON request payload contains the following fields:
Field Type Required For Description
operation String SUS, Team Subs The name of the operation. “SubscriptionActivate” in this case.
subscriptionId String SUS, Team Subs A unique identifier for the subscription.
productId String SUS, Team Subs The third-party product code identifying the item fulfilled. In most cases this would the vendor SKU.
userId String SUS, Team Subs Customer ID identifying the user to deliver the item to. This is the same ID you send on account linking calls.
numberOfLicenses Integer Team Subs only The number of licenses in the subscription the customer has access to. This number may change later as customers add or remove licenses.
You must always return a response with a status code 200 (any other code is regarded as a failure). The response body must indicate whether the activation was successful and contain the following fields:
Field Type Required For Description
response String SUS, Team Subs Valid response values are:
• “OK”
• “FAIL_USER_NOT_ELIGIBLE” – User is not eligible to purchase this item
• “FAIL_USER_INVALID” – User is invalid
• “FAIL_INVALID_SUBSCRIPTION” – Invalid values are in the JSON fields “subscriptionId” or “numberOfLicenses”
• “FAIL_OTHER” – This is a catch-all error code As the API evolves, more response values will be added and the generic value “FAIL_OTHER” will be used less and less.
numberOfUnusedLicenses Integer Team Subs only The number of licenses assigned to users.
numberOfUsedLicenses Integer Team Subs only The number of licenses currently un-assigned.
managementURL String Team Subs only The URL to the license management page. See LICENSE MANAGEMENT PAGE section for more details.
9
Example HTTP POST request from Amazon to your service for an SUS product: { "operation": "SubscriptionActivate",
"subscriptionId": "V7ZX0EWJDAYPXD9FS941", "productId": "product_A", "userId": "550e8400", }
Response from your service back to Amazon: { "response": "OK" }
HTTP POST request from Amazon to your service for a Team Subscription product: { "operation": "SubscriptionActivate",
"subscriptionId": "V7ZX0EWJDAYPXD9FS941", "productId": "product_A", "userId": "550e8400", "numberOfLicenses": 4, }
Response from your service back to us: {
"response": "OK", "numberOfUnusedLicenses": 1, "numberOfUsedLicenses": 2,
"managementURL": "https://www.vendor.com/licenses?subscriptionId=123", }
Once a subscription is successfully activated, the customer is given a link to your management page for assigning or un-assigning licenses. The page must not allow activities which affect billing (e.g. changing the license quantity, cancelling subscriptions). More details are provided in the LICENSE MANAGEMENT PAGE section later.
10
2. Subscription Deactivation We send a deactivation (HTTP POST) request to the fulfillment endpoint when a subscription is cancelled. You must revoke all licenses tied to the subscription, and return a response indicating whether the operation was successful. The request has a JSON payload with the following fields:
Field Type Required Description
operation String Yes The name of the operation. “SubscriptionDeactivate” in this case.
subscriptionId String Yes A unique identifier for the license. This is the same ID as the one Amazon sent in subscription activation calls.
period String Yes An enumerated value representing the period of a subscription’s life cycle in which this action occurred. Valid values are:
• “GRACE_PERIOD” – Action occurred during the risk-free period.
• “REGULAR” – Action occurred while the subscription was valid.
• “NOT_STARTED” – The subscription was purchased but not activated. This is used when the “UNABLE_TO_FULFILL” reason code is used. (See the “reason” field below).
• “FREE_TRIAL” – Used for free trial subscriptions.
reason String Yes An enumerated value explaining why this message was sent. Valid values are:
• “NOT_RENEWED” – The subscription reached the end of its term.
• “USER_REQUEST” – The user deactivated the subscription via Amazon.com.
• “CUSTOMER_SERVICE_REQUEST” – Deactivation initiated by Amazon Customer Service.
• “PAYMENT_PROBLEM” – Deactivation initiated due to an error in processing the customer’s payment.
• “UNABLE_TO_FULFILL” – Subscription was canceled due to a problem activating the subscription.
• “TESTING” – Test request, please ignore.
You must always return a response with a status code 200 (any other code is regarded as a failure). The response body must indicate whether the deactivation was successful and contain the following fields:
Field Description
Response Valid response values are:
• “OK”
• “FAIL_INVALID_SUBSCRIPTION” – “subscriptionId” is not recognized
• “FAIL_OTHER” – This is a catch-all error code
Example
HTTP POST request from Amazon to your service: { "operation": "SubscriptionDeactivate",
"subscriptionId":"V7ZX0EWJDAYPXD9FS941" "period": "GRACE_PERIOD", "reason": "CUSTOMER_SERVICE_REQUEST", }
Response from your service back to Amazon: { "response": "OK" }
11
3. Subscription Update This operation is for Team Subscriptions only. We send an update (HTTP POST) request to your fulfillment endpoint when the license quantity of a subscription must be changed. This occurs in the following scenarios:
o A customer purchases one or more additional licenses for an active subscription, and we send an update request to increment the license quantity on your end.
o During the renewal of a subscription, we discover that the subscription has one or more unassigned licenses. We automatically send you an update request to remove unassigned licenses on your end to avoid unnecessary charges to the customer. Customers can add back the licenses any time they want on the Amazon website.
The JSON request payload contains the following fields:
Field Type Required Description
operation String Yes The name of the operation. “SubscriptionUpdate” in this case.
subscriptionId String Yes A unique identifier for the subscription.
productId String Yes The third-party product code identifying the item fulfilled. In most cases this would the vendor SKU.
userId String Yes Customer ID identifying the user to deliver the item to. This is the same ID you send on account linking calls.
numberOfLicenses Integer No The updated number of total licenses associated with the given subscription. Any new license must be initialized in an un-assigned (assignable) state. This parameter is mutually exclusive with “removeAllUnassignedLicenses”.
removeAllUnassignedLicenses Boolean No A boolean flag to indicating whether un-assigned licenses should be removed. Mutually exclusive with “numberOfLicenses”.
You must always return a response with a status code 200 (any other code is regarded as a failure). The response body must indicate whether the update was successful and contain the following fields:
Field Type Required Description
response String Yes Valid response values are:
• “OK”
• “FAIL_USER_NOT_ELIGIBLE” – User is not eligible to purchase this item
• “FAIL_USER_INVALID” – User is invalid
• “FAIL_INVALID_SUBSCRIPTION” – Invalid values provided in the JSON fields “subscriptionId”, “numberOfLicenses”, “removeAllUnassignedLicenses”
• “FAIL_OTHER” – This is a catch-all error code As the API evolves, more response values will be added and the generic value “FAIL_OTHER” will be used less and less.
numberOfUnusedLicenses Integer Yes The number of licenses assigned to users. numberOfUsedLicenses Integer Yes The number of licenses currently un-assigned.
managementURL String Yes The URL to the license management page. See LICENSE MANAGEMENT PAGE section for more details.
12
Example A customer owns a subscription with ID V7ZX0EWJDAYPXD9FS941. The subscription has a total of 7 licenses: 5 assigned and 2 unassigned. The customer buys 2 more licenses for the subscription on Amazon.com, and we send you an HTTP POST request to increase the total license count of the subscription by 2: { "operation": "SubscriptionUpdate",
"subscriptionId": "V7ZX0EWJDAYPXD9FS941", "productId": "product_A", "userId": "550e8400", "numberOfLicenses": 9, // 7 + 2 }
Response from your service back to us should look something like this: { "response": "OK", "numberOfUnusedLicenses": 4, // 2 + 2 "numberOfUsedLicenses": 5, "managementURL": "https://www.vendor.com/manage/licenses" }
Note:
• Only the value of “numberOfUnusedLicenses” should increase, as the new licenses are not assigned yet.
• The sum of “numberOfUnusedLicenses” and “numberOfUsedLicenses” must equal “numberOfLicenses”.
• Your service is responsible for calculating the new values. Here are simple equations clarifying how: 1. oldNumberOfLicenses = oldNumberOfUnusedLicenses + oldNumberOfUsedLicenses 2. numberOfLicensesIncrease = newNumberOfLicenses - oldNumberOfLicenses 3. newNumberOfUnusedLicenses = oldNumberOfUnusedLicenses + numberOfLicensesIncrease 4. newNumberOfUsedLicenses = oldNumberOfUsedLicenses
• If we apply the above equations to this example we get the following: 1. oldNumberOfLicenses = 5 + 2 = 7 2. numberOfLicensesIncrease = 9 – 7 = 2 3. newNumberOfUnusedLicenses = 2 + 2 = 4 4. newNumberOfUsedLicenses = 5
After the billing period, the renewal process for subscription V7ZX0EWJDAYPXD9FS941 will kick in. At that point we would notice that the subscription still has 4 unassigned licenses. To avoid charging the customer extra for the next billing cycle, we send you an HTTP POST request to “clean up” the unassigned licenses from the subscription: { "operation": "SubscriptionUpdate",
"subscriptionId": " V7ZX0EWJDAYPXD9FS941", "productId": "product_A", "userId": "550e8400", "removeAllUnassignedLicenses": true, }
Response from your service back to us: { "response": "OK", "numberOfUnusedLicenses": 0, "numberOfUsedLicenses": 5, "managementURL": "https://www.vendor.com/manage/licenses" }
Note: While removing licenses, “numberOfUsedLicenses” should remain unchanged and “numberOfUnusedLicenses” should become 0.
13
4. Subscription Retrieval (Get) This operation is for Team Subscriptions only. We send a retrieval (HTTP POST) request to the fulfillment endpoint whenever we need to pull up the most recent license information on a subscription, such as the count of assigned/un-assigned licenses and the license management URL. The JSON request payload contains the following fields:
Field Type Required Description
operation String Yes The name of the operation. “SubscriptionGet” in this case.
subscriptionId String Yes A unique identifier for the subscription.
productId String Yes The third-party product code identifying the item fulfilled. In most cases this would the vendor SKU.
userId String Yes Customer ID identifying the user to deliver the item to. This is the same ID you send on account linking calls.
You must always return a response with a status code 200 (any other code is regarded as a failure). The response body must indicate whether the update was successful and contain the following fields:
Field Type Required Description
response String Yes Valid response values are:
• “OK”
• “FAIL_USER_INVALID” – User is invalid
• “FAIL_INVALID_SUBSCRIPTION” – Invalid values provided in the JSON field “subscriptionId”
• “FAIL_OTHER” – This is a catch-all error code As the API evolves, more response values will be added and the generic value “FAIL_OTHER” will be used less and less
numberOfUnusedLicenses Integer Yes The number of licenses assigned to users.
numberOfUsedLicenses Integer Yes The number of licenses currently un-assigned.
managementURL String Yes The URL to your license management page. See LICENSE MANAGEMENT PAGE section for more details.
Example HTTP POST request from Amazon to your service: { "operation": "SubscriptionGet",
"subscriptionId": "V7ZX0EWJDAYPXD9FS941", "productId": "product_A", "userId": "550e8400" }
Response from your service back to Amazon: { "response": "OK", "numberOfUnusedLicenses": 4, "numberOfUsedLicenses": 5, "managementURL": "https://www.vendor.com/manage/licenses" }
14
5. Free Trial Subscriptions
We allow free trials for both SUS and Team Subscription products by not charging the customers for a set period of time after activation (e.g. 30-days free trial). Free trial subscription activation calls look identical to regular paid subscription activation calls. When the trial period is over, we automatically roll-over the customers to a pre-configured paid subscription plan (e.g. monthly or annually) unless the customers have auto-renewal turned off for the product. The auto-renewal is enabled by default. If the auto-renewal is active and the roll-over occurs, we begin charging the customers. You specify the paid plan a free trial rolls over to with our business team during the initial vendor on-boarding. Currently, there is no way for vendors to distinguish free trial subscription activation calls from paid ones. Our business team periodically sends reports showing the breakdown of free-trials vs. paid subscriptions.
Example 1. When a customer activates free trial, we send you a subscription activation (HTTP POST) request as usual: { "operation": "SubscriptionActivate", "subscriptionId": "US-7d3001e5-9385-07b7-a107-019234a548d8", "productId": "product_A", "userId": "550e8400", }
2. The response your service sends back to Amazon: { "response": "OK" }
3. Once the trial period is over, we begin charging the customer automatically. No requests are sent to the vendor at this point. When a customer deactivates a free trial subscription before the trial period ends, the automatic roll-over does not occur. In this case, we send a subscription deactivation (HTTP POST) request where the period field is set to “FREE_TRIAL”.
Example 1. We send your service a subscription deactivation (HTTP POST) request with the period set to “FREE_TRIAL”: { "operation": "SubscriptionDeactivate", "subscriptionId":"US-7d3001e5-9385-07b7-a107-019234a548d8" "period": "FREE_TRIAL", "reason": "USER_REQUEST", }
2. The response from your service back to Amazon: { "response": "OK" }
15
LICENSE MANAGEMENT PAGE This page is required for Team Subscription products only. You must provide an external web page allowing customers to assign and un-assign licenses to users. The design of this page is completely up to you, but the page must not allow customers to perform activities which affect billing (e.g. changing the number of licenses tied to subscriptions, cancelling subscriptions, renewing subscriptions or licenses). Instead, we recommend using links redirecting back to our Amazon website (see REDIRECTING CUSTOMERS BACK TO AMAZON for more details). We send a subscription retrieval request to your fulfillment endpoint in order to obtain the URL for your license management page to relay to the customer. Here is an example URL: https://www.vendor.com/licenses.
16
REQUEST AUTHORIZATION To allow verification of whether Amazon is the initiator of an API calls, a signature is provided in the headers of all account linking and fulfillment requests. The header fields are as follows:
Header Field Description
Authorization This field is populated with the information needed to authenticate the request and consists of an HMAC style signature and the information to calculate it. This field breaks down as follows: ALGORITHM SignedHeaders=SIGNEDHEADERS, Credential=CREDENTIAL, Signature=SIGNATURE
• ALGORITHM: The algorithm for signing messages. This is always set to “DTA1-HMAC-SHA256”.
• SIGNEDHEADERS: List of signed headers names lowercased and then sorted in byte order.
• CREDENTIAL: This is in format “{KEY}/{DATE}”, where KEY is the public identifier for the secret key used to sign. DATE is the date of the full time presented in x-amz-date in UTC. Using this information secret daily key for the request is calculated. The calculation is done by signing the Date string in format YYYYMMDD with the secret key. The secret daily key is then used for the rest of the signing.
• SIGNATURE: The computed signature using the request path, query parameters, HTTP method, signed headers and body. The algorithm is the same as used in: http://docs.aws.amazon.com/general/latest/gr/sigv4-signed-request-examples.html with these major differences:
o The keys are only generated to the *day* level as the Instant Access system is a single service segmented by region, and thus secret keys are already unique to this level
o The signing key is the HMAC-256 of the secret and the x-amz-date header (none of the other region, service, etc. information is required)
o The header names and values must not be trimmed, lowered, or otherwise modified when creating the canonical headers
x-amz-request-id A unique message ID
x-amz-date The time of the request. Best practice is to discard any messages more than 30 minutes old.
x-amz-customer-id
A directed customer ID for the Amazon customer
x-amz-dta-version The API version
Example Authorization: DTA1-HMAC-SHA256 SignedHeaders=content-type;x-amz-date;x-amz-customer-id;x-amz-dta-
version;x-amz-request-id, Credential=69b2048d-8bf8-4c1c-b49d-e6114897a9a5/20170504,
Signature=ced6826de92d2bdeed8f846f0bf508e8559e98e4b0199114b84c54174deb456c
x-amz-request-id: 0A49CE4060975EAC x-amz-date: 20170504T233600Z
x-amz-customer-id: 1704344 x-amz-dta-version: 1
content-type: application/json
This page should serve only as a reference, as the SDKs automatically handle the authorization. You simply need to specify,
in the SDK code, the public and private key pair we generate for you. We cover how to trigger the key generation in
DEVELOPER PORTAL section, and how to use it in the SDK DOCUMENTATION section later.
17
Note: Please review your server setup and ensure that the Authorization header is not stripped away. For example, Apache does not, by default, pass authorization headers to PHP unless the user explicitly allows it in its configuration file.
IP WHITELISTING The request authorization is already built-in to the Instant Access API. As such, IP whitelisting for the purpose of authentication is almost always unnecessary.
If you still choose to use it for your service, The IP ranges used by Amazon are available in JSON form from here. You should expect these IP ranges to change several times a week. As such, your web service must poll the list of IP ranges and update the whitelist accordingly, as described in the linked documentation.
VENDOR SLA To provide the best experience possible to the customers, we expect all vendors to uphold the following SLAs (Service Level Agreements) for their web services:
For account-linking and subscription get API calls:
• 50% of all responses should occur within 1 second
• 99% of all responses should occur within 5 seconds
For subscription activation, deactivation and update API calls:
• 50% of all responses should occur within 5 seconds
• 99% of all responses should occur within 15 seconds.
REQUEST RETRY POLICY When API calls to your web service fail for any reason, we handle them in the following manner:
• If an account-linking API call fails, error messages are displayed to customers who can make the decision to retry
as many times as they would like.
• If a subscription activation call fails, error messages are displayed to customers who can make the decision to
retry as many times as they would like.
• If a subscription deactivation call fails, then we make a series of rapid-fire requests. If all requests failed, the
subscription marked as deactivated on our side. The subscription may not be deactivated on your end.
For Team Subscription only:
• If a subscription update call fails while adding new licenses, error messages are displayed to the customers who
can make the decision to retry as many times as they would like.
• If a subscription update call fails while removing unassigned licenses (during subscription renewal), the
customers is charged for the unassigned licenses until the next cycle.
• If a subscription retrieval (get) API call fails, we display to the customers the cached and possibly outdated
values of the license quantities. We display your license management URL to redirect the customers so they can
see the latest license details if needed.
18
4. DEVELOPER PORTAL In addition to building a web service, you must sign up for a developer account on Amazon Developer Portal and create a vendor profile. This requires the profile name, URLs for your web service, account-identifying information fields, and all-hours support email address. In order to finalize the profile, you must also pass a set of automated tests within the developer portal. The tests ensure your web service supports the API per specification, and help resolve any networking or security issues. The tests consist of two parts: fulfillment integration tests and account registration page redirection test. These are not full end-to-end tests (they occur during QA).
19
CREATING A NEW VENDOR PROFILE Below is a summary of the steps required to create a new vendor profile:
1. Create new account on developer portal:
• Go to http://developer.amazon.com and click “Sign In” at the top right of the page.
• Follow the instructions to create a new developer account. 2. Go to the Amazon Instant Access page:
• Go to http://developer.amazon.com/mac-pc/console/instantaccess/profiles.html and login with the new account.
3. Configure a new vendor profile:
• Go to “Step 1: Profile Configuration”.
• Enter the name for the new profile.
• Enter the URLs for your web service.
• Enter the all-hours support email.
• Enter up to 3 account-identifying information fields. The first field is mandatory.
• Click on “Submit”. An authorization key pair should be generated at this point.
• Click on “Show Keys” to access the key pair. Keep the private key in a secure location. 4. Host the challenges in your service:
• Follow the Challenge instructions (see CHALLENGE) for more details on this part.
5. Enable request authorization in your service using the generated key pair:
• Follow the SDK-specific instructions (see SDK DOCUMENTATION) for more details on this part.
• At this point your web service should be running and ready for end-to-end testing.
6. Run the integration tests:
• Click on “Step 2: Integration Test”.
• Select “Single User Subscriptions” or “Team Subscriptions” (depending on your product type) in the “Test Suite” dropdown.
• Enter the account-identifying information fields to be used for testing.
• Click on “Run Test” (this button is disabled until the profile configuration is complete).
• If there are any issues, resolve them and rerun the tests until everything passes. 7. Run the registration page redirection test:
• Click on “Step 3: Account Linking Redirection Test”.
• Click on “Begin Redirection Test” (this button is disabled until the integration tests pass).
• This should redirect to your own registration page in a popup window.
• Complete the registration and verify that the popup window is closed and you are redirected back.
• If there are any issues, resolve them and rerun the test until it passes.
8. Finalize the profile creation:
• Once all the tests pass, the “Save Profile” button at the bottom should be enabled.
• Click on “Save Profile” to finalize the profile creation.
• Follow the instructions on the following popup window (see QUALITY ASSURANCE). Please do not create multiple vendor profiles with the same name to avoid confusion in the future.
20
CHALLENGE After creating the profile on http://developer.amazon.com/mac-pc/console/instantaccess/profiles.html, you must host the challenges in your service endpoints to be able to run integration tests. This is required to verify your server domain. Steps to host the challenge:
• Download challenge: o Click on “Download Challenge” in your profile page to get “challenge.json” file o The “challenge.json” file contains the three challenges you need to host on your three API endpoints:
▪ linkingUrlChallenge -> linkingUrlChallenge ▪ serviceUrlChallenge -> serviceUrlChallenge ▪ registrationUrlChallenge -> registrationUrlChallenge
• Host Account Linking Challenge: o Create Account Linking Challenge API endpoint to return linkingURLchallenge string (you can find it in
challenge.json file) for a GET request. o Account Linking Challenge API endpoint is your Account Linking API endpoint
plus ”/amazonLinkingChallenge”. For example, if your Account Linking API endpoint is https://www.example.com/linkAccount then your Account Linking Challenge API endpoint will be https://www.example.com/linkAccount/amazonLinkingChallenge
• Host Fulfillment Challenge: o Create Fulfillment Challenge API endpoint to return serviceURLchallenge string (you can find it in
challenge.json file) for a GET request. o Fulfillment Challenge API endpoint is your Fulfillment API endpoint plus ”/amazonServiceChallenge”. For
example, if your Fulfillment API endpoint is https://www.example.com/purchaseAccount then your Fulfillment Challenge API endpoint will be https://www.example.com/purchaseAccount/amazonServiceChallenge
• Host Account Registration Challenge: o Create Account Registration Challenge API endpoint to return registrationURLchallenge string (you can
find it in challenge.json file) for a GET request. o Account Registration Challenge API endpoint is your Account Registration API endpoint
plus ”/amazonRegistrationChallenge”. For example, if your Account Registration API endpoint is https://www.example.com/register/amazon then your Account Registration Challenge API endpoint will be https://www.example.com/register/amazon/amazonRegistrationChallenge
21
FULFILLMENT INTEGRATION TESTS The integration tests check account linking, subscription activation, subscription deactivation, subscription get and subscription update API calls. The following test scenarios are run to see if the fulfillment integration has been successfully carried out:
Test Case Expected Behavior
Account linking with valid user: We send you one account linking request with the account-identifying information fields (e.g. email) set in the test page.
The response should be “OK” and the user ID mapping to the account-identifying information fields should be returned.
Account linking duplicate call with same valid user: We send you two duplicate account linking requests with the account-identifying information fields (e.g. email) set in the test page.
The response should be “OK” and the user ID mapping to the account-identifying information fields should be returned for both requests. The number of requests should not affect the user ID returned.
Account linking with invalid user: We wend you one account linking request with all three account-identifying information fields set to string value “DTG_INVALID_USER_INFO”.
The response field should be “FAIL_ACCOUNT_INVALID”. The user ID field should be set to null or an empty string. In order for this test to be meaningful, you should not implement separate logic around string value “DTG_INVALID_USER_INFO” just to pass the test.
Subscription activation with valid user and valid product: We send you one valid account linking request to get a user ID. Then we send you one subscription activation request with the user ID, random subscription ID, and the product ID set in the test page.
The response should be “OK” and you should fulfill the item for the correct user.
Subscription activation twice with valid user and valid product: We send you one valid account linking request to obtain a userId. Then we send you two duplicate subscription activation requests with the userId, random subscription ID, and the product ID set in the test page. The same subscription ID is sent for both requests.
The response should be “OK” and your service should recognize the subscription is already active and act accordingly for the second request (e.g. log the event but do nothing).
Subscription activation for invalid user: We send you one subscription activation request with an invalid user ID with prefix “invaliduserid”, random subscription ID, and the product ID set in the test page.
The response should be “FAIL_USER_INVALID”. In order for this test to be meaningful, you should not implement separate logic around prefix “invaliduserid” just to pass the test.
Subscription activation for invalid product: We send you one valid account linking request to obtain a user ID. Then we send you one subscription activation request with the user ID, random subscription ID, and an invalid product ID with string value “DTG_INVALID_PRODUCT_ID”.
The response should be “FAIL_OTHER”. In order for this test to be meaningful, you should not implement separate logic around string value “DTG_INVALID_PRODUCT_ID” just to pass the test.
Subscription deactivation for valid user and valid product: We send you one valid account linking request to get a user ID. Then we send you valid subscription activation request with the user ID, random subscription ID, and the product ID you set in the test page. Then we send you a subscription deactivation request for the same subscription ID.
The response should be “OK” and the subscription should be deactivated on your end.
Subscription deactivation twice: We send you one valid account linking request to get a user ID. Then we send you one valid subscription activation request with the user ID, random subscription ID, and the product ID set in the test page. Then we send you two duplicate subscription deactivation requests for the same subscription ID.
The response should be “OK”. Your web service should recognize the subscription is already deactivated and act accordingly for the second request (e.g. log the event but do nothing).
Subscription get for valid user and valid product (Team Subscription only): We send you one valid account linking request to get a user ID. Then we send you a valid subscription activation request with the user ID, random subscription ID, and the product ID set in the test page. Then we send you a subscription get request with the same subscription ID.
The response should be “OK” and the correct subscription mapping to the subscription ID should be returned.
Subscription get after deactivation for valid user and valid product (Team Subscription only): We send you one valid account linking request to get a user ID. Then we send you a valid subscription activation request with the user ID, random subscription ID, and the product ID set in the test page. Then we send you a subscription deactivation request for the same subscription ID. Then we send you a subscription get request with the same subscription ID.
The response should be “FAIL_INVALID_SUBSCRIPTION”.
Subscription update for valid user and valid product (Team Subscription only): We send you one valid account linking request to get a user ID. Then we send you a valid subscription activation request with the user ID, random subscription ID, and the product ID set in the test page. Then we send you a subscription update request for the same subscription ID to increment the license quantity.
The response should be “OK” and the subscription’s number of unused licenses should be increased by the correct amount.
Some test cases send multiple requests, but the results table in the test page displays details of the last request only. All test cases are independent from each other.
22
ACCOUNT REGISTRATION PAGE REDIRECTION TEST This test checks the customer’s ability to register a new account with your registration page, and to ensure it redirects back to us with correct query parameters.
• Once the test is initiated, a popup window opens displaying the registration page.
• If the window does not show the correct location, correct the value in “Account Registration URL” textbox.
• Register a new account in the registration page.
• If registration takes longer than two minutes, the window times out and the test fails.
• If your configuration is correct, the window should automatically close.
• If the test is not successful, check the “Test Results” section for advice on resolving the issue.
UPDATING AN EXISTING VENDOR PROFILE Below is a summary of the steps required to update an existing vendor profile:
1. Go to the Amazon Instant Access page:
• Go to http://developer.amazon.com and login with the existing account.
• Click on “APPS & SERVICES” and then on “PC/Mac & Web Instant Access”. 2. Update the vendor profile:
• Go to “Step 1: Profile Configuration”.
• Select the profile to update in “Configuration Profile” dropdown.
• Make any necessary changes to the profile.
• The authentication key pair cannot be changed once generated.
• If the private key was compromised, contact [email protected].
3. Run the integration tests:
• Click on “Step 2: Integration Test”.
• Select “Single User Subscriptions” or “Team Subscriptions” (depending on your product type) in the “Test Suite” dropdown.
• Enter the account-identifying information fields to be used for testing.
• Click on “Run Test” (this button is disabled until the profile configuration is complete)
• If there are any issues, resolve them and rerun the tests until everything passes. 4. Run the registration page redirection test:
• Click on “Step 3: Account Linking Redirection Test”.
• Click on “Begin Redirection Test” (this button is disabled until the integration tests pass)
• This should redirect to your own registration page in a popup window.
• Complete the registration and verify that the popup window is closed and you are redirected back.
• If there are any issues, resolve them and rerun the test until it passes.
5. Finalize the profile update:
• Once the tests pass, the “Save Profile” button at the bottom should be enabled.
• Click on “Save Profile” to finalize the profile update.
• The instructions in the popup window is only for first time creation and can be ignored. Note: The integration tests and the registration page direction test must re-run after any change to the vendor profile.
23
QUALITY ASSURANCE After finalizing the profile on the Amazon Developer Portal, you must submit for QA the following information to [email protected]:
• The name of the vendor profile on the Instant Access page.
• The primary email address of the Amazon Developer Portal account.
• A link or zip file containing the image assets including a company logo, main product image and up to 6 additional supporting images. Please follow the video and image guidelines here.
• Completed NIS (New Item Setup) excel sheet found here. An example can be found here.
• If applicable, details on any free trial plans to set up (this is for Team Subscription products only). Please include the length of the trial period and the paid plan to roll over to if there are multiple options.
24
5. SDK DOCUMENTATION The SDK itself has more detailed documentation on individual functionality. This section has brief information as an
introduction. Please ignore the naming convention such as “DTA” (short for “Direct to Account”) and interfaces in the SDK
codebase such as “FulfillPurchase” and “RevokePurchase” as they serve a different product.
JAVA SDK The Java SDK includes two servlets, AccountLinkingServlet and PurchaseServlet.
• The AccountLinkingServlet supports the account linking API call.
• The PurchaseServlet supports SubscriptionActivate, SubscriptionDeactivate, SubscriptionGet and SubscriptionUpdate API calls.
• Both servlets need a credential store with a valid key, provided during the profile configuration in the developer portal.
The SDK can be found on GitHub – https://github.com/amzn/amazon-instant-access-sdk-java Credential Store A CredentialStore is needed for request authorization. /* * Class used to manage the credential */ public class CredentialStore { private HashMap<String, Credential> store; public CredentialStore() { store = new HashMap<String, Credential>(); } }
The getCredentialStore function must return a valid CredentialStore object. /** * Returns the credential store * * @return a CredentialStore object with the credential */ public abstract CredentialStore getCredentialStore();
This object can be built from:
• A file with the credential pairs
• An InputStream
• A String. If a credential file is used, it must contain a secret key and a public key separated by a space as follows: 69b2048d-8bf8-4c1c-b49d-e6114897a9a5 dce53190-1f70-4206-ad28-0e1ab3683161
25
Account Linking In order to implement the Account Linking API using the SDK, extend the AccountLinkingServlet and implement one abstract method – GetUserId. /** * Process the request and returns the user id * * @param request: the request relative to the get user id operation * @return: a GetUserIdSerializableResponse object */ public abstract GetUserIdSerializableResponse getUserId(GetUserIdSerializableRequest request);
Subscription Activate In order to implement the Subscription Activate API using the SDK, extend the PurchaseServlet class and implement one abstract method – processSubscriptionActivate. /** * Process the activation request and return the response to whether or not the request succeeded * * @param request: the request with information about the subscription * @return: a SubscriptionResponse object */ public abstract SubscriptionResponse processSubscriptionActivate(SubscriptionActivateRequest request);
Subscription Deactivate In order to implement the Subscription Deactivate API using the SDK, extend the PurchaseServlet class and implement one abstract method – processSubscriptionDeactivate. /** * Process the deactivation request and return the response to whether or not the request succeeded * * @param request: the request with information about the subscription * @return: a SubscriptionResponse object */ public abstract SubscriptionResponse processSubscriptionDeactivate(SubscriptionDeactivateRequest request);
Subscription Get In order to implement the Subscription Get API using the SDK, extend the PurchaseServlet class in package com.amazon.dtasdk.v3.servlets and implement one abstract method – processSubscriptionGet. /** * Process the get request and return the response to whether or not the request succeeded * * @param request: the request with information about the subscription * @return: a SubscriptionGetResponse object */ public abstract SubscriptionGetResponse processSubscriptionGet(SubscriptionGetRequest request);
Subscription Update In order to implement the Subscription Update API using the SDK, extend the PurchaseServlet class in package com.amazon.dtasdk.v3.servlets and implement one abstract method – processSubscriptionUpdate. /** * Process the update request and return the response to whether or not the request succeeded * * @param request: the request with information about the subscription * @return: a SubscriptionResponse object */ public abstract SubscriptionResponse processSubscriptionUpdate(SubscriptionUpdateRequest request);
C# (.NET) SDK The C# (.NET) SDK currently does not support Team Subscriptions. The documentation below is only for SUS.
26
The C# SDK includes two controllers, AccountLinkingController and PurchaseController.
• The AccountLinkingController supports the account linking API call.
• The PurchaseController supports the ProcessSubscriptionActivate and ProcessSubscriptionRevoke API calls.
• Both controllers need to implement the CredentialStore object with a valid key, provided during the profile configuration in the developer portal.
The SDK can be found on GitHub – https://github.com/amzn/amazon-instant-access-sdk-net Credential Store An overridden CredentialStore object needed for authenticating messages. It must be implemented in both controllers. protected override CredentialStore CredentialStore { get; } = new CredentialStore("private_key", "pub_key");
The CredentialStore object must be initialized. Ensure the parameters are entered in the right order. The abstract controller methods then handle all signature verification automatically. Account Linking In order to implement Account Linking API using the SDK, extend the controller class AccountLinkingController and implement one abstract method – GetUserId. /// <summary> /// Processes getUserId requests. /// </summary> /// <returns>A <see cref="Task{T}"/> of <see cref="GetUserIdResponse"/></returns> protected override Task<GetUserIdResponse> GetUserId(GetUserIdRequest request);
Subscription Activation To implement the Subscription Activation API using the SDK, extend the PurchaseController class and implement one abstract method – ProcessSubscriptionActivate. /// <summary> /// Processes Subscription Activation requests. /// </summary> /// <returns>A <see cref="Task{T}"/> of <see cref="SubscriptionResposne"/> or an exception if bill once purchases are not supported.</returns> protected override Task<SubscriptionResponse> ProcessSubscriptionActivate(SubscriptionActivateRequest request);
Subscription Deactivation To implement the Subscription Deactivation API using the SDK, extend the PurchaseController class and implement one abstract method – ProcessSubscriptionRevoke. /// <summary> /// Processes Subscription Revoke (Deactivate) requests. /// </summary> /// <returns>A <see cref="Task{T}"/> of <see cref="SubscriptionResponse"/> or an exception if bill once purchases are not supported.</returns> protected override Task<SubscriptionResponse> ProcessSubscriptionRevoke( SubscriptionDeactivateRequest request);
PHP SDK The PHP SDK currently does not support Team Subscriptions. The documentation below is only for SUS. The PHP SDK includes two controllers, AccountLinkingController and PurchaseController.
• Each controller is stood up on a separate endpoint.
27
• The AccountLinkingController supports the account linking API call.
• The PurchaseController supports the subscription activation and deactivation API calls.
• Both controllers need a credential store with a valid key, provided during profile configuration in the developer portal.
The controller’s lifecycle is as follows:
1. Controller is created by passing a valid CredentialStore. 2. Callbacks are assigned to the corresponding operations. 3. Function process is called passing the $_SERVER variable, where the request is validated and the proper callback
is called. 4. The return of process is sent as a response. 5. Controller is destroyed.
When using the controllers, ensure the response does not send any other extraneous information. The SDK can be found on GitHub – https://github.com/amzn/amazon-instant-access-sdk-php Credential Store A CredentialStore object needs to be passed when creating the controllers. The CredentialStore can either load keys from a file through the function loadFromFile or from a string through load. $credentialStore = new CredentialStore(); $credentialStore->loadFromFile('/path/to/file'); $credentialStore->load('secret public');
Each line of the file/string must contain a secret key and a public key separated by an empty space. For example: 69b2048d-8bf8-4c1c-b49d-e6114897a9a5 dce53190-1f70-4206-ad28-0e1ab3683161
Account Linking In order to implement the Account Linking API using the SDK, use the controller class AccountLinkingController and pass a callback to onGetUserId. The callback receives a GetUserIdRequest object and returns a GetUserIdResponse. Example Code: $controller = new AccountLinkingController($credentialStore); $controller->onGetUserId(function ($req) { $id = $db->getId($req->getInfoField1(),$req->getInfoField2()); $res = new GetUserIdResponse(); if ($id) { $res->setResponse(GetUserIdResponseValue::OK); $res->setUserId($id); } else { $res->setResponse(GetUserIdResponseValue::FAIL_ACCOUNT_INVALID); } return $res; }); $response = $controller->process($_SERVER); echo $response;
Purchase Controller In order to implement the Purchase API using the SDK, use the controller class PurchaseController and implement callbacks to two operations – onSubscriptionActivate and onSubscriptionDeactivate.
• SubscriptionActivate – This callback receives a SubscriptionActivateRequest object and returns a SubscriptionActivateResponse object.
28
• SubscriptionDeactivate – This callback receives a SubscriptionDeactivateRequest object and returns a SubscriptionDeactivateResponse object.
Example code: $controller = new PurchaseController($credentialStore); $controller->onSubscriptionActivate(function ($req) { $res = new SubscriptionActivateResponse(); $res->setResponse(SubscriptionActivateResponseValue::OK); return $res; }); $controller->onSubscriptionDeactivate(function ($req) { $res = new SubscriptionDeactivateResponse(); $res->setResponse(SubscriptionDeactivateResponseValue::OK); return $res; }); $response = $controller->process($_SERVER); echo $response;
RUBY SDK The Ruby SDK is slightly different from other SDKs.
• The SDK is a simple library for request authorization only
• No controller code is provided to avoid restriction to a specific web framework The SDK can be found on GitHub – https://github.com/amzn/amazon-instant-access-sdk-ruby. Example code for Ruby on Rails: require 'amazon-instant-access' class VendorFulfillmentController < ApplicationController def create credentials = {'public_key' => 'secret_key'} auth = AmazonInstantAccess::Authentication.new(credentials) auth.verify_request(request.method, request.url, request.raw_post, request.headers) operation = params['operation'] if operation == 'SubscriptionActivate' # Vendor logic elsif operation == 'SubscriptionDeactivate' # Vendor logic end render json: {response: 'OK'}, status: :ok end end
Please refer to the README on the GitHub page for more information on how to use the SDK.
6. CUSTOMER EXPERIENCE This section describes how the digital purchase experience looks like to Amazon customers once we complete the integration process.
29
EXAMPLE CUSTOMER FLOW – SINGLE USER SUBSCRIPTIONS (SUS) 1. A customer locates an SUS product on the Amazon website through search, product recommendation, or a direct
product link. The customer selects the number of licenses to purchase and clicks “Add to Cart”:
2. The customer is redirected to the order review screen. The customer clicks “Place your order”:
3. The customer sees the success page and clicks “Your Games and Software Library” to view the new subscription:
30
Note: It may take some time for the fulfillment operation to go through, and subscription may not be accessible right away. A notification email is sent to the customer once it is ready to be used.
4. The customer is redirected to the “Subscriptions” page. The customer clicks “Manage Licenses”:
5. The customer is redirected to the “Licenses” page. The customer clicks “Add email to assign license” to assign the license and initiate the account linking process:
31
6. The customer is presented with the account linking page. The customer links the subscription to a new third-party account by clicking “Create new account and link”, or to an existing account by filling in the information fields on the right-hand side and clicking “Link existing account”:
7. If the customer clicks “Create new account and link”, your registration page is displayed in a pop-up window. The customer either creates a new account or logs in with an existing one (only if your registration page supports logins) to link to the Amazon account:
Once the form submission is complete, account linking and subscription activation calls are sent to your web service.
32
8. When the API calls succeed, the item is fulfilled and the customer is redirected back to “Your Game and Software Library” page. At this point the customer can return to the “Licenses” page to manage the license:
If customer clicks “Cancel license”, a subscription deactivation call is queued up to be sent to your fulfillment endpoint in the next renewal cycle. The customer can also click “Turn off auto-renewal” to disable the subscription renewal.
EXAMPLE CUSTOMER FLOW – TEAM SUBSCRIPTIONS
33
1. A customer locates a Team Subscription product on the Amazon website through search, product recommendation, or a direct product link. The customer selects the number of licenses to purchase and clicks “Add to Cart”:
2. The customer is redirected to the order review screen, and clicks “Place your order”:
3. The customer sees the success page and clicks “Your Games and Software Library” to view the new subscription:
34
Note: It may take some time for the fulfillment operation to go through, and subscription may not be accessible right away. A notification email is sent to the customer once it is ready to be used.
4. The customer is redirected to the “Subscriptions” section in “Your Games and Software Library” page. The customer
clicks “Setup Account” to initiate the account linking process:
Note: The “Access Product” button is disabled until the account linking is complete and the subscription is activated.
5. The customer is presented with the account linking page. The customer links the subscription to a new third-party account by clicking “Create new account and link”, or to an existing one by filling in the account information fields on the right-hand side and clicking “Link existing account”:
35
6. If the customer clicks “Create new account and link”, your registration page is displayed in a pop-up window. The customer either creates a new account or logs in to an existing one (only if your registration page supports logins) to link to the Amazon account:
Once the form submission is complete, account linking and subscription activation calls are sent to your web service.
7. When the subscription activation succeeds, the item is fulfilled and the customer is redirected back to “Your Game and Software Library” page. At this point, the customer can click “Access Product” to visit your license management page, or clicking “Add” to buy additional licenses for the subscription:
36
Once the customer specifies the license quantity and clicks “Add licenses”, a subscription update call is sent to your web service.
The customer can click on the information icon to view the license details. At this point, a subscription retrieval (get) call is sent to your web service. The custom can click “admin console” to visit your license management page:
If the subscription retrieval (get) API call fails for any reason, we display an error message or cached values instead:
37
The customer can click “Cancel subscription” (see previous screenshot) to deactivate the subscription, at which point a subscription deactivation call is queued up to be sent to your fulfillment endpoint in the next renewal cycle:
Note: The customer can click “Undo cancellation” to undo the cancellation any time before the renewal takes place.
Lastly, the customer can click “Turn off auto-renewal” to disable subscription renewal:
38
Note: Billing and rollovers are handled completely by Amazon, and no API calls are sent to your service.
REDIRECTING CUSTOMERS BACK TO AMAZON
39
As customers manage all billing related activities within their Amazon accounts, we recommend you to update your management page(s) to redirect the customers to our Amazon website (for any activity which affect billing) by linking them to the following URL:
https://www.amazon.com/dsv/subscriptions?subscriptionId={AmazonSubscriptionID}
Where “{AmazonSubscriptionID}” is the subscription ID we send to your fulfillment endpoint.
Example Here's an example with an ID filled in (please note this example link directs to our top-level subscriptions management page, as this sample subscription ID does not belong to an actual Amazon account):
https://www.amazon.com/dsv/subscriptions?subscriptionId=54f73a82-08c2-4c7c-9715-bc5274a6139c
7. FAQ
1. Are we allowed to send a "Welcome Email" to our customers who register through Amazon?
Absolutely. We have several vendors who send "welcome kit" emails to customers. These emails can tell them about the
product, how to navigate, engage, etc. These are fine as long as these emails don't encourage a customer to move to
purchase directly from the vendor or describe confusing billing.
2. I went to view my products on Amazon.com and they were not purchasable. What happened?
Amazon has a service periodically monitoring the health of all of its vendors. This is to ensure products available on
the detail pages are actually purchasable in order to provide the best experience possible to Amazon customers. If we
detect your end point is not working as intended, we make your products unavailable to maintain a good customer
experience. When Amazon detects your end point is back functioning, the availability of your products is restored.
3. I'm getting a lot of requests to my system's endpoint. Why is this?
Amazon sends automated health checks to all vendors to ensure they are available to process requests we might be
sending. To ensure a consistent and positive customer experience, we disable your products if your system is in an
unhealthy state.
4. Are we allowed to show billing details and renew dates to our customers?
You should not show billing details and renew dates to the customers. You have the date the customer activated the
products, whereas Amazon has the date the customer purchased the products. There could be a gap between the two
dates.
Top Related