Manage Google Workspace and Google Chrome entitlements

This page describes how to manage customer entitlements for Google Workspace and Google Chrome products.

Pre-requisite

Before you continue, determine whether your reseller account has a single Google Workspace billing account or multiple Google Workspace billing accounts. To learn more about this topic, read Multiple Google Workspace Billing Account Starter Guide .

Create entitlement

Before you begin

You need a Customer setup before you can proceed.

To create entitlement, follow these steps:

1. With the Customer name, call listPurchasableSkus to retrieve a list of PurchasableSkus

   ListPurchasableSkusRequest
   {
     "customer": "accounts/123/customers/abc",
     "createEntitlementPurchase": {
       "product": "products/-"
     }
   }
   ListPurchasableSkusResponse
   {
     "purchasableSkus": [
       {
         "sku": {
           "name": "products/product_id/skus/sku_id1",
           "product": {
             "name": "products/product_id",
           }
         }
       },
       {
         "sku": {
           "name": "products/product_id/skus/sku_id2",
           "product": {
             "name": "products/product_id",
           },
         }
       }
     ]
   }
   

2. With the selected PurchasableSku, use the queryEligibleBillingAccounts method to find a set of Google Workspace BillingAccount that can be used to pay for the entitlement.

   1. If you want to pay in a specific currency, select a BillingAccount with that currency.

   QueryEligibleBillingAccountsRequest
   {
     "customer": "accounts/123/customers/abc",
     "skus": ["products/product_id/skus/sku_id1"]
   }
   QueryEligibleBillingAccountsResponse
   {
     "skuPurchaseGroups": [
       {
         "skus": [
           "products/product_id/skus/sku_id1"
         ],
         "billingAccountPurchaseInfos": [
           {
             "billingAccount": {
               "name": "accounts/123/billingAccounts/billing_account_id1",
               "displayName": "Google_Workspace_USD_US_1",
               "currencyCode": "USD",
               "regionCode": "US"
             }
           },
           {
             "billingAccount": {
               "name": "accounts/123/billingAccounts/billing_account_id2",
               "displayName": "Google_Workspace_CAD_CA_1",
               "currencyCode": "CAD",
               "regionCode": "CA"
             }
           }
         ]
       }
     ]
   }
   

3. With the selected PurchasableSku and BillingAccount, use the listPurchasableOffers method to find the available PurchasableOffer

   ListPurchasableOffersRequest
   {
     "customer": "accounts/123/customers/abc",
     "createEntitlementPurchase": {
       "sku": "products/product_id/skus/sku_id1",
       "billingAccount": "accounts/123/billingAccounts/billing_account_id2"
     }
   }
   ListPurchasableOffersResponse
   {
     "purchasableOffers": [
       {
         "offer": {
           "name": "accounts/123/offers/offer_id1",
         },
         "sku": {
           "name": "products/product_id/skus/sku_id1",
         },
         "plan": {
           "paymentPlan": "FLEXIBLE",
           "paymentCycle": {
             "duration": 1,
             "periodType": "MONTH"
           }
         },
       }
     ],
   }
   

4. At this point you should have the BillingAccount that will pay for the Entitlement and the PurchasableOffer. Begin to create the entitlement by using the create method.

   1. Create an Entitlement and populate the offer, billingAccount and any other required parameters.

   CreateEntitlementRequest
   {
     "parent": "accounts/123/customers/abc",
     "entitlement": {
       "offer": "accounts/123/offers/offer_id1",
       "maxUnits": 100,
       "billingAccount": "accounts/123/billingAccounts/billing_account_id2"
     }
   }
   CreateEntitlementResponse
   {
     "name": "operations/operation_id1"
   }
   

Change payment plan on Google Workspace entitlements

Before you begin

Google Workspace entitlements with a Free or Trial payment plan do not have a Google Workspace billing account. In order to change the payment plan for an Entitlement to a paid payment plan, there are a couple of additional steps to select a Google Workspace billing account.

To change payment plan on Google Workspace entitlements, follow these steps:

The first two steps are only required if the existing Entitlement has a Free or Trial payment plan.

1. With the Offer, use the lookupOffer method to find Sku information on the Offer.

   LookupOfferRequest
   {
     "entitlement": "accounts/123/customers/abc/entitlements/entitlement_id1"
   }
   LookupOffer respones
   {
     "name": "accounts/123/offers/offer_id1",
     "sku": {
       "name": "products/product_id/skus/sku_id1",
      }
   }
   

2. With the Customer and Sku, use the queryEligibleBillingAccounts method to find a set of BillingAccount that can be used to pay for this Entitlement. If you want to pay in a specific currency, select a BillingAccount with that currency.

    QueryEligibleBillingAccountsRequest
    {
      "customer": "accounts/123/customers/abc",
      "skus": ["products/product_id/skus/sku_id1"]
    }
    QueryEligibleBillingAccountsResponse
    {
      "skuPurchaseGroups": [
        {
          "skus": [
            "products/product_id/skus/sku_id1"
          ],
          "billingAccountPurchaseInfos": [
            {
              "billingAccount": {
                "name": "accounts/123/billingAccounts/billing_account_id1",
                "displayName": "Google_Workspace_USD_US_1",
                "currencyCode": "USD",
                "regionCode": "US"
              }
            },
            {
              "billingAccount": {
                "name": "accounts/123/billingAccounts/billing_account_id2",
                "displayName": "Google_Workspace_CAD_CA_1",
                "currencyCode": "CAD",
                "regionCode": "CA"
              }
            }
          ]
        }
      ]
    }
    ```
   

3. With the Entitlement and BillingAccount, use the listPurchasableOffers method to find any PurchasableOffer. The BillingAccount is not needed if the existing entitlement already has a paid plan, in this case, the existing BillingAccount will be used. To change the payment plan, the purchase_option field needs to be changeOfferPurchase

   ListPurchasableOffersRequest
   {
     "customer": "accounts/123/customers/abc",
     "changeOfferPurchase": {
       "entitlement": "accounts/123/customers/abc/entitlements/entitlement_id1",
       "billingAccount": "accounts/123/billingAccounts/billing_account_id2"
     }
   }
   ListPurchasableOffersResponse
   {
     "purchasableOffers": [
       {
         "offer": {
           "name": "accounts/123/offers/offer_id1",
         },
         "sku": {
           "name": "products/product_id/skus/sku_id1",
         },
         "plan": {
           "paymentPlan": "FLEXIBLE",
           "paymentCycle": {
             "duration": 1,
             "periodType": "MONTH"
           }
         },
       }
     ],
   }
   

4. At this point you should have the Entitlement, Offer and the BillingAccount. Begin to change the payment plan by using the changeOffer method.

   ChangeOfferRequest
   {
     "name": "accounts/abc/customers/123/entitlements/entitlement_id1",
     "offer": "accounts/abc/offers/offer_id1",
     "billing_account": "accounts/abc/billingAccounts/billing_account_id2",
     "parameters": [{
       "name": "max_units",
       "value": {
         "int64Value": "100"
       }
     }]
   }
   ChangeOfferResponse
   {
     "name": "operations/operation_id1"
   }
   

Upgrade or downgrade Google Workspace entitlements

To upgrade or downgrade Google Workspace entitlements, follow these steps:

1. With the Entitlement, call the listPurchasableSkus method to retrieve a list of PurchasableSkus that can be used for upgrade or downgrade.

   ListPurchasableSkusRequest
   {
     "customer": "accounts/123/customers/abc",
     "changeOfferPurchase": {
       "entitlement": "accounts/123/customers/abc/entitlements/entitlement_id1",
       "changeType": "UPGRADE"
     }
   }
   ListPurchasableSkusResponse
   {
     "purchasableSkus": [
       {
         "sku": {
           "name": "products/product_id/skus/sku_id1",
           "product": {
             "name": "products/product_id",
           }
         }
       },
       {
         "sku": {
           "name": "products/product_id/skus/sku_id2",
           "product": {
             "name": "products/product_id",
           },
         }
       }
     ]
   }
   

2. With the PurchasableSku, use the queryEligibleBillingAccounts method to find a set of BillingAccounts that can be used to pay for the Entitlement.

   1. If you want to pay in a specific currency, select a BillingAccount with that currency.

    QueryEligibleBillingAccountsRequest
    {
      "customer": "accounts/123/customers/abc",
      "skus": ["products/product_id/skus/sku_id1"]
    }
    QueryEligibleBillingAccountsResponse
    {
      "skuPurchaseGroups": [
        {
          "skus": [
            "products/product_id/skus/sku_id1"
          ],
          "billingAccountPurchaseInfos": [
            {
              "billingAccount": {
                "name": "accounts/123/billingAccounts/billing_account_id1",
                "displayName": "Google_Workspace_USD_US_1",
                "currencyCode": "USD",
                "regionCode": "US"
              }
            },
            {
              "billingAccount": {
                "name": "accounts/123/billingAccounts/billing_account_id2",
                "displayName": "Google_Workspace_CAD_CA_1",
                "currencyCode": "CAD",
                "regionCode": "CA"
              }
            }
          ]
        }
      ]
    }
    ```
   

3. With the Entitlement and BillingAccount, use the listPurchasableOffers method to find any PurchasableOffer.

     ListPurchasableOffersRequest
     {
       "customer": "accounts/123/customers/abc",
       "changeOfferPurchase": {
         "entitlement": "accounts/123/customers/abc/entitlements/entitlement_id1",
         "billingAccount": "accounts/123/billingAccounts/billing_account_id2"
       }
     }
     ListPurchasableOffersResponse
     {
       "purchasableOffers": [
         {
           "offer": {
             "name": "accounts/123/offers/offer_id1",
           },
           "sku": {
             "name": "products/product_id/skus/sku_id1",
           },
           "plan": {
             "paymentPlan": "FLEXIBLE",
             "paymentCycle": {
               "duration": 1,
               "periodType": "MONTH"
             }
           },
         }
       ],
     }
     ```
   

4. At this point you should have the Entitlement, PurchasableOffer and the BillingAccount. Begin to upgrade or downgrade by using the changeOffer method.

   1. Create an Entitlement object and populate the name, offer, billingAccount and any required parameters.

      ChangeOfferRequest
      {
        "name": "accounts/abc/customers/123/entitlements/entitlement_id1",
        "offer": "accounts/abc/offers/offer_id1",
        "billing_account": "accounts/abc/billingAccounts/billing_account_id2",
        "parameters": [{
          "name": "max_units",
          "value": {
            "int64Value": "100"
          }
        }]
      }
      ChangeOfferResponse
      {
        "name": "operations/operation_id1"
      }
      ```
   

Transfer entitlements

This section helps you transfer entitlements for existing Google Workspace and Chrome customers from their previous partner.

For help transferring customers in the Partner Sales Console, see our guides on transferring customers to a partner account or a Google account

Google Workspace customers can only purchase entitlements from a single partner or a single partner and Google.

During the transfer, existing entitlements are automatically canceled before they are created again under the new partner. If a customer has commitment plan entitlements, those will start a new commitment term after the transfer.

Before you begin

To manage entitlements for a customer, you need a customer-generated transfer token. Contact the customer and provide your Partner Public Identifier so they can generate a transfer token. After they create a token, the customer needs to send their transfer token back to you to complete the process. These tokens expire 14 days after creation. You also need the customer's domain or Cloud Identity ID.

When the customer creates their transfer token, they select the entitlements they want to transfer to their new reseller. You need to transfer all the selected entitlements during the process.

To transfer entitlements, follow these steps:

If you only have the customer's domain, you can use the Cloud Channel API to return their Cloud Identity ID. Call checkCloudIdentityAccountsExist with the customer's domain and, if the domain exists, the API will return the customer's Cloud Identity ID.

1. Begin the transfer by using the customers.import method to import the customer's data.

   ImportCustomerRequest
   {
     "parent": "accounts/abc",
     "domain": "domain"
   }
   

2. With the customer's Cloud Identity ID, call listTransferableSkus to retrieve a list of the customer's transferableSku Check each object's transferEligibility to make sure you can purchase the associated SKU.

   ListTransferableSkusRequest
   {
     "parent": "accounts/abc",
     "cloudIdentityId": "cloud_identity_id"
   }
   ListTransferableSkusResponse
   {
     "transferableSku": [
       {
         "sku": {
              "name": "products/product_id/skus/voice_sku_id1",
         },
       },
       {
         "sku": {
              "name": "products/product_id/skus/google_workspace_sku_id2",
         },
       },
       {
         "sku": {
              "name": "products/product_id/skus/google_workspace_chrome_sku_id3",
         },
       }
     ],
   }
   

3. Now that you have a list of TransferableSkus, you need to determine what BillingAccount to use to pay for the entitlements. Use the queryEligibleBillingAccounts method to find a set of BillingAccount that can be used for each TransferableSku.

   1. Note that certain TransferableSkus must share the same Google Workspace billing account, which is why queryEligibleBillingAccounts returns a sku group that informs you which TransferableSkus need to use the same BillingAccount. If there are multiple Google Workspace billing account for a given SKU group, you can pick one of the Google Workspace billing account and use it for every TransferableSku in the group.

   QueryEligibleBillingAccountsRequest
   {
     "customer": "accounts/123/customers/abc",
     "skus": ["products/product_id/skus/voice_sku_id1","products/product_id/skus/google_workspace_sku_id2","google_workspace_chrome_sku_id3"]
   }
   QueryEligibleBillingAccountsResponse
    {
      "skuPurchaseGroups": [
        {
          "skus": [
            "products/product_id/skus/voice_sku_id1"
          ],
          "billingAccountPurchaseInfos": [
            {
              "billingAccount": {
                "name": "accounts/123/billingAccounts/voice_billing_account_id1",
                "displayName": "Google_Workspace_Voice_USD_US_1",
                "currencyCode": "USD",
                "regionCode": "US"
              }
            }
          ]
        },
        {
          "skus": [
            "products/product_id/skus/google_workspace_sku_id2","google_workspace_chrome_sku_id3"
          ],
          "billingAccountPurchaseInfos": [
            {
              "billingAccount": {
                "name": "accounts/123/billingAccounts/gw_billing_account_id1",
                "displayName": "Google_Workspace_USD_US_1",
                "currencyCode": "USD",
                "regionCode": "US"
              }
            },
            {
              "billingAccount": {
                "name": "accounts/123/billingAccounts/gw_billing_account_id2",
                "displayName": "Google_Workspace_CAD_CA_1",
                "currencyCode": "CAD",
                "regionCode": "CA"
              }
            }
          ]
        }
      ]
    }
    ```
   

4. For each TransferableSku and BillingAccount pairs, use the listTransferableOffers method to find available TransferableOffers . At this point you should have the customer's list of tuples consisting of TransferableSku, BillingAccounts, and TransferableOffer.

   ListTransferableOffersRequest
   {
     "parent": "accounts/abc",
     "cloudIdentityId": "cloud_identity_id",
     "sku": "products/product_id/skus/voice_sku_id1",
     "billingAccount": "ccounts/123/billingAccounts/voice_billing_account_id1"
   }
   ListTransferableOffersResponse
      {
        "transferableOffers": [
          {
            "offer": {
              "name": "accounts/123/offers/voice_offer_id1",
            },
            "sku": {
              "name": "products/product_id/skus/voice_sku_id1",
            },
            "plan": {
              "paymentPlan": "FLEXIBLE",
              "paymentCycle": {
                "duration": 1,
                "periodType": "MONTH"
              }
            },
          }
        ],
      }
   

5. For each tuple create a new corresponding Entitlement object, each Entitlement needs an Offer, BillingAccount and any required parameters. Call the transferEntitlements method to perform the transfer.

   TransferEntitlementsRequest
   {
     "parent": "accounts/abc/customers/123",
     "entitlements": [
       { 
         "offer": "accounts/123/offers/voice_offer_id1",
         "maxUnits": 100,
         "billingAccount": "accounts/123/billingAccounts/voice_billing_account_id1"
       },
       {
         "offer": "accounts/123/offers/gw_offer_id2",
         "maxUnits": 150,
         "billingAccount": "accounts/123/billingAccounts/gw_billing_account_id1"
       }
       {
         "offer": "accounts/123/offers/gw_chrome_offer_id3",
         "maxUnits": 200,
         "billingAccount": "accounts/123/billingAccounts/gw_billing_account_id1"
       }   
     ]
   }
   TransferEntitlementsResponse
   {
     "name": "operations/operation_id1"
   }