As a seller, how do I integrate AWS API Gateway with my AWS Marketplace SaaS listing?

For a SaaS product that is an API running in Amazon API Gateway, API Gateway can automatically report usage to AWS Marketplace. This automated reporting is suited for SaaS products that include usage-based pricing model. For example, you change a per API call price. API Gateway only meters on one-single dimension per product (in other words, one price point per SaaS product listing). This cannot be changed.

Regarding the API Gateway and AWS Marketplace BatchMeterUsage API integration:

For the BatchMeterUsage integration to work properly, please note the following:

1. Your SaaS product MUST either have the pricing model “SaaS Subscription” or “SaaS Contract with Consumption”.
2. Your SaaS product MUST have a single billing dimension called “apigateway”.
3. If you are listing a “SaaS Contract with Consumption” pricing model, this dimension MUST be an “out-of-contract” (or overage) dimension (see pricing page in SaaS product submission tool). Please note that API Gateway is not aware of any “gifted” or “included” units. All usage will be automatically sent to the “apigateway” dimension.
4. Please note that API Gateway cannot report to other dimensions. It only reports to the single “apigateway” dimension. This means that usage on all endpoints enabled will be reported to and billed on that single dimension.
5. Your API Gateway MUST be in the seller account and have proper permission.
6. Your API Gateway MUST first have a Usage Plan setup that is associated with the AWS Marketplace product code. Here is an example using the API Gateway UpdateUsagePlan action with AWS CLI:

   $ aws apigateway update-usage-plan \
     --usage-plan-id "USAGE_PLAN_ID" \
     --patch-operations "op=replace,path=/productCode,value=MARKETPLACE_PRODUCT_CODE"
   

7. When a new user onboards to your SaaS platform, the following steps are the process of providing them access and tracking their usage:
   1. Retrieve their marketplace Customer ID using the ResolveCustomer API action.
   2. Create an API key for the user with their Customer ID in API Gateway. Here is an example using the API Gateway CreateApiKey action with AWS CLI:

      $ aws apigateway create-api-key \
         --name "my_api_key" \
          --description "My API key" \
          --no-enabled \
          --customer-id "MARKETPLACE_CUSTOMER_ID"
      

   3. Add the API key to the Usage Plan associated with your marketplace product. This is NOT automatically done and requires you to implement this logic. Here is an example using the API Gateway CreateUsagePlanKey action with AWS CLI:

      $ aws apigateway create-usage-plan-key \
          --usage-plan-id "n371pt" \
          --key-id "q5ugs7qjjh" \
          --key-type "API_KEY"
      

   4. If one is already created for this customer, you can retrieve it and filter by the Customer ID to display it again to the customer. Here is an example using the API Gateway GetApiKyes action with AWS CLI:

      $ aws apigateway get-api-keys --customer-id "MARKETPLACE_CUSTOMER_ID"
      

8. When your customer calls the API Gateway endpoints, they MUST use their API key or you must have an Authorizer that maps back to their API key.

If you have followed ALL 8 points above, API Gateway should report every hour or so if there are usage.

You can confirm that BatchMeterUsage was called by using AWS CloudTrail in your seller account. Please note that CloudTrail is an opt-in service that stores logs in S3 and there is generally a 15-minute delay for logs to show up.

Note Previously, the AWS API Gateway Developer Portal application took care of the onboarding of AWS Marketplace buyers by automatically creating APIGW Usage Plan, API key, and associating with marketplace product and customer ID. That integration has since been removed. Sellers must create their own landing page and integrate with API Gateway.