Working with your Revenue Attribution IDs

A Revenue Attribution ID is a deal-level identifier that maps your AWS Marketplace product revenue to specific AWS Marketplace Offers and/or AWS Partner Central Opportunities. It builds on top of product-level Partner Revenue Measurement (PRM) implementation: PRM captures total attributed revenue for a Marketplace product, and a Revenue Attribution ID maps that revenue to specific deals according to the monthly cost allocation percentages you specify.

The Revenue Attribution Service exposes APIs to create, retrieve, list, and update Revenue Attribution IDs and to manage their monthly cost allocation entries asynchronously.

What is a Revenue Attribution ID?

A Revenue Attribution ID has two layers:

A Revenue Attribution ID can be used in two ways:

Working with your Revenue Attribution IDs

Partners can manage Revenue Attribution IDs and their monthly cost allocation entries through the Revenue Attribution Service. The lifecycle progresses through two independent flows: the attribution-record flow (create, update, retrieve, list) and the allocations flow (start a batch task, poll for results, retrieve individual entries, list entries for an attribution).

Creating a Revenue Attribution ID

The first step is creating a Revenue Attribution ID using the CreateRevenueAttribution API action. The returned Id and Arn can be used immediately as a resource-tag value or in a user-agent string to attribute AWS consumption.

When creating a Revenue Attribution ID, partners must provide:

Partners can optionally provide:

Best Practice: Provide MarketplaceProduct.ProductIdentifier whenever your deal is anchored to a specific Marketplace listing. This enables AWS to validate that the product is owned by the calling partner account or by a subsidiary account connected via Partner Account Connection (PAC), and surfaces the resolved ProductCode and ProductType (for example, SaaS, AMI, ML) in the response. If the product is not owned by an authorized account, the API returns ValidationException with reason PRODUCT_NOT_FOUND_OR_NOT_OWNED.

The response returns the new Id (format ra-[a-z0-9]{13}), Arn, resolved MarketplaceProduct attributes, and the initial Version number (which starts at 1 and increments on each subsequent update).

Adding monthly cost allocation entries

Once a Revenue Attribution ID is created, partners associate AWS Marketplace Offers and/or ACE Opportunities to it by submitting a batch of monthly cost allocation entries through the StartRevenueAttributionAllocationsTask API action. This is an asynchronous operation that accepts up to 250 allocation changes (CREATE and/or UPDATE) per task.

Each allocation entry specifies:

The total Cost Allocation % across all allocation entries for a given Revenue Attribution ID and the same Billing Month must not exceed 100%. If the total exceeds 100%, the offending entry is rejected during async business validation with a per-record error code.

Synchronous validation: StartRevenueAttributionAllocationsTask performs basic shape validation synchronously (field types, patterns, batch size). If the basic validation passes, the API returns a TaskId with status IN_PROGRESS. Business validation (cap checks, immutability rules, dependency lookups against Marketplace and ACE) runs asynchronously and the per-record results are discovered through GetRevenueAttributionAllocationsTask.

To monitor a submitted task, partners poll GetRevenueAttributionAllocationsTask with the Revenue Attribution Resource Id or ARN. The response progresses from IN_PROGRESS to COMPLETED (regardless of whether individual records succeeded or failed) and returns:

Partners should retrieve task results promptly. After the task completes, the per-record outcomes can be reconciled and any failed entries can be corrected and resubmitted in a new task.

Editing monthly cost allocation entries

Cost allocation entries are managed per billing month with these rules:

After the 7th of the current month, attribution for the prior billing month can no longer be modified. Updates to a current or future month's entry apply from the next monthly billing cycle. Historical attribution for prior months is not retroactively recalculated.

Updates to allocation entries are submitted through the same StartRevenueAttributionAllocationsTask API action with Operation set to UPDATE for each affected entry. The async task pattern handles updates and creations uniformly.

Updating a Revenue Attribution ID

Partners can update the Description of an existing Revenue Attribution ID using the UpdateRevenueAttribution API action. The attribution record itself is otherwise immutable — Name, MarketplaceProduct, and tag-on-create values cannot be changed after creation. To re-tag the resource, use the standard AWS tagging operations on the attribution's ARN.

When updating a Revenue Attribution ID, partners must provide:

Partners can optionally provide:

Optimistic Locking: The Version field ensures updates apply only if the attribution hasn't changed since it was last retrieved. If the submitted Version doesn't match the current resource version, the update is rejected with ConflictException and a message including the submitted and current version numbers. Best practice is to retrieve the latest version with GetRevenueAttribution before each update.

Viewing Revenue Attribution ID details

Partners can retrieve complete information for a single Revenue Attribution ID using the GetRevenueAttribution API action. This returns:

Resource Metadata:

Marketplace Product Attributes (if MarketplaceProduct was set at creation):

Audit Information:

Partners can optionally provide a specific Version in the request to retrieve a historical version of the attribution. Omit Version to return the latest.

To retrieve a specific monthly cost allocation entry, partners use the GetRevenueAttributionAllocation API action with the entry's AllocationId. This returns the Offer ID or Opportunity ID, Billing Month, Cost Allocation %, Customer AWS Account ID, and the entry's status and audit information.

Listing Revenue Attribution IDs

Partners can view all Revenue Attribution IDs in their account using the ListRevenueAttributions API action. This returns a paginated list of attribution summaries with filtering and sorting capabilities.

Partners can filter results by:

Partners can configure result sorting using the Sort parameter:

The response includes a summary for each attribution: Arn, Id, Catalog, Name, resolved MarketplaceProduct attributes, CreatedDate, LastModifiedDate, the latest Version, and TotalRevenueAttributionAssociationCount (the number of active monthly cost allocation entries linked to the attribution).

Use MaxResults (default 25, maximum 100) and NextToken to paginate through large result sets. The response includes a NextToken if additional pages are available.

Listing monthly cost allocation entries

Partners can list the monthly cost allocation entries for a specific Revenue Attribution ID using the ListRevenueAttributionAllocations API action. This returns a paginated list of allocation summaries with filtering capabilities.

Partners can filter results by:

The response includes summary information for each entry: the AllocationId, the associated Offer ID or Opportunity ID, the Customer AWS Account ID, the Billing Month, the Cost Allocation %, the entry's name and status, and audit timestamps.

Dashboard Building: The combination of ListRevenueAttributions and ListRevenueAttributionAllocations is designed to support partner dashboard creation. Partners can build views such as: