# Using the AWS Partner Central Benefits API Using the Benefits API The AWS Partner Central Benefits API streamlines how partners discover, apply for, and manage benefits across all AWS Partner Programs. By centralizing benefit management into a single, intuitive interface, the service creates a transparent meritocracy that rewards partners while simplifying operations. The API provides standard AWS API functionality. Access it by either using API [Actions](https://docs.aws.amazon.com/partner-central/latest/benefits-api/API_Operations.html) or by using an AWS SDK that's tailored to your programming language or platform. For more information, see [Getting Started with AWS](https://aws.amazon.com/getting-started) and [Tools to Build on AWS](https://aws.amazon.com/developer/tools/). ## What is a Benefit? In the AWS Partner Network (APN), a Benefit represents an advantage or capability that a partner may obtain from AWS to support their business growth and customer success. Benefits are designed to reward partners based on their qualifications and contributions while providing tangible value that helps partners scale their AWS practices. Benefits can take many forms, including: + **Financial incentives** - Credits, cash disbursements, and funding programs like Migration Acceleration Program (MAP) or Marketing Development Funds (MDF) + **Access benefits** - Preview access to new services, tools, or specialized resources + **Recognition** - Digital badges, certifications, competency designations, and partner tier status + **Technical resources** - Solution architecture assistance, technical support, and ProServe engagements + **Marketing support** - Co-marketing opportunities, featured partner status, and success story publications ## Discovering Available Benefits Partners begin their benefit journey by discovering what benefits are available to them and understanding eligibility requirements. The Benefits API provides comprehensive discovery capabilities through the Benefit Discovery APIs. ### Listing Available Benefits Partners can view all available benefits using the `ListBenefits` API action. This action retrieves a catalog of benefits with optional filtering capabilities to help partners find relevant opportunities quickly. To efficiently discover benefits, partners can filter by: + **Program** - Filter by specific AWS partner programs such as MAP (Migration Acceleration Program), MDF (Marketing Development Funds), ISV Workload Migration, Innovation Sandbox, Proof of Concept, or Partner Initiative Funding + **Fulfillment Type** - Filter by how benefits are delivered: `CREDITS`, `CASH`, `DISCOUNT`, `ACCESS`, `RECOGNITION`, or `RESOURCE` + **Status** - Filter by benefit status: `ACTIVE` or `DEPRECATED` The `ListBenefits` API returns benefit summaries containing essential information such as benefit ID, name, description, associated programs, and fulfillment types. This summary view allows partners to quickly scan available benefits and identify those most relevant to their business objectives. **Example filtering approach:** Partners focused on financial incentives might filter by fulfillment types `CREDITS` and `CASH` to see funding opportunities. Partners seeking technical enablement might filter by fulfillment type `RESOURCE` or `ACCESS` to find technical support benefits and tool access. ### Viewing Detailed Benefit Information Once a partner identifies a benefit of interest, they can retrieve complete details using the `GetBenefit` API action. This provides comprehensive information including: + **Eligibility criteria** - Detailed requirements that partners must meet to qualify for the benefit + **Benefit request schema** - The specific information and documentation partners need to provide when applying + **Grant details** - What partners will receive upon approval + **Associated programs** - Which AWS partner programs the benefit supports The benefit request schema is particularly important as it defines the structure and required fields for benefit applications. Partners should review this schema carefully before creating a benefit application to ensure they gather all necessary information upfront. **Important** Eligibility determination for each benefit is handled by the client or UI layer. For funding-related benefits, eligibility is typically based on the partner's scorecard performance and program participation. **Topics** + [ ## What is a Benefit? ](#what-is-a-benefit) + [ ## Discovering Available Benefits ](#discovering-available-benefits) + [ # Working with Benefit Applications ](working-with-benefit-applications.md) + [ # Working with Benefit Allocations ](working-with-benefit-allocations.md) # Working with Benefit Applications A Benefit Application models a partner's request for a specific benefit. It captures all information needed to evaluate and process the request according to benefit-specific conditions. The benefit application lifecycle progresses through multiple states from draft creation to final approval or rejection. ## Creating Benefit Applications Partners initiate the benefit request process by creating a benefit application using the `CreateBenefitApplication` API action. At creation, the application enters `PENDING_SUBMISSION` status, allowing partners to prepare complete information before submitting for review. When creating a benefit application, partners must provide: + **Benefit Identifier** - The ID or ARN of the benefit being requested + **Fulfillment Types** - How the partner expects to receive the benefit (`CREDITS`, `CASH`, `DISCOUNT`, `ACCESS`, `RECOGNITION`, or `RESOURCE`) + **Benefit Application Details** - A JSON document containing benefit-specific information as defined by the benefit's request schema + **Client Token** - A unique idempotency token to prevent duplicate submissions Partners can optionally provide: + **Name and Description** - Human-readable identifiers for the application + **Partner Contacts** - Contact information for the person managing this benefit request (maximum 1 contact) + **File Attachments** - Supporting documentation such as project plans, SOWs, proof of cost, or customer satisfaction surveys (maximum 10 files) + **Associated Resources** - Links to related opportunities or existing benefit allocations (maximum 10 resources) + **Tags** - Key-value pairs for resource organization and tracking (maximum 200 tags) The `CreateBenefitApplication` API performs soft validation, checking only basic field types and patterns. Full business logic validation occurs during submission, allowing partners to save incomplete applications and return later to complete them. **Best Practice:** Partners should use the benefit request schema from `GetBenefit` to understand exactly what information is required before creating an application. This reduces the likelihood of submission failures due to missing or invalid data. ## Updating Benefit Applications Partners can modify draft benefit applications using the `UpdateBenefitApplication` API action. This allows partners to refine information, add documentation, or correct errors before submission. When updating a benefit application, partners must provide: + **Identifier** - The ID or ARN of the benefit application to update + **Revision** - The current revision number for optimistic locking + **Benefit Application Details** - The complete, updated JSON document Partners must submit the complete benefit application object, even if only specific fields are changing. The best practice is to first retrieve the latest application details using `GetBenefitApplication`, modify the necessary fields, then submit the full updated payload to `UpdateBenefitApplication`. **Optimistic Locking:** The revision field ensures that updates are applied only if the application hasn't changed since it was last retrieved. If the revision doesn't match the current database value, the update is rejected with a conflict error. This prevents partners from accidentally overwriting changes made by other processes or systems. Updates can only be performed while the application is in `PENDING_SUBMISSION` status. Once submitted, applications enter the review process and can no longer be updated through this API. ## Associating Resources with Benefit Applications Partners can link benefit applications to related resources using the `AssociateBenefitApplicationResource` API action. This creates valuable connections between benefits and the business context in which they're being used. Supported resource types include: + **OPPORTUNITY** - Link the benefit application to a specific customer opportunity in . This is particularly useful for opportunity-specific benefits like MAP funding or POC credits tied to customer engagements. + **BENEFIT\$1ALLOCATION** - Link to existing benefit allocations, enabling partners to chain benefits or demonstrate how previous benefits are being leveraged Resource association can only occur before submission. Once a benefit application is submitted (status changes to `IN_REVIEW`), no further associations are allowed. Partners can associate up to 10 resources with each benefit application. To disassociate a resource, partners use the `DisassociateBenefitApplicationResource` API action. Like association, disassociation can only occur in `PENDING_SUBMISSION` status. **Important** Partners must have appropriate permissions to both access the benefit application and read the specific resource being associated. The API validates these permissions during the association operation. ## Submitting Benefit Applications When a benefit application is complete and ready for AWS review, partners submit it using the `SubmitBenefitApplication` API action. Submission triggers a state transition from `PENDING_SUBMISSION` to `IN_REVIEW` and initiates the benefit-specific approval workflow. Upon submission, the API performs comprehensive validation including: + **Required fields validation** - Ensures all mandatory fields in the benefit application details are present + **Field format validation** - Verifies that field values match expected patterns and data types + **Business rule validation** - Applies benefit-specific business logic and constraints + **Resource validation** - Confirms that all associated resources are valid and accessible + **File validation** - Verifies that all file attachments have completed processing successfully If validation fails, the API returns a ValidationException with detailed error codes and messages indicating which fields require correction. Partners must address these issues using `UpdateBenefitApplication` before attempting submission again. **File Processing Requirement:** Benefit applications cannot be submitted if any attached files are still in `PENDING` status. Partners must wait for file processing to complete (status changes to `SUCCEEDED`) before submitting. If files fail processing (status `FAILED`), partners should upload corrected versions. After successful submission: + The application status changes to `IN_REVIEW` + The benefit owner's team is notified of the new submission + Partners can no longer modify application details through standard update APIs + The application enters a defined approval workflow which may include business approval, technical approval, and finance approval stages Partners can track submission progress by retrieving the application and monitoring the Stage field, which indicates the current approval stage (e.g., "Business Approval", "Tech Approval", "Finance Approval"). ## Managing Submitted Applications Once submitted, partners have limited options for managing benefit applications, but the API provides specific actions for common scenarios. ### Recalling Benefit Applications If a partner discovers an error or needs to make changes after submission, they can recall the application using the `RecallBenefitApplication` API action. Recall transitions the application back to `PENDING_SUBMISSION` status, allowing updates and resubmission. When recalling an application, partners should provide: + **Identifier** - The ID or ARN of the benefit application to recall + **Reason** - An optional explanation for the recall (maximum 1000 characters) The reason field enables better traceability and helps AWS understand common issues that lead to recalls, informing future improvements to the benefit application process. After recall, partners can use `UpdateBenefitApplication` to make necessary changes, then resubmit using `SubmitBenefitApplication` when ready. **Important** Recall is typically only available during early review stages. Applications that have progressed to later approval stages or have been approved may not be eligible for recall. ### Amending Benefit Applications For minor corrections after submission, partners can use the `AmendBenefitApplication` API action to update specific fields without recalling the entire application. This is particularly useful when AWS reviewers request clarifications or corrections during the review process. Amendments use a JSON Patch-style approach where partners specify: + **Path** - A JSONPath expression identifying the field to update (e.g., `$.CreditDisbursementDetails.AwsAccountIdForCredits`) + **Value** - The new value for the field + **Operation** - The operation to perform (currently only `REPLACE` is supported) Partners can submit up to 10 amendments in a single API call. Each amendment must include an updated revision number for optimistic locking. Amendments should be used for minor corrections. For substantial changes, partners should use `RecallBenefitApplication` to return the application to draft status for comprehensive updates. ### Canceling Benefit Applications If a partner no longer needs a benefit or wishes to withdraw their application, they can cancel it using the `CancelBenefitApplication` API action. Cancellation transitions the application to `CANCELED` status, permanently ending the application process. When canceling an application, partners should provide: + **Identifier** - The ID or ARN of the benefit application to cancel + **Reason** - An optional explanation for the cancellation (maximum 1000 characters) Once canceled, applications cannot be reactivated. If the partner later decides they need the benefit, they must create a new benefit application. Common reasons for cancellation include: + Customer opportunity was lost or delayed + Partner capacity constraints changed + Business priorities shifted + Benefit is no longer needed for the intended purpose ## Viewing Benefit Application Details Partners can retrieve complete information about a benefit application using the `GetBenefitApplication` API action. This provides a comprehensive view of the application including: **Application Metadata:** + Unique identifier (ID) and Amazon Resource Name (ARN) + Associated benefit identifier + Application name and description + Current status (`PENDING_SUBMISSION`, `IN_REVIEW`, `ACTION_REQUIRED`, `APPROVED`, `REJECTED`, or `CANCELED`) + Current processing stage **Status Information:** + Status Reason - Human-readable explanation of the current status + Status Reason Codes - Structured codes indicating specific issues or requirements (e.g., "Checklist Incomplete", "Project Plan Missing", "Design Win Missing") **Application Content:** + Complete benefit application details JSON document + Partner contact information + File attachments with processing status + Associated resources (opportunities or allocations) + Resource tags **Audit Information:** + Creation timestamp + Last modification timestamp + Current revision number The status reason codes are particularly valuable when an application is in `ACTION_REQUIRED` status. These codes provide specific, actionable guidance on what partners need to address for the application to proceed. ## Listing Benefit Applications Partners can view all their benefit applications using the `ListBenefitApplications` API action. This returns a paginated list of application summaries with powerful filtering capabilities. Partners can filter applications by: + **Program** - View applications for specific programs (MAP, MDF, Sandbox, POC, etc.) + **Fulfillment Type** - Filter by delivery method (`CREDITS`, `CASH`, `ACCESS`, etc.) + **Benefit Identifier** - View applications for a specific benefit + **Status** - Filter by application status (`PENDING_SUBMISSION`, `IN_REVIEW`, `APPROVED`, `REJECTED`, `CANCELED`) + **Stage** - Filter by approval stage (Business Approval, Tech Approval, Finance Approval) + **Associated Resource ARNs** - Find applications linked to specific opportunities or allocations The list response includes essential summary information such as: + Application ID, ARN, and name + Associated benefit ID + Programs and fulfillment types + Current status and stage + Creation and modification timestamps + Associated resources + Current revision number + Selected fields from benefit application details (as defined by the benefit owner) Partners can configure result sorting using the Sort parameter, with options to sort by creation date, status, program, or benefit identifier in ascending or descending order. **Dashboard Building:** The `ListBenefitApplications` API is designed to support partner dashboard creation. By filtering and sorting applications, partners can build views such as: + Applications requiring action (`ACTION_REQUIRED` status) + Recently submitted applications (sorted by creation date, `IN_REVIEW` status) + Approved applications pending allocation (`APPROVED` status) + Applications by program (filtered by specific programs) # Working with Benefit Allocations A Benefit Allocation represents a benefit that has been granted to a partner. When a benefit application is approved, AWS creates one or more benefit allocations that provide partners with the actual credits, funding, access, or other benefit fulfillment. ## Understanding Benefit Allocations Benefit allocations can represent various types of fulfillment: + **Financial Disbursements (CASH)** - Direct financial payments to partners with disbursement tracking + **AWS Credits (CREDITS)** - Credit codes applicable to AWS accounts with usage tracking + **Consumable Allocations** - Pre-approved funding amounts or wallets with utilization tracking + **Access Grants (ACCESS)** - Access to systems, tools, or resources + **Recognition (RECOGNITION)** - Digital badges, certifications, or status designations + **Resources (RESOURCE)** - Technical support, advisory services, or ProServe engagements Each benefit allocation has a lifecycle tracked through its Status field: + **ACTIVE** - The allocation is available for use + **INACTIVE** - The allocation is temporarily unavailable + **FULFILLED** - The allocation has been completely used or delivered Benefit allocations also include temporal information defining when they become effective (StartsAt) and when they expire (ExpiresAt), enabling partners to understand the timeframes for utilizing benefits. ## Listing Benefit Allocations Partners can view all their benefit allocations using the `ListBenefitAllocations` API action. This returns a paginated list of allocation summaries with comprehensive filtering capabilities. Partners can filter allocations by: + **Benefit Identifier** - View allocations for a specific benefit + **Benefit Application Identifier** - View allocations resulting from a specific application + **Fulfillment Type** - Filter by allocation type (`CREDITS`, `CASH`, `ACCESS`, etc.) + **Status** - Filter by allocation status (`ACTIVE`, `INACTIVE`, `FULFILLED`) The list response includes allocation summaries containing: + Allocation ID, ARN, and name + Associated benefit ID and benefit application ID (if applicable) + Fulfillment type + Current status + Creation timestamp + Start date This list view enables partners to build allocation tracking dashboards and identify: + Active allocations available for immediate use + Allocations approaching expiration + Fulfilled allocations for historical tracking + Total allocation value by program or fulfillment type ## Viewing Detailed Allocation Information Partners can retrieve complete allocation details using the `GetBenefitAllocation` API action. This provides comprehensive information about the allocation including fulfillment-specific details that vary based on the allocation type. **Core Allocation Information:** + Unique identifier (ID) and Amazon Resource Name (ARN) + Allocation name and status + Status reason (explanation of current status) + Associated benefit ID and benefit application ID + Fulfillment type + Creation, update, start, and expiration timestamps **Fulfillment Details (Type-Specific):** The FulfillmentDetail field contains different information structures based on the fulfillment type: ### Cash Disbursement Details (CASH Type) For direct cash payments, the fulfillment details include: + **Disbursed Amount** - The total amount of funding disbursed, including amount value and currency code + **Issuance Details (if applicable)** - Information about purchase orders or issuance events: + Issuance ID - Unique identifier for the disbursement + Issuance Amount - Amount in local currency + Issued At - Timestamp of disbursement This structure supports both single disbursements and pre-approved funding scenarios where multiple issuances may occur against a single allocation. ### Credit Details (CREDITS Type) For AWS credits, the fulfillment details include: + **Allocated Amount** - Total credit amount allocated + **Issued Amount** - Total credit amount issued (may be less than allocated for phased issuance) + **Credit Codes** - Array of individual credit code details: + AWS Account ID - Account where credit is applied + Value - Monetary value of the credit code + AWS Credit Code - The actual credit code string + Status - Credit code status (`ACTIVE`, `INACTIVE`, `FULFILLED`) + Issued At - When the credit code was issued + Expires At - When the credit code expires This detailed credit tracking allows partners to monitor credit utilization across multiple accounts and understand which credits are available, partially used, or fully consumed. ### Consumable Allocation Details (Pre-Approved Amounts/Wallets) For pre-approved funding pools, the fulfillment details include: + **Allocated Amount** - Total amount in the allocation + **Remaining Amount** - Unused amount still available + **Utilized Amount** - Amount already consumed + **Issuance Details (if applicable)** - Purchase order information for the allocation Consumable allocations enable partners to draw down funds as needed for eligible activities, with real-time tracking of remaining balance. ### Access Details (ACCESS Type) For access grants, the fulfillment details include: + **Description** - Detailed explanation of the access being granted and how to utilize it Access allocations might provide access to preview services, specialized tools, or restricted resources. The description field provides instructions on how partners can activate and use the granted access. ## Applying Allocations to New Benefit Applications The ApplicableBenefitIds field in benefit allocations identifies other benefits that can leverage this allocation. This enables benefit chaining where partners can use existing allocations to apply for additional benefits. For example, a partner might: 1. Receive a pre-approved MAP funding allocation 1. Create benefit applications for individual customer migration projects 1. Associate those applications with the pre-approved allocation 1. Draw down funds from the allocation as projects are approved This approach streamlines the benefit application process for partners with pre-approved funding, reducing the review cycle for individual project requests. **Topics** + [ ## What is a Benefit? ](#what-is-a-benefit) + [ ## Discovering Available Benefits ](#discovering-available-benefits) + [ # Working with Benefit Applications ](working-with-benefit-applications.md) + [ # Working with Benefit Allocations ](working-with-benefit-allocations.md)