Purchase a spend-based commitment

Stay organized with collections Save and categorize content based on your preferences.

Today, only spend-based commitments for selected products can be purchased via the API. This how-to describes how to purchase a spend-based commitment.

Before you begin

• Enable the Cloud Commerce Consumer Procurement API for your Google Cloud project.

• Ensure that you have one of the following Identity and Access Management (IAM) roles for the Cloud Billing account you want to use to purchase the commitment:

  • Billing Administrator (roles/billing.admin) for the target Cloud Billing account OR the Google Cloud organization where your billing account is located.

  • Consumer Procurement Order Administrator (roles/consumerprocurement.orderAdmin) for the target Cloud Billing account OR the Google Cloud organization where your billing account is located.

Identify the Offer you want to purchase

To purchase a spend-based commitment, you use an Offer name which indicates the product you're purchasing and the discount term.

The following Offers are available for purchase:

Identify the Offer parameters

Commitments have two parameters:

• Commitment amount (hourly_commit): The credit applied to your Cloud Billing account each hour after you purchase this commitment.
• Region (region): The region for which this commitment's credits apply.

When you purchase a commitment, you must specify both parameters.

Purchase the Offer

To purchase an Offer, call billingAccounts.orders.place, and supply the following parameters:

• The hourly_commit indicating the dollar value of the commitment.

• The region to purchase the commitment for.

To place an order, run the following command:

curl 'https://cloudcommerceconsumerprocurement.googleapis.com/v1alpha1/billingAccounts/BILLING_ACCOUNT_ID/orders:place' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer ACCESS_TOKEN' \
    --header 'X-Goog-User-Project: CONSUMER_PROJECT_ID' \
    -d '@-' <<EOF
    {
    "displayName": "DISPLAY_NAME",
    "lineItemInfo": [{
        "parameters": [{
        "name": "hourly_commit",
        "value": {
            "doubleValue": HOURLY_COMMIT
        }
        }, {
        "name": "region",
        "value": {
            "stringValue": "REGION"
        }
        }],
        "offer": "OFFER_NAME"
    }]
    }
EOF

This returns the name of a long-running operation:

{
    "name": "OPERATION_NAME"
}

To verify that the returned long-running operation completed successfully, run the following command:

curl 'https://cloudcommerceconsumerprocurement.googleapis.com/v1alpha1/OPERATION_NAME' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer ACCESS_TOKEN' \
    --header 'X-Goog-User-Project: CONSUMER_PROJECT_ID'

The long-running operation should complete in less than one second.

View your Order

You can view the current state of a commitment directly in Google Cloud console, or by calling billingAccounts.orders.get. The name field of the created Order specifies the Order name.

curl 'https://cloudcommerceconsumerprocurement.googleapis.com/v1alpha1/ORDER_NAME' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer ACCESS_TOKEN' \
    --header 'X-Goog-User-Project: CONSUMER_PROJECT_ID'