Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Sell your API Gateway APIs through Amazon Web Services Marketplace

After you build, test, and deploy your APIs, you can package them in an API Gateway usage plan and sell the plan as a Software as a Service (SaaS) product through Amazon Web Services Marketplace. API buyers subscribing to your product offering are billed by Amazon Web Services Marketplace based on the number of requests made to the usage plan.

To sell your APIs on Amazon Web Services Marketplace, you must set up the sales channel to integrate Amazon Web Services Marketplace with API Gateway. Generally speaking, this involves listing your product on Amazon Web Services Marketplace, setting up an IAM role with appropriate policies to allow API Gateway to send usage metrics to Amazon Web Services Marketplace, associating an Amazon Web Services Marketplace product with an API Gateway usage plan, and associating an Amazon Web Services Marketplace buyer with an API Gateway API key. Details are discussed in the following sections.

For more information about selling your API as a SaaS product on Amazon Web Services Marketplace, see the Amazon Web Services Marketplace User Guide.

Initialize Amazon Web Services Marketplace integration with API Gateway

The following tasks are for one-time initialization of Amazon Web Services Marketplace integration with API Gateway, which enables you to sell your APIs as a SaaS product.

List a product on Amazon Web Services Marketplace

To list your usage plan as a SaaS product, submit a product load form through Amazon Web Services Marketplace. The product must contain a dimension named apigateway of the requests type. This dimension defines the price-per-request and is used by API Gateway to meter requests to your APIs.

Create the metering role

Create an IAM role named ApiGatewayMarketplaceMeteringRole with the following execution policy and trust policy. This role allows API Gateway to send usage metrics to Amazon Web Services Marketplace on your behalf.

Execution policy of the metering role

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "aws-marketplace:BatchMeterUsage",
        "aws-marketplace:ResolveCustomer"
      ],
      "Resource": "*",
      "Effect": "Allow"
    }
  ]
}

Trusted relationship policy of the metering role

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "apigateway.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Associate usage plan with Amazon Web Services Marketplace product

When you list a product on Amazon Web Services Marketplace, you receive an Amazon Web Services Marketplace product code. To integrate API Gateway with Amazon Web Services Marketplace, associate your usage plan with the Amazon Web Services Marketplace product code. You enable the association by setting the API Gateway UsagePlan's productCode field to your Amazon Web Services Marketplace product code, using the API Gateway console, the API Gateway REST API, the Amazon CLI for API Gateway, or Amazon SDK for API Gateway. The following code example uses the API Gateway REST API:

PATCH /usageplans/USAGE_PLAN_ID
Host: apigateway.region.amazonaws.com
Authorization: ...

{
    "patchOperations" : [{
        "path" : "/productCode",
        "value" : "MARKETPLACE_PRODUCT_CODE",
        "op" : "replace"
    }]
}

Handle customer subscription to usage plans

The following tasks are handled by your developer portal application.

When a customer subscribes to your product through Amazon Web Services Marketplace, Amazon Web Services Marketplace forwards a POST request to the SaaS subscriptions URL that you registered when listing your product on Amazon Web Services Marketplace. The POST request comes with an x-amzn-marketplace-token parameter containing buyer information. Follow the instructions in SaaS customer onboarding to handle this redirect in your developer portal application.

Responding to a customer's subscribing request, Amazon Web Services Marketplace sends a subscribe-success notification to an Amazon SNS topic that you can subscribe to. (See SaaS customer onboarding). To accept the customer subscription request, you handle the subscribe-success notification by creating or retrieving an API Gateway API key for the customer, associating the customer's Amazon Web Services Marketplace-provisioned customerId with the API keys, and then adding the API key to your usage plan.

When the customer's subscription request completes, the developer portal application should present the customer with the associated API key and inform the customer that the API key must be included in the x-api-key header in requests to the APIs.

When a customer cancels a subscription to a usage plan, Amazon Web Services Marketplace sends an unsubscribe-success notification to the SNS topic. To complete the process of unsubscribing the customer, you handle the unsubscribe-success notification by removing the customer's API keys from the usage plan.

Authorize a customer to access a usage plan

To authorize access to your usage plan for a given customer, use the API Gateway API to fetch or create an API key for the customer and add the API key to the usage plan.

The following example shows how to call the API Gateway REST API to create a new API key with a specific Amazon Web Services Marketplace customerId value (MARKETPLACE_CUSTOMER_ID).

POST apikeys HTTP/1.1
Host: apigateway.region.amazonaws.com
Authorization: ...

{
  "name" : "my_api_key",
  "description" : "My API key",
  "enabled" : "false",
  "stageKeys" : [ {
    "restApiId" : "uycll6xg9a",
    "stageName" : "prod"
  } ],
  "customerId" : "MARKETPLACE_CUSTOMER_ID"
}

The following example shows how to get an API key with a specific Amazon Web Services Marketplace customerId value (MARKETPLACE_CUSTOMER_ID).

GET apikeys?customerId=MARKETPLACE_CUSTOMER_ID HTTP/1.1
Host: apigateway.region.amazonaws.com
Authorization: ...

To add an API key to a usage plan, create a UsagePlanKey with the API key for the relevant usage plan. The following example shows how to accomplish this using the API Gateway REST API, where n371pt is the usage plan ID and q5ugs7qjjh is an example API keyId returned from the preceding examples.

POST /usageplans/n371pt/keys HTTP/1.1
Host: apigateway.region.amazonaws.com
Authorization: ...

{
    "keyId": "q5ugs7qjjh",
    "keyType": "API_KEY"
}

Associate a customer with an API key

You must update the ApiKey's customerId field to the Amazon Web Services Marketplace customer ID of the customer. This associates the API key with the Amazon Web Services Marketplace customer, which enables metering and billing for the buyer. The following code example calls the API Gateway REST API to do that.

PATCH /apikeys/q5ugs7qjjh
Host: apigateway.region.amazonaws.com
Authorization: ...
        
{
    "patchOperations" : [{
        "path" : "/customerId",
        "value" : "MARKETPLACE_CUSTOMER_ID",
        "op" : "replace"
    }]
}