Request Syntax Request Parameters Response Syntax Response Elements Errors Examples See Also

CreateAgreementRequest

Creates an agreement request that acts as a quote for the terms you want to accept. The agreement request captures the requested terms, calculates charges, and returns a summary. Use AcceptAgreementRequest with the returned agreementRequestId to finalize the agreement.

Request Syntax


{
   "agreementProposalIdentifier": "string",
   "clientToken": "string",
   "intent": "string",
   "requestedTerms": [ 
      { 
         "configuration": { ... },
         "id": "string"
      }
   ],
   "sourceAgreementIdentifier": "string",
   "taxConfiguration": { 
      "taxEstimation": "string"
   }
}

Request Parameters

The request accepts the following data in JSON format.

Note

In the following list, the required parameters are described first.

intent

The purpose and desired outcome of the agreement request. This is a required parameter that determines how the agreement request is processed.

NEW – Creates a new agreement for terms in the request.
AMEND – Modifies an existing agreement with terms that are accepted in the request.
REPLACE – Creates a new agreement with accepted terms and replaces the existing agreement.

Type: String

Valid Values: NEW | AMEND | REPLACE

Required: Yes

requestedTerms

A list of terms that define what is being accepted as part of the agreement. Some terms require configuration.

Type: Array of RequestedTerm objects

Array Members: Minimum number of 1 item. Maximum number of 30 items.

Required: Yes

agreementProposalIdentifier

The agreement proposal signed by the proposer. The proposal includes the requested resources and the terms that outline an agreement outcome.

Important

This parameter is required if the intent is not AMEND.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: (at-|ap-)[A-Za-z0-9]+

Required: No

clientToken

A unique, case-sensitive identifier that you provide to ensure the idempotency of the request.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: [a-zA-Z0-9-]+

Required: No

sourceAgreementIdentifier

The agreement's identifier that the request acts upon.

Important

This parameter is required for all non-NEW intents (i.e., AMEND or REPLACE). Don't provide this parameter if the intent is NEW.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: [A-Za-z0-9_/-]+

Required: No

taxConfiguration

Configuration for tax estimation in the agreement request response.

Type: TaxConfiguration object

Required: No

Response Syntax


{
   "agreementRequestId": "string",
   "chargeSummary": { 
      "currencyCode": "string",
      "estimatedTaxes": { 
         "breakdown": [ 
            { 
               "amount": "string",
               "rate": "string",
               "type": "string"
            }
         ],
         "totalAmount": "string"
      },
      "expectedCharges": [ 
         { 
            "amount": "string",
            "amountAfterTax": "string",
            "estimatedTaxes": { 
               "breakdown": [ 
                  { 
                     "amount": "string",
                     "rate": "string",
                     "type": "string"
                  }
               ],
               "totalAmount": "string"
            },
            "id": "string",
            "time": number,
            "timing": "string"
         }
      ],
      "invoicingEntity": { 
         "branchName": "string",
         "legalName": "string"
      },
      "itemizedCharges": [ 
         { 
            "chargeReference": "string",
            "dimensionKey": "string",
            "incrementalChargeAmount": "string",
            "newQuantity": number,
            "oldQuantity": number
         }
      ],
      "newAgreementValue": "string",
      "newAgreementValueAfterTax": "string"
   }
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

agreementRequestId

The unique identifier of the agreement request created. Use this identifier with AcceptAgreementRequest to accept the agreement.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: ar-[A-Za-z0-9]+

chargeSummary

Provides details of the charges associated with the agreement request. This is only applicable when a request is created for PurchaseAgreement.

Type: ChargeSummary object

Errors

For information about the errors that are common to all actions, see Common Error Types.

AccessDeniedException

User does not have sufficient access to perform this action.

message: Description of the error.
reason: The reason for the access denied exception.
requestId: The unique identifier for the error.

HTTP Status Code: 400

ConflictException

Request was denied due to a resource conflict.

message: Description of the error.
requestId: The unique identifier for the error.
resourceId: The unique identifier of the resource involved in the conflict.
resourceType: The type of the resource involved in the conflict.

HTTP Status Code: 400

InternalServerException

Unexpected error during processing of request.

message: Description of the error.
requestId: The unique identifier for the error.

HTTP Status Code: 500

ResourceNotFoundException

Request references a resource which does not exist.

message: Description of the error.
requestId: The unique identifier for the error.
resourceId: The unique identifier for the resource.
resourceType: The type of resource.

HTTP Status Code: 400

ServiceQuotaExceededException

Request exceeded the maximum allowed limit (quota) for a specific resource or API operation.

message: Description of the error.
quotaCode: The code of the quota that was exceeded.
requestId: The unique identifier for the error.
resourceId: The unique identifier of the resource that exceeded the quota.
resourceType: The type of the resource that exceeded the quota.
serviceCode: The code of the service whose quota was exceeded.

HTTP Status Code: 400

ThrottlingException

Request was denied due to request throttling.

message: Description of the error.
requestId: The unique identifier for the error.

HTTP Status Code: 400

ValidationException

The input fails to satisfy the constraints specified by the service.

fields: The fields associated with the error.
message: Description of the error.
reason: The reason associated with the error.
requestId: The unique identifier associated with the error.

HTTP Status Code: 400

Examples

Sample request

This example illustrates one usage of CreateAgreementRequest.


{
    "clientToken": "75298638-97dc-4588-bd5b-e7d5a40f1367",
    "intent": "NEW",
    "requestedTerms": [
        {
            "id": "term-EXAMPLE1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d",
            "configuration": {
                "configurableUpfrontPricingTermConfiguration": {
                    "selectorValue": "P12M",
                    "dimensions": [
                        {
                            "dimensionKey": "AdminUsers",
                            "dimensionValue": 5
                        },
                        {
                            "dimensionKey": "ReadOnlyUsers",
                            "dimensionValue": 10
                        }
                    ]
                }
            }
        },
        {
            "id": "term-EXAMPLE2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e",
            "configuration": {
                "renewalTermConfiguration": {
                    "enableAutoRenew": false
                }
            }
        },
        {
            "id": "term-EXAMPLE3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f"
        }
    ],
    "agreementProposalIdentifier": "ap-EXAMPLE6b64-0c26-8e5EXAMPLE12"
}

Sample response

This example illustrates one usage of CreateAgreementRequest.


{
    "agreementRequestId": "ar-EXAMPLE4a53-9b12-3d4EXAMPLE78",
    "chargeSummary": {
        "currencyCode": "USD",
        "newAgreementValue": "100",
        "expectedCharges": [
            {
                "id": "ch-EXAMPLE4b42-9614-5c3EXAMPLE56",
                "amount": "100",
                "time": null,
                "timing": "ON_ACCEPTANCE"
            },
            {
                "id": "ch-EXAMPLE5c53-0725-6d4EXAMPLE67",
                "amount": null,
                "time": null,
                "timing": "BILLING_PERIOD"
            }
        ],
        "itemizedCharges": [
            {
                "dimensionKey": "AdminUsers",
                "newQuantity": 5,
                "oldQuantity": 0,
                "incrementalChargeAmount": "50",
                "chargeReference": "ch-EXAMPLE4b42-9614-5c3EXAMPLE56"
            },
            {
                "dimensionKey": "ReadOnlyUsers",
                "newQuantity": 10,
                "oldQuantity": 0,
                "incrementalChargeAmount": "50",
                "chargeReference": "ch-EXAMPLE4b42-9614-5c3EXAMPLE56"
            }
        ]
    }
}