The AWS Marketplace API Reference was restructured. For more information about the supported API operations, see the AWS Marketplace API Reference.

Work with the Agreement API as a buyer

An agreement is a document that binds two parties, including the proposer and the acceptor (commonly, the buyer) and defines the terms and conditions applicable between them.

Buyer creates an AgreementRequest, which generates a quote. This quote includes all relevant information, such as the estimated charges that will be incurred over the lifetime of the agreement, which is critical for the buyer's purchase decision. If the buyer is satisfied with the quote, they can accept the AgreementRequest before it expires. The Agreement is created upon acceptance of the AgreementRequest. During this process, the buyer admin or buyer persona can associate purchase order to charges. Finally, based on the terms and conditions of the active agreement, the buyer is invoiced and granted a License to use the product.

Prerequisites: Discover products and offers

Before creating an agreement, use the AWS Marketplace Discovery API to discover the product and obtain the agreementProposalId, pricingModel, and term details needed to construct a CreateAgreementRequest.

For detailed information about discovering products and pricing, see Discover products and pricing.

An acceptor can perform the following tasks using this API:

Generate a quote

Use CreateAgreementRequest to generate a quote. You must provide:

response = client.create_agreement_request(
    agreementProposalIdentifier='at-edhtjnbilupjv3xqbphtom77y',
    intent='NEW',
    requestedTerms=[
        {'id': 'term-legal-abc123'},
        {'id': 'term-validity-def456'},
        {
            'id': 'term-configurable-pricing-789',
            'configuration': {
                'configurableUpfrontPricingTermConfiguration': {
                    'selectorValue': 'P12M',
                    'dimensions': [
                        {'dimensionKey': 'Users', 'dimensionValue': 50}
                    ]
                }
            }
        },
        {
            'id': 'term-renewal-012',
            'configuration': {
                'renewalTermConfiguration': {'enableAutoRenew': True}
            }
        }
    ]
)

print(f"Agreement Request ID: {response['agreementRequestId']}")
for charge in response['chargeSummary']['expectedCharges']:
    print(f"  Charge ID: {charge['id']}, Amount: ${charge['amount']}")

Constructing requestedTerms

To construct requestedTerms, you need to determine two things:

Required terms by pricing model

The pricingModel.PricingModel field in the GetOffer response determines which terms must be included in your CreateAgreementRequest.

The following terms must be included in every agreement when present in the offer: LegalTerm, SupportTerm, ValidityTerm, and RenewalTerm.

CONTRACT

All terms returned by GetOfferTerms are required in a single CreateAgreementRequest.

USAGE

Agreement creation depends on the terms present in the offer:

BYOL

Accept ByolPricingTerm along with the mandatory terms.

Term configurations

Most terms require only the id from GetOfferTerms. The following term types require a buyer-supplied configuration in addition to the id:

ConfigurableUpfrontPricingTermConfiguration

Use the example below to locate the values needed for ConfigurableUpfrontPricingTermConfiguration.

Example GetOfferTerms response:

{
  "offerTerms": [
    {
      "configurableUpfrontPricingTerm": {
        "id": "term-34dfb665ebd38eb2d0269a4af454c4f33cd90292ecc7b0f71058175594f67394",
        "currencyCode": "USD",
        "rateCards": [
          {
            "constraints": {
              "multipleDimensionSelection": "Allowed",
              "quantityConfiguration": "Allowed"
            },
            "selector": {
              "type": "Duration",
              "value": "P1M"
            },
            "rateCard": [
              {
                "dimensionKey": "BasicService",
                "displayName": "Basic Service",
                "price": "0",
                "unit": "Units"
              },
              {
                "dimensionKey": "PremiumService",
                "displayName": "Premium Service",
                "price": "0",
                "unit": "Units"
              }
            ]
          }
        ],
        "type": "ConfigurableUpfrontPricingTerm"
      }
    }
  ]
}

Example RequestedTerm payload for ConfigurableUpfrontPricingTerm:

{
  "id": "term-43ab7a2445f89dfcb7e1a6a81c92fe08c124125ffad126bea5e5b7915c065166",
  "configuration": {
    "configurableUpfrontPricingTermConfiguration": {
      "selectorValue": "P12M",
      "dimensions": [
        {
          "dimensionKey": "AdminUsers",
          "dimensionValue": 5
        },
        {
          "dimensionKey": "ReadOnlyUsers",
          "dimensionValue": 10
        }
      ]
    }
  }
}

RenewalTermConfiguration

Example RequestedTerm payload for RenewalTerm:

{
  "id": "term-ffcc0100ce0c5468426dc07d0b05cff09ab8447640108d9c95ce1591f0949738",
  "configuration": {
    "renewalTermConfiguration": {
      "enableAutoRenew": false
    }
  }
}

VariablePaymentTermConfiguration

Example RequestedTerm payload for VariablePaymentTerm:

{
  "id": "term-9ab34376c51cd5b4dc995aa0f410b657d58bd577b3f09b34d38afb6964aaaf12",
  "configuration": {
    "variablePaymentTermConfiguration": {
      "paymentRequestApprovalStrategy": "AUTO_APPROVE_ON_EXPIRATION",
      "expirationDuration": "P10D"
    }
  }
}

Accept an offer

First, generate a quote as described in Generate a quote. Then, use AcceptAgreementRequest to accept the quote and create the agreement. You must call AcceptAgreementRequest before the agreement request expires. You can optionally associate a purchase order number during acceptance.

# Use chargeId from CreateAgreementRequest response
response = client.accept_agreement_request(
    agreementRequestId='agrq-abc123',
    purchaseOrders=[
        {
            'chargeId': 'charge-xyz',  # From chargeSummary.expectedCharges[].id
            'purchaseOrderReference': 'PO-2024-001'
        }
    ]
)

print(f"Agreement ID: {response['agreementId']}")

Replace an existing agreement

Construct a CreateAgreementRequest as described in Generate a quote, but set intent to REPLACE and provide sourceAgreementIdentifier with the agreement to replace. Then call AcceptAgreementRequest to complete the replacement.

response = client.create_agreement_request(
    agreementProposalIdentifier='at-edhtjnbilupjv3xqbphtom77y',
    intent='REPLACE',
    sourceAgreementIdentifier='agmt-existing123'
)

print(f"Agreement Request ID: {response['agreementRequestId']}")

Amend an existing agreement

To modify term configuration on an existing agreement, set intent to AMEND and provide sourceAgreementIdentifier. Unlike a new agreement, no agreementProposalIdentifier is needed. Only include the terms whose configuration you want to change. Then call AcceptAgreementRequest to apply the amendment.

response = client.create_agreement_request(
    intent='AMEND',
    sourceAgreementIdentifier='agmt-existing123',
    requestedTerms=[
        {
            'id': 'term-configurable-pricing-789',
            'configuration': {
                'configurableUpfrontPricingTermConfiguration': {
                    'selectorValue': 'P12M',
                    'dimensions': [
                        {'dimensionKey': 'Users', 'dimensionValue': 100}
                    ]
                }
            }
        }
    ]
)

print(f"Agreement Request ID: {response['agreementRequestId']}")

Enable or disable auto-renewal

Use CreateAgreementRequest with the AMEND intent to toggle auto-renewal.

response = client.create_agreement_request(
    intent='AMEND',
    sourceAgreementIdentifier='agmt-existing123',
    requestedTerms=[
        {
            'id': 'term-renewal-456',
            'configuration': {
                'renewalTermConfiguration': {'enableAutoRenew': True}
            }
        }
    ]
)

print(f"Agreement Request ID: {response['agreementRequestId']}")

Cancel an agreement

Use CancelAgreement to cancel a usage agreement. For other agreement types, the buyer must reach out to the seller to initiate cancellation.

client.cancel_agreement(
    agreementId='agmt-abc123'
)

Search agreements

Use SearchAgreements to search across all agreements that you participate in as an acceptor. The search returns a list of agreements with basic agreement information.

response = client.search_agreements(
    catalog='AWSMarketplace',
    filters=[
        {'name': 'PartyType', 'values': ['Acceptor']},
        {'name': 'AgreementType', 'values': ['PurchaseAgreement']},
        {'name': 'Status', 'values': ['ACTIVE']}
    ]
)

for agmt in response['agreementViewSummaries']:
    print(f"  {agmt['agreementId']}: {agmt['status']}")

Describe an agreement

Use DescribeAgreement to view details about an agreement, such as the proposer, acceptor, start date, and end date.

response = client.describe_agreement(
    agreementId='agmt-abc123'
)

print(f"Status: {response['status']}")
print(f"Start: {response['startTime']}")
print(f"End: {response['endTime']}")

Get agreement terms

Use GetAgreementTerms to obtain details about the terms in an agreement that you participate in as an acceptor.

response = client.get_agreement_terms(
    agreementId='agmt-abc123'
)

for term in response['acceptedTerms']:
    print(f"  Term: {term}")

Get agreement entitlements

Use GetAgreementEntitlements to obtain an agreement-level view of the status and details of entitlements tied to your agreement.

response = client.get_agreement_entitlements(
    agreementId='agmt-abc123'
)

for ent in response['agreementEntitlements']:
    print(f"  {ent['resource']}: {ent['status']}")

Get a registration token

Use GetAgreementEntitlements to obtain a registration token. This short-lived token (valid for 30 minutes) is required by acceptors to set up an account with proposers. Currently only applicable for SaaS purchase agreements.

response = client.get_agreement_entitlements(
    agreementId='agmt-abc123'
)

for ent in response['agreementEntitlements']:
    if 'registrationToken' in ent:
        print(f"Registration Token: {ent['registrationToken']}")
        # Token is valid for 30 minutes

List agreement charges

Use ListAgreementCharges to view charges and purchase order details associated with your agreement.

response = client.list_agreement_charges(
    agreementId='agmt-abc123'
)

for charge in response['items']:
    print(f"  {charge['id']} (rev {charge['revision']}): ${charge['amount']}")
    print(f"  PO: {charge.get('purchaseOrderReference', 'N/A')}")

Update purchase orders

Use UpdatePurchaseOrders to add a purchase order number after subscribing to a product. Use the chargeId and chargeRevision from the List agreement charges response. Once a purchase order is associated with a charge, the invoice generated for that charge includes the purchase order number.

client.update_purchase_orders(
    agreementId='agmt-abc123',
    purchaseOrders=[
        {
            'chargeId': 'charge-xyz',
            'chargeRevision': 1,
            'purchaseOrderReference': 'PO-2024-001'
        }
    ]
)

List cancellation requests

Use ListAgreementCancellationRequests to list all cancellation requests for agreements you participate in. You can filter by agreement, status, and other criteria.

response = client.list_agreement_cancellation_requests(
    partyType='Acceptor',
    agreementId='agmt-abc123'
)

for req in response['agreementCancellationRequests']:
    print(f"  {req['agreementCancellationRequestId']}: {req['status']}")

Get cancellation request details

Use GetAgreementCancellationRequest to retrieve detailed information about a specific cancellation request, including status, timestamps, and reason codes.

response = client.get_agreement_cancellation_request(
    agreementId='agmt-abc123',
    agreementCancellationRequestId='acr-abc123'
)

print(f"Status: {response['status']}")
print(f"Reason: {response['reasonCode']}")

Accept a cancellation request

Use AcceptAgreementCancellationRequest to approve a cancellation request initiated by the seller. After approval, the agreement cancellation workflow executes asynchronously. You also need CancelAgreement permission because approving the cancellation request leads to agreement cancellation.

client.accept_agreement_cancellation_request(
    agreementId='agmt-abc123',
    agreementCancellationRequestId='acr-abc123'
)

Reject a cancellation request

Use RejectAgreementCancellationRequest to reject a cancellation request initiated by the seller. After rejection, the agreement remains active and the seller can create a new cancellation request if needed.

client.reject_agreement_cancellation_request(
    agreementId='agmt-abc123',
    agreementCancellationRequestId='acr-abc123'
)

List payment requests

Use ListAgreementPaymentRequests to list all payment requests for agreements you participate in. You can filter by agreement, status, and other criteria.

response = client.list_agreement_payment_requests(
    partyType='Acceptor',
    agreementId='agmt-abc123'
)

for req in response['agreementPaymentRequests']:
    print(f"  {req['agreementPaymentRequestId']}: {req['status']}")

Get payment request details

Use GetAgreementPaymentRequest to retrieve detailed information about a specific payment request, including status, timestamps, and associated charges.

response = client.get_agreement_payment_request(
    paymentRequestId='apr-abc123',
    agreementId='agmt-abc123'
)

print(f"Status: {response['status']}")
print(f"Amount: ${response['amount']}")

Accept a payment request

Use AcceptAgreementPaymentRequest to approve a payment request initiated by the seller for an active agreement.

client.accept_agreement_payment_request(
    paymentRequestId='apr-abc123',
    agreementId='agmt-abc123'
)

Reject a payment request

Use RejectAgreementPaymentRequest to reject a payment request initiated by the seller. After rejection, the seller can create a new payment request if needed.

client.reject_agreement_payment_request(
    paymentRequestId='apr-abc123',
    agreementId='agmt-abc123'
)