Use the API to purchase a spend-based commitment

This document describes how to purchase a spend-based commitment by using the Cloud Commerce Consumer Procurement API for Cloud Marketplace purchases.

This API only supports purchasing spend-based commitments, not resource-based commitments.

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, use an Offer name which indicates the product you're purchasing and the discount term.

The new CUD model introduces new Offer names for existing CUD products. The following table provides the Offer names both before and after migration to the new spend-based CUD model. You must use the Offer name that matches your Cloud Billing account's model.

The following updated Offers are available for purchase:

The following Offers are unaffected by the new CUD model and available for purchase:

Product	Term	Offer name
Backup for GKE	1 year	`services/gkebackup.googleapis.com/standardOffers/89852607-f073-4696-94cc-de7ed85f27c7`
Backup for GKE	3 years	`services/gkebackup.googleapis.com/standardOffers/25d2877b-2868-4312-b54e-880896a119c5`
Backup and DR (VMWare)	1 year	`services/backupdr.googleapis.com/standardOffers/30c7e770-724f-4a7d-8369-b726a397b53a`
Backup and DR (VMWare)	3 years	`services/backupdr.googleapis.com/standardOffers/6748e93c-4114-4fa2-bf3e-cb4d3534bb48`
NetApp Volumes	1 year	`services/netapp.googleapis.com/standardOffers/90520cfa-14b6-42ae-92b9-129671bf2aca`
NetApp Volumes	3 years	`services/netapp.googleapis.com/standardOffers/c852fef8-e699-4524-90f4-e7b89edeb33c`

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.
In the legacy CUDs program before automatic account migration, your commitment amount was the on-demand price instead. For more information, see Spend-based CUDs.
Region (region): The region for which this commitment's benefits 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

To view an order, run the following command:

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'

Console

In the Google Cloud console, go to your Cloud Billing account.

Go to your Cloud Billing account
Select Committed use discounts (CUDs) from the sidebar.
Your purchased commitments are displayed.