# AMI product pricing for AWS Marketplace AWS Marketplace has multiple pricing models for Amazon Machine Image (AMI) products. With seller private offers, there are options available for multi-year and custom duration contracts. For more information about multi-year and custom duration contracts, see [Preparing a private offer for your AWS Marketplace product](private-offers-overview.md) and [Private offer installment plans](installment-plans.md). The following sections provide information about pricing models for AMI-based products. **Note** You must be able to provide a W-9 tax form (for US based entities) or a W-8 form (for EU-based entities) as described in [Registering as a seller on AWS Marketplace](seller-account-registering.md). **Topics** + [AMI pricing models](#pricing-models-for-ami-products) + [AWS charges and software charges](#aws-charges-vs-software-charges) + [Custom metering pricing for AMI products with AWS Marketplace Metering Service](custom-metering-pricing-ami-products.md) + [Contract pricing for AMI products on AWS Marketplace](ami-contracts.md) + [Associating licenses with AMI-based products using AWS License Manager](ami-license-manager-integration.md) ## AMI pricing models The following table provides general information about pricing models for AMI-based products. | Pricing model | Description | | --- | --- | | Free | Customers can run as many instances as Amazon Elastic Compute Cloud (Amazon EC2) supports with no additional software charges incurred. Free Trial and Annual pricing can't be combined with Monthly pricing. | | Bring your own license (BYOL) | AWS Marketplace doesn't charge customers for usage of the software, but customers must supply a license key to activate the product. This key is purchased outside of AWS Marketplace. The entitlement and licensing enforcement, in addition to all pricing and billing, are handled by you. | | Paid hourly or hourly-annual | **Hourly** – Software is charged by the hour. Each instance type can be priced differently (but it isn't required to be), and usage is rounded up to the nearest whole hour. **Hourly with Free Trial** – Customers are limited to running exactly one instance of the software without incurring a charge. You define the duration, between 5 and 30 days. The free trial applies to the most expensive instance type that is running, and any concurrent usage outside the 1 instance is billed at the hourly rate. NOTE: This is a different model than the AWS Free Tier for Amazon EC2 usage whereby customers are given 750 hours of free usage each month. **Hourly and Monthly** – Both hourly and monthly charges are applied independently. The monthly fee is charged every month regardless of usage, and the hourly fee is applied based on hourly usage only. **Hourly with Annual** – Customers have the option to purchase a year’s worth of usage upfront for one Amazon EC2 instance of one instance type. You set the pricing for each instance type and can offer net savings over the hourly price. Any customer usage above the number of annual subscriptions purchased is billed at the hourly rate you set for that instance type. **Hourly with Multi-Annual and Custom Duration** – This type of offer is only available through seller private offers. Using seller private offers, you specify a custom contract duration, up to 3 years. You can specify upfront payment, or include a flexible payment schedule. You set the pricing for each instance type. If there is a flexible payment schedule in the offer, you also set the invoice dates, payment amounts, and number of instances for each instance type included in the offer. For an active seller private offer with a flexible payment schedule, after the customer launches the specified number of instances, any additional instances launched are charged at the hourly rate specified in the seller private offer. For more information about multi-year and custom duration contracts, see [Preparing a private offer for your AWS Marketplace product](private-offers-overview.md) and [Private offer installment plans](installment-plans.md). **Hourly with Annual (includes Free Trial)** – This is identical to the Hourly model with an Annual option, except it includes a Free Trial allowing a customer to run one instance of any instance type for free for a set number of days that you determine. Annual subscriptions can be purchased at any time, and they are combined with the Free Trial subscription. **Annual with Hourly** – Same as the Hourly with Annual pricing model. Customers have the option to purchase a year’s worth of usage upfront for one Amazon EC2 instance of one instance type. You set the pricing for each instance type and can offer net savings over the hourly price, but offering savings isn't required. Any customer usage above the number of annual subscriptions purchased is billed at the hourly rate you set for that instance type. **Multi-Annual and Custom Duration with Hourly** – This is only available through [Preparing a private offer for your AWS Marketplace product](private-offers-overview.md). Using seller private offers, you can specify a custom duration contract of up to three years. You can require upfront payment, or you can offer a flexible payment schedule to the customer. You set the pricing for each instance type for the duration of the contract, and the hourly pricing for additional instances launched. If you offer a flexible payment schedule, you also set the invoice dates, payment amounts, and number of instances for each instance type included in the offer. For an active private offer with a flexible payment schedule, after the specified number of instances have been launched, any additional instances the customer launches are charged at the hourly rate specified in the private offer. For more information about multi-year and custom duration contracts, see [Preparing a private offer for your AWS Marketplace product](private-offers-overview.md) and [Private offer installment plans](installment-plans.md). Free Trial and Annual pricing can't be combined with Monthly pricing. | | Paid monthly | **Monthly** – Software is paid for on a fixed monthly basis, regardless of the number of instances the customer runs. Monthly charges are pro-rated at sign-up and upon cancellation. Example: A customer who subscribes for 1 day of the month will be charged for 1/30th of the month. **Monthly with Hourly** – Both Hourly and Monthly charges are applied independently. The monthly fee is charged every month regardless of usage, and the hourly fee is applied based on hourly usage only. Free Trial and Annual pricing can't be combined with Monthly pricing. | | Paid usage pricing | Software is directly charged for the value you provide along with one of four usage categories: users, data, bandwidth, or hosts. You can define up to 24 dimensions for the product. All charges are still incurred hourly by the customer. All usage is calculated monthly and billed monthly using the same mechanism as existing AWS Marketplace software. Usage pricing is also referred to as AWS Marketplace Metering Service. | | Contract pricing model | **AMI with contract pricing** – A Single-AMI product or Single-AMI with AWS CloudFormation stack that the buyer pays an upfront fee for. | ## AWS charges and software charges Amazon Machine Image (AMI)-based product charges fall into two categories: + **Infrastructure Pricing Details** – All AMI-based products incur associated AWS infrastructure charges depending on the services and infrastructure used. These rates and fees are defined and controlled by AWS, and can vary between AWS Regions. For more information, see [Amazon EC2 Pricing](https://aws.amazon.com/ec2/pricing/). + **Software Pricing Details** – For Paid products, the seller defines the charges for using the software. These two product charge categories are displayed separately on the AWS Marketplace detail pages to help buyers understand the potential cost of using the products. ### Free trial for AMI hourly products AMI hourly products are eligible for the optional Free trial program. In a Free trial, a customer can subscribe to the product and use a single instance for up to 31 days without paying software charges on the product. Applicable AWS infrastructure charges still apply. Free trials will automatically convert to a paid subscription upon expiration. Customers will be charged for additional usage above the free units provided. To offer an hourly product free trial, define the duration of the trial period and notify the [AWS Marketplace Seller Operations](https://aws.amazon.com/marketplace/management/contact-us/) team. The trial period can be 5–31 days. When customers subscribe to a Free trial product, they receive a welcome email message that includes the term of the Free trial, a calculated expiration date, and details on unsubscribing. A reminder email message is sent three days before the expiration date. If you offer a Free trial product in AWS Marketplace, you agree to the specific refund policies described under **Refund Policy**. ### Additional resources For more information about AMI product pricing, see the following topics: + [Custom metering pricing for AMI products with AWS Marketplace Metering Service](custom-metering-pricing-ami-products.md) + [Contract pricing for AMI products on AWS Marketplace](ami-contracts.md) For more information bout billing, metering, and licensing integrations for AMI-based products, see the following topics: about AMI product pricing, see the following topics: + [Configuring custom metering for AMI products with AWS Marketplace Metering Service](custom-metering-with-mp-metering-service.md) + [Associating licenses with AMI-based products using AWS License Manager](ami-license-manager-integration.md) # Custom metering pricing for AMI products with AWS Marketplace Metering Service With the AWS Marketplace Metering Service, you can modify your software to send metering records to an endpoint to capture usage. You can select a usage category and define up to 24 dimensions for that one category. These dimensions are metered once per hour, aggregated, and charged against a price plan that you define. As a seller, you must determine which dimension you want to use. After the AMI is published, you will not be able to change it. The following sections provide information about AWS Marketplace Metering Service. **Topics** + [Metering service concepts](#metering-service-concepts) + [Pricing your software](#pricing-your-software) + [Adding your product to AWS Marketplace](#listing-your-product-on-aws-marketplace) + [Modifying your software to use the Metering Service](#modifying-your-software-to-use-the-metering-service) + [Vendor-metered tagging (Optional)](#ami-vendor-metered-tagging) + [Configuring custom metering](#configure-custom-metering) + [Configuring custom metering for AMI products with AWS Marketplace Metering Service](custom-metering-with-mp-metering-service.md) ## Metering service concepts Before you use the AWS Marketplace Metering Service, note the following important service concepts: + **Usage Category** – Any software product priced through the use of the Metering Service is categorized according to one usage category, which determines the appropriate way to charge customers. Usage categories include but aren't limited to: + **Users** – A defined set of permissions associated with a single identifier. This category is appropriate for software in which a customer’s users connect to the software directly (for example, for customer-relationship management or business intelligence reporting). + **Hosts** – Any server, node, instance, endpoint, or other part of a computing system. This category is appropriate for software that monitors or scans many customer-owned instances (for example, performance or security monitoring). + **Data** – Storage or information, measured in MB, GB, or TB. This category is appropriate for software that manages stored data or processes data in batches. + **Bandwidth** – Measured in Mbps or Gbps. This category is appropriate for software that allows customers to specify an amount of bandwidth to provision. + **Unit** – Unit of measurement; see the examples described next. + **Usage Unit** – A software product's specific usage unit corresponds to the selected usage category. This usage unit describes the unit your software will charge on. Examples include: + **NodesHrs** (corresponding to the Hosts category) + **UserHrs** (corresponding to the User category) + **GBStored** (corresponding to the Data category) + **Consumption** – Software products priced through the use of the Metering Service charge for consumption in one of three ways: + Provisioned – The software allows customers to configure a specific amount of resources for use (for example, number of users or a fixed amount of bandwidth). Each hour, customers pay for what they have provisioned. + Concurrent – The software allows any number of distinct hosts or users to connect to the software. Each hour, customers pay based on the number of hosts or users who accessed the software. + Accumulated – The software allows customers to use any amount of data, either processed or stored. Each hour, customers pay for the aggregated amount. + **Pricing** – Software products priced through the use of the Metering Service must specify either a single price or define up to 24 dimensions, each with their own price. Details about the pricing options include: + Single dimension – This is the simplest pricing option. Customers pay a single price per resource unit per hour, regardless of size or volume (for example, \$10.014 per user per hour, or \$10.070 per host per hour). + Multiple dimensions – This pricing option is appropriate when the selected usage category varies along multiple axes. For example, for host monitoring, a different price could be set depending on the size of the host. Or, for user-based pricing, a different price could be set based on the type of user (for example, admin, power user, and read-only user). + **Metering** – All usage is recorded as a metering event, once each hour. Your software must be configured to send the appropriate dimension and usage amount to the AWS Marketplace Metering Service. + Allocations – Optionally, you may distribute the usage into allocations by properties that you track. These allocations are represented as tags to the buyer. The tags allow the buyer to view their costs split into usage by tag. For example, if you charge by the user, and users have a "Department" property, you could create usage allocations with tags that have a key of "Department", and one allocation per value. This approach doesn't change the price, dimensions, or the total usage that you report. However, it allows your customer to view their costs by categories appropriate to your product. ## Pricing your software When pricing your software with the AWS Marketplace Metering Service, you must first decide on a usage category and how it will be consumed. The service supports six distinct pricing scenarios. You must select only one of these for your product: + Provisioned user (per hour) + Concurrent user (per hour) + Provisioned host (per hour) + Concurrent host (per hour) + Provisioned bandwidth (per hour) + Accumulated data (per hour) Next, you must decide how to price the selected usage category: + Single price + Multiple dimensions (up to 24) [Adding your product to AWS Marketplace](#listing-your-product-on-aws-marketplace) describes how to provide a customer-friendly description of your dimension and pricing. ### Example: Provisioned bandwidth with nonlinear pricing Imagine you offer network appliance software. You choose to bill by provisioned bandwidth. For your usage category, select **Bandwidth**. In addition to charging by bandwidth, you want to charge a different price as buyers scale up. You can define multiple dimensions within the bandwidth category. You can define a distinct price for 25 Mbps, 100 Mbps, and 1 Gbps. ### Example: Concurrent hosts with multiple dimensions Imagine you offer software that monitors other Amazon EC2 instances. You choose to bill by the number of hosts that are being monitored. For your usage category, select **Host**. In addition to charging by host, you want to charge for the extra value for monitoring larger hosts. You can use multiple dimensions within the host category. You can define a distinct price for micro, small, medium, large, x-large, 2XL, 4XL, and 8XL instances. Your software is responsible for mapping each particular host to one of your defined dimensions. Your software is responsible for sending a separate metering record for each dimension of your usage category if applicable. ## Adding your product to AWS Marketplace To take advantage of the Metering Service, you must create a new product for AWS Marketplace to list. If your product is already on the AWS Marketplace, you will need to decide whether the new AWS Marketplace Metering Service product will be made available in addition to your current product, or if it will replace your current product as the only version available to new users. If you choose replacement, the existing product will be removed from the AWS Marketplace so that it is no longer available for new buyers. Existing customers will continue to have access to their old product and instances, but they can migrate to the new product at their convenience. The new product must meter usage to the AWS Marketplace Metering Service, as described in [Modifying your software to use the Metering Service](#modifying-your-software-to-use-the-metering-service). After you have your AMI, follow the standard process to share and scan your AMI using the self-service tool. In addition to using the template available on the management portal, fill out the product load form and upload it to start the ingestion process. Use the following definitions to complete the fields of the Product Load Form for the AWS Marketplace Metering Service. On the Product Load Form, these fields are labeled as **Flexible Consumption Pricing (FCP)** to differentiate them from hourly and monthly priced products. + **Title** – If you already have a product on AWS Marketplace and you're adding the same product with the AWS Marketplace Metering Service, include the FCP category and dimension in parentheses to differentiate them (for example, “PRODUCT TITLE (Data)”). + **Pricing Model** –From the dropdown list, choose **Usage**. + **FCP Category** – The category in which customers are charged for paid products with a **Usage** pricing component. From the dropdown list, choose **Users**, **Hosts**, **Data**, or **Bandwidth**. + **FCP Unit** –The unit of measurement on which customers are charged for paid products with a **Usage** pricing component. Options will appear in the dropdown list based on the FCP category you selected. The following table lists the valid units for each category. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/marketplace/latest/userguide/custom-metering-pricing-ami-products.html) + **FCP Dimension Name** – The name used when sending metering records by calling the `MeterUsage` operation. It is visible in billing reports. However, because it isn't external-facing, the name doesn't need to be user-friendly. The name can be no more than 15 characters and can only include alphanumeric and underscore characters. After you set the name and make the product public, you can't change it. Changing the name requires a new AMI. + **FCP Dimension Description** – The customer-facing statement that describes the dimension for the product. The description (can be no more than 70 characters and should be user-friendly. Examples of descriptions include: Administrators per hour and Per Mbps bandwidth provisioned. After the product is published, you can't change this description. + **FCP Rate** – The software charge per unit for this product. This field supports eight decimal places. **Notes:** You don't need to fill out hourly and annual pricing fields. Free trial and annual pricing aren't compatible. Products that use an AMI, and the Clusters, and AWS Resources feature, can't use the AWS Marketplace Metering Service. Price, instance type, or AWS Region change will follow the same process as other AWS Marketplace products. Products with the AWS Marketplace Metering Service can't be converted to other pricing models such as hourly, monthly, or Bring Your Own License (BYOL). AWS Marketplace recommends adding IAM policy information in your usage instructions or document. You can include up to 24 FCP dimensions in total. Once created and published, you can't modify existing dimensions, but you can add new ones (up to the limit of 24). If you have questions, contact the [AWS Marketplace Seller Operations](https://aws.amazon.com/marketplace/management/contact-us/) team. ## Modifying your software to use the Metering Service You will need to modify your software to record customer usage, send hourly usage reports to the Metering Service, and handle new failure modes. The software operates independently of pricing, but the software will need to know about the usage category, how it's consumed, and any dimensions. ### Measuring consumption Your software must determine how much of the selected usage category and which dimensions the customer has consumed. This value will be sent, once each hour, to the Metering Service. In all cases, it's assumed that your software has the ability to measure, record, and read consumption of resources for the purpose of sending it on an hourly basis to the Metering Service. For provisioned consumption, this will typically be read from the software configuration as a sampled value, but might also be a maximum configured value, recorded each hour. For concurrent consumption, this might be either a periodic sample or a maximum value recorded each hour. For accumulated consumption, this will be a value that is accumulated each hour. For pricing on multiple dimensions, multiple values must be measured and sent to the Metering Service, one per dimension. This requires your software to be programmed or configured with the known set of dimensions when you provide the AMI. The set of dimensions can't change after a product is created. For each pricing scenario, the following table describes recommended ways for measuring consumption each hour. | **Scenario ** | **How to measure ** | | --- | --- | | Provisioned user | Current number of provisioned users (sampled). -OR- Maximum number of provisioned users (seen that hour). | | Concurrent user | Current number of concurrent users (sampled). -OR- Maximum number of concurrent users (seen that hour). -OR- Total number of distinct users (seen that hour). | | Provisioned host | Current number of provisioned hosts (sampled). -OR- Maximum number of provisioned hosts (seen that hour). | | Concurrent host | Current number of concurrent hosts (sampled). -OR- Maximum number of concurrent hosts (seen that hour). -OR- Total number of distinct hosts (seen that hour). | | Provisioned bandwidth | Current provisioned bandwidth setting (sampled). -OR- Maximum provisioned bandwidth (seen that hour). | | Accumulated data | Current GB of data stored (sampled). -OR- Maximum GB of data stored (seen that hour). -OR- Total GB of data added or processed that hour. -OR- Total GB of data processed that hour. | ## Vendor-metered tagging (Optional) Vendor-metered tagging helps Independent Software Vendors (ISVs) give the buyer more granular insight into their software usage and can help them perform cost allocation. To tag a buyer's software usage, you need to determine how costs are allocated. First ask your buyers what they want to see in their cost allocation. Then you can split the usage across properties that you track for the buyer’s account. Examples of properties include `Account ID`, `Business Unit`, `Cost Centers`, and other relevant metadata for your product. These properties are exposed to the buyer as tags. Using tags, buyers can view their costs split into usage by the tag values in their AWS Billing Console ([https://console.aws.amazon.com/costmanagement/](https://console.aws.amazon.com/costmanagement/)). Vendor-metered tagging doesn't change the price, dimensions, or the total usage that you report. It allows your customer to view their costs by categories appropriate to your product. In a common use case, a buyer subscribes to your product with one AWS account. The buyer also has numerous users associated with the same product subscription. You can create usage allocations with tags that have a key of `Account ID`, and then allocate usage to each user. In this case, buyers can activate the `Account ID` tag in their Billing and Cost Management console and analyze individual user usage. ### Seller experience Sellers can aggregate the metering records for resources with the same set of tags instead of aggregating usage for all resources. For example, sellers can construct the metering record that includes different buckets of `UsageAllocations`. Each bucket represents `UsageQuantity` for a set of tags, such as `AccountId` and `BusinessUnit`. In the following diagram, **Resource 1** has a unique set of `AccountId` and `BusinessUnit` tags, and appears in the **Metering Record** as a single entry. **Resource 2** and **Resource 3** both have the same `AccountId` tag, `2222`, and the same `BusinessUnit` tag, `Operations`. As a result, they're combined into a single `UsageAllocations` entry in the **Metering Record**. ![\[Diagram showing how vendor metering tags combine usage data. Three resources (Resource 1, 2, and 3) with different AccountIds and BusinessUnits are consolidated into a single Metering Record with UsageAllocations grouped by AccountId and BusinessUnit before being sent to the AWS Marketplace Metering Service.\]](http://docs.aws.amazon.com/marketplace/latest/userguide/images/seller-vendor-meter-tag.png) Sellers can also combine resources without tags into a single `UsageAllocation` with the allocated usage quantity and send it as one of the entries in `UsageAllocations`. Limits include: + Number of tags – 5 + Size of `UsageAllocations` (cardinality) – 2,500 Validations include: + Characters allowed for the tag key and value – a-zA-Z0-9\$1 -=.\$1:\$1/@ + Maximum tags across `UsageAllocation` list – 5 + Two `UsageAllocations` can't have the same tags (that is, the same combination of tag keys and values). If that's the case, they must use the same `UsageAllocation`. + The sum of `AllocatedUsageQuantity` of `UsageAllocation` must equal the `UsageQuantity`, which is the aggregate usage. ### Buyer experience The following table shows an example of the buyer experience after a buyer activates the `AccountId` and `BusinessUnit` vendor tags. In this example, the buyer can see allocated usage in their **Cost Usage Report**. The vendor-metered tags use the prefix `“aws:marketplace:isv”`. Buyers can activate them in the Billing and Cost Management, under **Cost Allocation Tags**, **AWS-generated cost allocation tags**. The first and last rows of the **Cost Usage Report** are relevant to what the Seller sends to the Metering Service (as shown in the [Seller experience](container-metering-meterusage.md#container-vendor-metered-tag-seller) example). **Cost Usage Report (Simplified)** | ProductCode | Buyer | UsageDimension | UsageQuantity | `aws:marketplace:isv:AccountId ` | `aws:marketplace:isv:BusinessUnit` | | --- | --- | --- | --- | --- | --- | | xyz | 111122223333 | Network: per (GB) inspected | 70 | 2222 | Operations | | xyz | 111122223333 | Network: per (GB) inspected | 30 | 3333 | Finance | | xyz | 111122223333 | Network: per (GB) inspected | 20 | 4444 | IT | | xyz | 111122223333 | Network: per (GB) inspected | 20 | 5555 | Marketing | | xyz | 111122223333 | Network: per (GB) inspected | 30 | 1111 | Marketing | For a code example, see [`MeterUsage` with usage allocation tagging (Optional)](custom-metering-with-mp-metering-service.md#ami-meterusage-code-example) ## Configuring custom metering For more information about working with AWS Marketplace Metering Service, see [Configuring custom metering for AMI products with AWS Marketplace Metering Service](custom-metering-with-mp-metering-service.md). # Configuring custom metering for AMI products with AWS Marketplace Metering Service **Note** For AMI-based products with custom metering pricing, your software must call the [MeterUsage API](https://docs.aws.amazon.com/marketplace/latest/APIReference/API_marketplace-metering_MeterUsage.html) using temporary AWS credentials of the IAM role for Amazon Elastic Compute Cloud attached to the Amazon EC2 instance. Using long-term access keys is not supported. The AWS Marketplace Metering Service is a pricing and metering feature that you can use to directly charge for your software by usage category. There are five usage categories: users, data, bandwidth, hosts, or unit. You can use the Metering Service with Amazon Machine Image (AMI)-based, container-based, and software as a service (SaaS)-based products. The following sections provide more information about how to configure custom metering with AWS Marketplace Metering Service. The AWS Marketplace Metering Service enables several new scenarios. For example, if your software monitors hosts, you can charge for each host monitored. You can have different prices based on the host size, and charge for the number of concurrent hosts monitored each hour. Similarly, if your software allows many users across an organization to sign in, you can charge by the number of users. Each hour, the customer is charged for the total number of provisioned users. For more information, see the [https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/Welcome.html](https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/Welcome.html). For more information about integrating AWS Marketplace Metering Service API for AMI-based products with custom metering pricing, see the [List AMI products priced by custom units](https://catalog.workshops.aws/mpseller/en-US/ami/list-ami-custom-units) lab of the *AWS Marketplace seller workshop*. **Topics** + [Requirements](#metering-service-requirements) + [Call AWS Marketplace Metering Service](#call-aws-marketplace-metering-service) + [Failure handling](#important-information-about-failure-handling) + [Limitations](#limitations) + [Code example](#ami-metering-code-example) ## Requirements All AMI-based software that uses the Metering Service must meet the following requirements: + Your software must be launched from AWS Marketplace through an Amazon Machine Image (AMI). + If you have an existing product in AWS Marketplace, you must submit a new AMI and create a new product to enable this feature. + All software must be provisioned with an AWS Identity and Access Management (IAM) role. The end customer must add an IAM role to the Amazon Elastic Compute Cloud (Amazon EC2) instance the user is provisioning with the software. The use of an IAM role is optional when you deploy software through AWS Marketplace. It's required when you deploy AWS Marketplace Metering Service software. + Your software must be able to determine consumption in some way. ## Call AWS Marketplace Metering Service Your software must call the Metering Service hourly and record the consumption value for that hour. When your software starts, it should record the minute-of-the-hour at which it started. This is referred to as the *start-minute*. Every hour on the start-minute, your software must determine the consumption value for that hour and call the Metering Service. For information about how to obtain this value, see [Modifying your software to use the Metering Service](https://docs.aws.amazon.com/marketplace/latest/userguide/custom-metering-pricing-ami-products.html#modifying-your-software-to-use-the-metering-service). To wake up each hour at the start-minute, your software must use one of the following approaches: + A thread within your software. + A daemon process that starts up with the instance or software. + A cron job that is configured during application startup. **Note** Your software must call the AWS Marketplace Metering Service using the IAM role configured on the customer’s instance and specify the consumption dimension and amount. Your software can use the AWS SDK to call the AWS Marketplace Metering Service, similar to the following example implementation: 1. Use the instance profile to create a service client. This requires the role configured for the EC2 instance. The role credentials are refreshed by the SDK automatically. 1. Each hour, read your software configuration and state to determine consumption values for that hour. This might include collecting a value-per-dimension. 1. Call the `meterUsage` method on the SDK client with the following parameters (call additionally for each dimension that has usage): + `timestamp` – Timestamp of the hour being recorded (in UTC). + `productCode` – Product code assigned to the software. + `dimension` – Dimension (or dimensions) assigned to the software. + `quantity` – Consumption value for the hour. + `allocations` – (Optional) You may provide allocations for the usage across properties that you track. These allocations must add up to the total consumption in the record. To the buyer, these display as potential cost allocation tags in their billing tools (such as the AWS Billing and Cost Management console). The buyer must activate the tags in their account in order to track their cost using these tags. In addition, your software must call an in-Region AWS Marketplace Metering Service endpoint. Your product must have a correct Regional endpoint set up, so `us-east-1` sends records to a `us-east-1` endpoint, and `us-west-2` sends records to a `us-west-2` endpoint. Making in-Region calls provides buyers with a more stable experience and prevents situations in which an unrelated Region’s availability could impact software running in another Region. When you send metering records to the service, you must connect to the AWS Marketplace Metering Service in your Region. Use the `getCurrentRegion()` helper method to determine the Region in which the EC2 instance is running, and then pass this Region information to the `MeteringServiceClient` constructor. If you don't specify an AWS Region in the SDK constructor, the default `us-east-1` Region is used. If your application attempts to make cross-Region calls to the service, the calls are rejected. For more information, see [Determining an Application’s Current Region](https://java.awsblog.com/post/Tx3GBOIEN1JJMQ5/Determining-an-Application-s-Current-Region) and [getCurrentRegion()](http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/regions/Regions.html#getCurrentRegion()). ## Failure handling Your product must send metering records to the service, a public internet endpoint, so that usage can be captured and billed. Because it's possible for a customer to modify network settings in a way that prevents your metering records from being delivered, your product should account for this by choosing a failure mode. **Note** Some metering failures may be transient issues in connecting to the AWS Marketplace Metering Service. AWS Marketplace strongly recommends implementing retries for up to 30 minutes, with exponential back off, to avoid short-term outages or network issues. Typically, software can fail open (provide a warning message but maintain full functionality) or fail closed (disable all functionality in the application until a connection has been reestablished). You can choose to fail open, closed, or something specific to your application. We strongly recommend that you refrain from failing closed after less than two hours of metering failures. As an example of failing partially open, you could continue to allow access to the software but not allow the buyer to modify the software settings. Or, a buyer could still access the software but would not be able to create additional users. Your software is responsible for defining and enforcing this failure mode. Your software’s failure mode must be included when your AMI is submitted, and it can't be changed later. ## Limitations Keep these limitations in mind when designing and submitting your Metering Service-enabled software: + **IAM role and internet gateway requirements for your customers** – Your customers must have an internet gateway and must launch your software with an IAM role with specific permissions. For more information, see [AWS Marketplace metering and entitlement API permissions](iam-user-policy-for-aws-marketplace-actions.md). Your software can't connect to the Metering Service if these two conditions aren't met. + **Inability to add new or change usage category to existing Metering Service product** – When customers subscribe to your software product, they're agreeing to terms and conditions. Changing the usage categories in products with the Metering Service requires a new product and a new subscription. + **Inability to change dimensions to existing Metering Service product** – When customers subscribe to your software product, they're agreeing to terms and conditions. Changing the dimensions in products with the Metering Service requires a new product and a new subscription. You *can* add new dimensions to existing products, up to the limit of 24. + **Lack of free trial and annual subscriptions** – Metering Service products don't support free trials and annual subscriptions at launch. + **Multi-instance or cluster-based deployment considerations** – Some software is deployed as part of a multi-instance deployment. When you design your software, consider how and where consumption is measured and where metering records are emitted. ## Code example The following code example is provided to help you integrate your AMI product with the AWS Marketplace APIs required for publishing and maintaining your product. ### `MeterUsage` with usage allocation tagging (Optional) The following code example is relevant for AMI products with consumption pricing models. The Python example sends a metering record with appropriate usage allocation tags to AWS Marketplace to charge your customers for pay-as-you-go fees. ``` # NOTE: Your application will need to aggregate usage for the # customer for the hour and set the quantity as seen below. # AWS Marketplace can only accept records for up to an hour in the past. # # productCode is supplied after the AWS Marketplace Ops team has # published the product to limited # Import AWS Python SDK import boto3 import time usageRecord = [ { "AllocatedUsageQuantity": 2, "Tags": [ { "Key": "BusinessUnit", "Value": "IT" }, { "Key": "AccountId", "Value": "123456789" }, ] }, { "AllocatedUsageQuantity": 1, "Tags": [ { "Key": "BusinessUnit", "Value": "Finance" }, { "Key": "AccountId", "Value": "987654321" }, ] } ] marketplaceClient = boto3.client("meteringmarketplace") response = marketplaceClient.meter_usage( ProductCode="testProduct", Timestamp=int(time.time()), UsageDimension="Dimension1", UsageQuantity=3, DryRun=False, UsageAllocations=usageRecord ) ``` For more information about `MeterUsage`, see [MeterUsage](https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/API_MeterUsage.html) in the *AWS Marketplace Metering Service API Reference*. ### Example response ``` { "MeteringRecordId": "string" } ``` # Contract pricing for AMI products on AWS Marketplace Contract pricing for Amazon Machine Image (AMI)-based products means that the buyer pays an upfront fee for a single AMI product or single AMI with AWS CloudFormation stack. For AMI-based products with contract pricing, AWS Marketplace bills your customers upfront or by the payment schedule that you define, based on the contract between you and your customer. After that point, they're entitled to use those resources. This topic provides more information about contract pricing. To set your pricing, choose one or more contract durations that you offer customers. You can enter different prices for each contract duration. Your options are 1-month, 12-months, 24-month, and 36-month durations. For private offers, you can specify a custom duration in months (up to 60 months). **Note** Free trials are not available for AMI products with contract pricing. Choose the category that best describes your product’s pricing. The pricing category appears to customers on the AWS Marketplace website. You can choose from **Bandwidth** (GB/s, MB/s), **Data** (GB, MB, TB), **Hosts**, **Requests**, **Tiers**, or **Users**. If none of the predefined categories fit your needs, you can choose the more generic **Units** category. The offer allows for up to 24 dimensions to be added to it. Each dimension requires the following data: + **Contracts Category** – For contract products with no consumption-based pricing, you can choose a category which most closely resembles the category of dimension in the contract or choose **Units** if no values resemble the units for the dimension in the contract + **Contracts Unit** – Choose one of the available values for the units that closely matches your dimensions based on the Category selected. + **Contracts Dimension Allow Multiple Purchases** – This field is used to indicate whether an offer is a tiered pricing offer or a non-tiered offer: Tiered offer – Allows the buyer to subscribe to only one of the available dimensions in the offer. Dimensions in a tiered offer don't have the concept of quantities. Signing a contract with a specific dimension essentially indicates that the buyer has chosen the specific feature indicated by that dimension. Non-tiered offer – Allows the customer to procure more than one dimensions as part of the contract and allows them to procure multiple units of each such dimension. Setting a value of *true* for this field indicates that the offer is a non-tiered offer. Setting a value of *false* for this field indicates that the offer is a tiered offer. When using the Product Load Form (PLF) to create the contracts for your AMI product, you must define the following fields for your pricing dimensions: + **Contracts DimensionX API Name** – The name that should appear in the license generated in the buyer’s AWS License Manager account. This name is also used as the value for `Name` in `Entitlement` in the `Checkoutlicense` API call. + **Contracts DimensionX Display Name** – The customer-facing name of the dimension that will be displayed on the product detail and procurement pages of the AWS Marketplace website. Create a name that is be user-friendly. The name's maximum length is 24 characters. After the listing is public, the value of `Name`can't be changed. + **Contracts DimensionX Description** – The customer-facing description of a dimension that provides additional information about the dimension for the product, such as the capabilities that the specific dimension provides. The maximum length for the description is 70 characters. + **Contracts DimensionX Quantity** – This is used to calculate proration in cases of agreement amendments to a product. This value of this field should be set to 1 for all contract offers. It should not be edited. + **Contracts DimensionX **1-Month Rate**** – The contract rate to be charged for one month of entitlements against this dimension. For non-tiered offers, this rate is charged for each unit of the dimension that is procured. This field supports three decimal places. + **Contracts DimensionX **12-Month Rate**** – The contract rate to be charged for 12 months of entitlements against the dimension. For non-tiered offers, this rate is charged for each unit of the dimension that is procured. This field supports three decimal places. + **Contracts DimensionX **24-Month Rate**** – The contract rate to be charged for 24 months of entitlements against the dimension. For non-tiered offers, this rate is charged for each unit of the dimension that is procured. This field supports three decimal places. + **Contracts DimensionX **36-Month Rate**** – The contract rate to be charged for 36 months of entitlements against the dimension. For non-tiered offers, this rate is charged for each unit of the dimension that is procured. This field supports three decimal places. **Example: Data storage application** | | 1-month price | 12-month price | 24-month price | 36-month price | | --- | --- | --- | --- | --- | | Unencrypted data (GB) | \$11.50/GB | \$116.00/GB | \$130.00/GB | \$160.00/GB | | Encrypted data (GB) | \$11.55/GB | \$116.60/GB | \$131.20/GB | \$161.20/GB | **Example: Log monitoring product** | | 1-month price | 12-month price | 24-month price | 36-month price | | --- | --- | --- | --- | --- | | Basic (10 hosts monitored, 5 containers monitored) | \$1100 | \$11000 | \$12000 | \$14000 | | Standard (20 hosts monitored, 10 containers monitored) | \$1200 | \$12000 | \$14000 | \$18000 | | Pro (40 hosts monitored, 20 containers monitored) | \$1400 | \$14000 | \$18000 | \$116,000 | | Additional hosts monitored per hour | \$110 | \$1100 | \$1200 | \$1400 | | Additional containers monitored per hour | \$110 | \$1100 | \$1200 | \$1400 | **Note** The prices can be for the following durations: 1 month, 12 months, 24 months, or 36 months. You can choose to offer one or more of these options for your product. The durations must be the same across each dimension. **Example** For example, in a case where you have `ReadOnlyUsers` and `AdminUsers` dimensions, if you offer a yearly price for ReadOnlyUsers, you must offer a yearly price for `AdminUsers`, too. ## Automatic renewals When customers purchase your product through AWS Marketplace using AMI contracts, they can agree to automatically renew the contract terms. Customers continue to pay for the entitlements every month or for 1, 2, or 3 years. Customers can modify their renewal settings at any time. For more information, see [Modifying an existing contract](https://docs.aws.amazon.com/marketplace/latest/buyerguide/buyer-ami-contracts.html#modify-existing-contract) in the *AWS Marketplace Buyer Guide*. # Associating licenses with AMI-based products using AWS License Manager For Amazon Machine Image (AMI)-based products with contract pricing, you can use AWS License Manager to associate licenses with your product. AWS License Manager is a license management tool that enables your application to track and update licenses (also known as entitlements) that have been purchased by a customer. After the integration is complete, you can publish your product listing on AWS Marketplace. The following sections provide more information about using AWS License Manager to associate licenses with your AMI-based product. For more information about AWS License Manager, see the [AWS License Manager User Guide](https://docs.aws.amazon.com/license-manager/latest/userguide/license-manager.html) and the [AWS License Manager](https://docs.aws.amazon.com/cli/latest/reference/license-manager/index.html) section of the *AWS CLI Command Reference*. For more information about integrating AWS License Manager with AMI-based products with contract pricing, see the [List AMI products priced by upfront payment](https://catalog.workshops.aws/mpseller/en-US/ami/list-ami-upfront-payment) lab of the *AWS Marketplace seller workshop*. **Note** Customers can't launch new instances of the AMI after the contract expiry period. However, during the contract duration, they can launch any number of instances. These licenses are not node-locked or tied to particular instances. **Private Offer Creation**– Sellers can generate private offers for the products using the Private offer creation tool in the AWS Marketplace Management Portal. **Reporting** – You can set up data feeds by setting up an Amazon S3 bucket in the **Report** section in the AWS Marketplace Management Portal. For more information, see [Seller reports, data feeds, and dashboards in AWS Marketplace](reports-and-data-feed.md). **Topics** + [License models](#license-models) + [Integration workflow](#LM-workflow) + [License Manager integration prerequisites](#LM-prereqs) + [Integrating an AMI-based product with AWS License Manager](#integrate-with-LM) + [License renewals and upgrades](#lic-renew-upgrade) ## License models AWS Marketplace integration with AWS License Manager supports two license models: + [Configurable license model](#config-lic-model) + [Tiered license model](#tiered-lic-model) ### Configurable license model The configurable license model (also known as the quantifiable license model) entitles a buyer to a specific quantity of resources after a buyer has procured a license. You set a pricing dimension and a per unit price. Then, buyer can choose the quantity of the resources that they want to purchase. **Example of pricing dimension and per unit price** You can set a pricing dimension (such as data backup) and per unit price (such as \$130/unit) The buyer can choose to purchase 5, 10, or 20 units. Your product tracks and meters usage to measure the quantity of resources consumed. With the configuration model, the entitlements are counted in one of two ways: + [Drawdown licenses](#drawndown-lic) + [Floating licenses](#floating-lic) #### Drawdown licenses The license is drawn from the pool of allowed amount of licenses upon use. That entitlement is checked out permanently and can't be returned to the license pool. **Example of processing a limited amount of data** A user is entitled to process 500 GB of data. As they continue to process data, the quantity is drawn from the pool of 500 GB until all 500 GB licenses are consumed. For drawdown licenses, you can use the `CheckoutLicense` API operation to check out license units that are consumed. **Example of backup to Amazon S3 for a number of units/year** You have a storage product that allows backup to Amazon Simple Storage Service for up to 1024 units for data for one year. Your application can be launched by using multiple Amazon EC2 instances. Your application has a mechanism to track and aggregate data. Your software calls the `CheckoutLicense` API operation with the Product ID upon every backup or at fixed intervals to update the consumed quantities. In this example, your software calls `CheckoutLicense` to check out 10 units of data. When the total capacity reaches the backup limit that the customer has purchased, the API call fails. **Request** ``` linux-machine ~]$ aws license-manager checkout-license\ --product-sku "2205b290-19e6-4c76-9eea-377d6bf7la47" \ --checkout-type "PERPETUAL" \ --key-fingerprint "aws:294406891311:AWS/Marketplace:issuer-fingerprint" \ --entitlements "Name=DataConsumption, Value=l0, Unit=Count" \ --client-token "AKIAIOSFODNN7EXAMPLE" ``` **Response** ``` { "CheckoutType": "PERPETUAL", "EntitlementsAllowed": [ { "Name": "DataConsumption", "Count": 10, "Units": "Count", "Value": "Enabled" } }, "Expiration": "2021-04-22Tl9:02: 36", "IssuedAt": "2021-04-22Tl8:02:36", "LicenseArn": "arn:aws:license-manager::294406891311:license:l-16bf01b...", "LicenseConsumptionToken": "AKIAIOSFODNN7EXAMPLE" } ``` #### Floating licenses The license is returned to the pool of the allowed amount of licenses after use. **Example of number of users from a fixed upper limit** A user is entitled to 500 simultaneous users on the application. As users log in and log out, the users are drawn and returned to the pool of 500 users. However, the application can't draw more than 500 users from the pool because 500 simultaneous users is the fixed upper limit. For floating licenses, you can use the `CheckInLicense` API operation to return the license units to the entitlement pool. **Example of number of concurrent users for one year** Your product is priced based on number of concurrent users. The customer purchases a license for 10 users for one year. The customer launches the software by providing AWS Identity and Access Management (IAM) permissions. When a user logs in, your application calls the `CheckoutLicense` API operation to reduce the quantity by 1. When the user logs out, the application returns that license to the pool by calling the `CheckInLicense` API operation. If you don't call `CheckInLicense`, the license unit will be automatically checked in after 1 hour. **Note** In the following Request, the `key-fingerprint` isn't a placeholder value but the actual value of the fingerprint with which all licenses will be published. **Request** ``` linux-machine ~]$ aws license-manager checkout-license\ --product-sku "2205b290-19e6-4c76-9eea-377d6bf7la47" \ --checkout-type "PROVISIONAL" \ --key-fingerprint "aws:294406891311:AWS/Marketplace:issuer-fingerprint" \ --entitlements "Name=ReadOnlyUSers, Value=l0, Unit=Count" \ --client-token "AKIAIOSFODNN7EXAMPLE" ``` **Response** ``` { "CheckoutType": "PROVISIONAL", "EntitlementsAllowed": [ { "Name": "ReadOnlyUsers", "Count": 10, "Units": "Count", "Value": "Enabled" } }, "Expiration": "2021-04-22Tl9:02: 36", "IssuedAt": "2021-04-22Tl8:02:36", "LicenseArn": "arn:aws:license-manager::294406891311:license:l-16bf01b...", "LicenseConsumptionToken": "AKIAIOSFODNN7EXAMPLE" } ``` ### Tiered license model The tiered license model entitles a buyer to a specific level, or tier, of application features after a buyer has procured a license. You create tiers for your product, such as Basic, Intermediate, and Premium. The buyer then selects one of the predefined tiers. The application doesn't need to track or meter usage of the application. With the tiered license model, the entitlements aren't counted but instead signify a tier of service that was procured by the customer. If you want to offer bundled features together, we recommend using the tiered license model. **Example of Basic, Intermediate, and Premium tiers** A customer can sign a contract for one of three possible tiers of the software: Basic, Intermediate, or Premium. Each of these tiers has its own pricing. Your software can identify the tier that the customer has signed up for by invoking the `CheckoutLicense` API operation and specifying all possible tiers in the request. The response of the request contains the entitlement corresponding to the tier the customer has procured. Based on this information, the software can provision the appropriate customer experience. #### Request ``` linux-machine ~]$ aws license-manager checkout-license\ --product-sku "2205b290-19e6-4c76-9eea-377d6bf7la47" \ --checkout-type "PROVISIONAL" \ --key-fingerprint "aws:294406891311:AWS/Marketplace:issuer-fingerprint" \ --entitlements "Name=BasicTier, Unit=None" "Name=IntermediateTier, Unit=None" \ "Name=PremiumTier, Unit=None" ``` #### Response ``` { "CheckoutType": "PROVISIONAL", "EntitlementsAllowed": [ { "Name": "IntermediateTier", "Units": "None" } }, "Expiration": "2021-04-22Tl9:02:36", "IssuedAt": "2021-04-22Tl8:02:36", "LicenseArn": "arn:aws:license-manager::294406891311:license:l-16bf01b...", "LicenseConsumptionToken": "AKIAIOSFODNN7EXAMPLE" } ``` ## Integration workflow The following steps show the workflow for integrating your AMI product with AWS License Manager: 1. Seller creates a product with AWS License Manager integration. 1. Seller lists the product on AWS Marketplace. 1. Buyer finds the product on AWS Marketplace and purchases it. 1. A license is sent to the buyer in their AWS account. 1. Buyer uses the software by launching the Amazon Elastic Compute Cloud (Amazon EC2) instance, Amazon Elastic Container Service (Amazon ECS) task, or Amazon Elastic Kubernetes Service (Amazon EKS) pod software, The customer deploys by using an IAM role. 1. Software reads the license in the buyer's AWS License Manager account, discovers the entitlements purchased, and provisions the features accordingly. **Note** License Manager doesn't do any tracking or updates; this is done by the seller’s application. ## License Manager integration prerequisites Before publishing the product, you must do the following: 1. Create a new AMI product in the AWS Marketplace Management Portal, and make a note of its product code. 1. Fill out the Product Load Form (PLF) with the necessary price information, and return it to us for processing. 1. Use an IAM role for the task or pod running your application with the IAM permissions necessary to call `CheckoutLicense`, `ExtendLicenseConsumption`, and `CheckInLicense`. The required IAM permissions are detailed in the following IAM policy. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Sid":"VisualEditorO", "Effect":"Allow", "Action":[ "license-manager:CheckoutLicense", "license-manager:GetLicense", "license-manager:CheckInLicense", "license-manager:ExtendLicenseConsumption", "license-manager:ListReceivedLicenses" ], "Resource":"*" } ] } ``` ------ 1. Make a test call to the `RegisterUsage` API operation with a record for all of the pricing dimensions you define. ## Integrating an AMI-based product with AWS License Manager You can integrate your AMI-based product with License Manager by using the [AWS License Manager](https://docs.aws.amazon.com/license-manager/latest/APIReference/Welcome.html) API. Launch the Amazon EC2 instances by using AWS Marketplace AMI-based products. **Note** Make sure that you have completed the [License Manager integration prerequisites](#LM-prereqs) before you perform the following procedure. **To integrate your AMI-based product with License Manager** 1. Complete the procedure in [Creating a test license in License Manager](#creating-test-license). You must create a test license in License Manager for testing your integration. 1. Run the [GetLicense](https://docs.aws.amazon.com/license-manager/latest/APIReference/API_GetLicense.html) API operation using the license Amazon Resource Name (ARN) that you obtained in step 1. Note the value of the `KeyFingerprint` attribute of the `GetLicense` response for later use. 1. Download and include the latest public AWS SDK in your application. 1. To verify that the buyer is entitled to use a license for your application, run the [CheckoutLicense](https://docs.aws.amazon.com/license-manager/latest/APIReference/API_CheckoutLicense.html) API operation. Use the entitlements details and the key fingerprint of the test license that you obtained in step 1. If there are no entitlements found for the license, or the entitlement maximum count is exceeded, the `CheckoutLicense` API operation returns `NoEntitlementsAllowedException`. If the entitlements are valid, or available to use, the `CheckoutLicense` operation returns a successful response with the requested entitlements and their values. 1. (Required for floating entitlements only) Run the [CheckinLicense](https://docs.aws.amazon.com/license-manager/latest/APIReference/API_CheckInLicense.html) API operation using the `LicenseConsumptionToken` that was received in the `CheckoutLicense` response. This action releases previously checked-out entitlements back into the pool of available entitlements. 1. After you successfully verify the License Manager integration with the test license that you created in step 1, update the key fingerprint in your code to `aws:294406891311:AWS/Marketplace:issuer-fingerprint`. Now, you're ready to work with licenses issued by AWS Marketplace. Follow the release process of building the application to an AMI product and then submit the product to AWS Marketplace following the product publishing process. ### Creating a test license in License Manager You use version 2 of the AWS Command Line Interface (AWS CLI) to create a test license in AWS License Manager. This test license is only used for verifying and testing the AWS License Manager integration. After the testing is completed, you can delete the test license. The actual license is generated by AWS Marketplace with a different key fingerprint. AWS Marketplace supports two types of entitlements in AWS License Manager. However, only one type can be enabled for a product. When you create a license, including a test license, you must specify one of the following types of entitlements: **Tiered entitlements ** – The tiered license model entitles the customer to certain application features. Customers can't define the quantity of units they want to purchase. However, they can select a single predefined package or tier. Customers can modify the contract later to subscribe to another tier. **Configurable entitlements ** – The configurable license model grants entitlements to a certain quantity of resources when the customer procures a license. The customer chooses the quantity of units they want to purchase during the subscription process and will be billed based on the unit price. Customers can also subscribe to multiple dimensions. The required parameters for use in the `CheckoutLicense` API operation are as follows: + `CheckoutType` – The valid values are `Perpetual` or `Provisional`: + `Perpetual` – Used when the quantity of entitlements checked out will be exhausted from the pool. Example: Buyer is entitled to process 500 GB of data. As they continue to process data, the quantity is drawn down and exhausted from the pool of 500 GB. Gets the status of a purchased license on whether the license is expired or about to be expired to send a notification to the customer. + `Provisional` – Used for floating license entitlements where entitlements are checked out of the pool and returned back after use. Example: User is entitled to 500 simultaneous users in the application. As users log in and log out, the users are drawn and returned to the pool of 500 users. For more information about floating license entitlements, see [Seller issued licenses in AWS License Manager.](https://docs.aws.amazon.com/license-manager/latest/userguide/seller-issued-licenses.html) + `ClientToken` – Unique, case-sensitive identifier to ensure the exact result occurs and is the same no matter how many times attempted. We recommend that you use a random universally unique identifier (UUID) for each request. + `Entitlements` – List of entitlements to be checked out. + For tiered entitlements, provide `Name` and `Unit` properties as follows: `{` `"Name": "",` `"Unit": "None"` `}` + For configurable entitlements, provide `Name`, `Unit`, and `Value`properties as follows: `{` `"Name": "",` `"Unit": "",` `"Value": {` \$1 + `KeyFingerprint` – Use this key fingerprint to verify that the license is issued by AWS Marketplace. The key fingerprint for licenses issued by AWS Marketplace is as follows: `aws:294406891311:AWS/Marketplace:issuer-fingerprint` + `Product SKU` – Product ID with a Globally Unique Identifier (GUID) format that is associated with an AWS Marketplace product. **Example of a configurable entitlement** The following is an example of a request that uses the `CheckoutLicense` API operation to check out a configurable entitlement named `PowerUsers`. ``` aws license-manager checkout-license \ product-sku "2205b290-19e6-4c76-9eea-377d6bf71a47" \ checkout-type "PROVISIONAL" \ client-token "79464194dca9429698cc774587a603a1" \"Statement":[ entitlements "Name=PowerUsers,Value=1,Unit=Count" \ key-fingerprint "aws:294406891311:AWS/Marketplace:issuer-fingerprint" ``` **Example of a tiered entitlement** The following is an example of a request that uses the `CheckoutLicense` API operation to check out a feature entitlement named `EnterpriseEdition`. ``` aws license-manager checkout-license \ --product-sku "2205b290-19e6-4c76-9eea-377d6bf71a47" \ --checkout-type "PROVISIONAL" \ --client-token "79464194dca9429698cc774587a603a1" \ --entitlements "Name=EnterpriseEdition,Unit=None" \ --key-fingerprint "aws:294406891311:AWS/Marketplace:issuer-fingerprint" ``` **To create a test license for your AMI-based product** 1. From your local environment with AWS CLI v2 installed, run the following script. The script creates the test license and configures the appropriate product details. **Note** Use a different AWS account than the test AWS account in which you are deploying and testing your software. Licenses can't be created, granted to, and checked out in the same AWS account. ``` #!/bin/bash # Replace with intended product ID on AWS Marketplace PRODUCT_ID= # Replace with license recipient's AWS Account ID BENEFICIARY_ACCOUNT_ID= # Replace with your product's name PRODUCT_NAME="Test Product" # Replace with your seller name on AWS Marketplace SELLER_OF_RECORD="Test Seller" # Replace with intended license name LICENSE_NAME="AWSMP Test License" # Replace the following with desired contract dimensions # More info here: https://docs.aws.amazon.com/license-manager/latest/APIReference/API_Entitlement.html # Example "configurable entitlement" ENTITLEMENTS='[ { "Name": "ReadOnly", "MaxCount": 5, "Overage": false, "Unit": "Count", "AllowCheckIn": true } ]' # Example "tiered entitlement" # ENTITLEMENTS='[ # { # "Name": "EnterpriseUsage", # "Value": "Enabled", # "Unit": "None" # } # ]' # Format "yyyy-mm-ddTHH:mm:ss.SSSZ" # This creates a validity period of 10 days starting the current day # Can be updated to desired dates VALIDITY_START=$(date +%Y-%m-%dT%H:%M:%S.%SZ) VALIDITY_END=$(date --date="+10 days" +%Y-%m-%dT%H:%M:%S.%SZ) # Configuration for consumption of the license as set on Marketplace products CONSUMPTION_CONFIG='{ "RenewType": "None", "ProvisionalConfiguration": { "MaxTimeToLiveInMinutes": 60 } }' # License's home Region HOME_REGION=us-east-1 # License issuer's name ISSUER=Self # Run AWS CLI command to create a license aws license-manager create-license \ --license-name "${LICENSE_NAME}" \ --product-name "${PRODUCT_NAME}" \ --product-sku "${PRODUCT_ID}" \ --issuer Name="${ISSUER}" \ --beneficiary "${BENEFICIARY_ACCOUNT_ID}" \ --validity 'Begin="'"${VALIDITY_START}"'",End="'"${VALIDITY_END}"'"' \ --entitlements "${ENTITLEMENTS}" \ --home-region "${HOME_REGION}" \ --region "${HOME_REGION}" \ --consumption-configuration "${CONSUMPTION_CONFIG}" \ --client-token $(uuidgen) ``` 1. Grant the license using the AWS License Manager console. For more information, see [distribute an entitlement](https://docs.aws.amazon.com/license-manager/latest/userguide/granted-licenses.html#distribute-entitlement.) in the *License Manager User Guide*. 1. Sign in to the AWS account that acts as a buyer account where you will deploy and test your software. This must be a different AWS account from the AWS account that created and granted the license. 1. Go to the AWS License Manager console to accept and activate the granted licenses. For more information, see [manage your granted licenses](https://docs.aws.amazon.com/license-manager/latest/userguide/granted-licenses.html#manage-granted-licenses) in the *License Manager User Guide*. 1. Run the following command in your environment. ``` # The following example uses a key fingerprint that should match the test license you created. # When checking out an actual AWS Marketplace created license, use the following fingerprint: # aws:294406891311:AWS/Marketplace:issuer-fingerprint aws license-manager checkout-license \ --product-sku \ --checkout-type PROVISIONAL \ --key-fingerprint "aws::Self:issuer-fingerprint" \ --entitlements "Name=ReadOnly,Value=1,Unit=Count" \ --client-token $(uuidgen) ``` The previous command uses `PROVISIONAL` as the value for the `CheckoutType` parameter. If the entitlement uses a drawdown license, use `PERPETUAL` for the value. ### License Manager API calls To manage the licenses stored in the customer's License Manager account, your software can use the following API calls: + `GetLicense` – Gets the status of a purchased license on whether the license is expired or about to be expired to send a notification to the customer. + `CheckoutLicense` – Discovers licenses that the user has purchased. You can also use it to update the license quantity when the user has consumed some quantity of licenses. With `CheckoutLicense`, you can keep checking out the quantities of the licenses used by the customer. When the customer exhausts all the licenses, this call returns an error. For information about the suggested cadence to run `CheckoutLicense`, see [License renewals and upgrades](#lic-renew-upgrade). + `ExtendLicenseConsumption` – In case of floating dimensions, when the software check outs a license, it will return the license to the pool automatically after 60 minutes. If you want to extend the time the license remains checked out, your software can call `ExtendLicenseConsumption` to extend the license for another 60 minutes. + `CheckInLicense` – In case of floating dimensions, when you want to return the license to the entitlement pool, use `CheckInLicense`. + `ListReceivedLicenses` – Lists licenses purchased by the buyer. ## License renewals and upgrades Customers can renew or upgrade their licenses on the AWS Marketplace Management Portal. After they make an additional purchase, AWS Marketplace generates a new version of the license that reflects the new entitlements. Your software reads the new entitlements using the same API calls. You don't have to do anything different in terms of License Manager Integration to handle renewals and upgrades. Due to license renewals, upgrades, cancellations, and so on, we recommend that your product performs the `CheckoutLicense` API call at a regular cadence while the product is in use. By using the `CheckoutLicense` API operation at a regular cadence, the product can detect changes in entitlements such as upgrades and expiry. We recommend that you perform the `CheckoutLicense` API call every 15 minutes.