When customers choose a pricing plan for your software, Google creates an entitlement , which indicates that the customer has bought your product from Cloud Marketplace. This section reviews how to create and manage entitlements for your customers using the Partner Procurement API.
For more details on managing entitlements, visit the reference documentation .
Before you begin
- Set up access to the Cloud Commerce Partner Procurement API, as described in Integrate your app .
If you've turned on multiple orders of the same product, the
Partner Procurement API can send multiple events with the event type ENTITLEMENT_ACTIVE
for the same value of ACCOUNT_ID
, each with a unique ENTITLEMENT_ID
representing a different offer. This means that you must
ensure that your app's event handling logic can respond to the ENTITLEMENT_ID
instead of the ACCOUNT_ID
or the PRODUCT_ID
.
You must ensure that your frontend integration can handle the new orders
object included in the JWT payload. For more information, see Integrate your app's frontend
.
For more information about turning on multiple orders of the same product, see Turn on multiple orders of the same product .
Approve an entitlement
When a customer chooses a pricing plan, Cloud Marketplace creates an entitlement and sends the following Pub/Sub message to your app:
{ "eventId" : "..." , "eventType" : "ENTITLEMENT_CREATION_REQUESTED" , "providerId" : " YOUR_PARTNER_ID " , "entitlement" : { "id" : " ENTITLEMENT_ID " , "updateTime" : "..." , "newOfferDuration" : "P2Y3M" , // Contract duration for offer-based entitlements }, }
where ENTITLEMENT_ID is an ID created by Cloud Marketplace. If the offer has a specified duration, that duration is provided in years and months. If the offer has a specified end date, instead of a duration, the field indicating the duration is empty.
In your system, update the user's account to reflect that they have purchased
a plan. Then, to approve the entitlement, make an HTTP POST
request to the
Partner Procurement API, and send the ENTITLEMENT_ID
that you're
approving:
POST v1/providers/ YOUR_PARTNER_ID /entitlements/ ENTITLEMENT_ID :approve
Reject an entitlement
To reject an entitlement, make an HTTP POST
request to the
Partner Procurement API, and use the reject
method in your request:
POST v1/providers/ YOUR_PARTNER_ID /entitlements/ ENTITLEMENT_ID :reject
To give a reason for rejecting the entitlement in the request body, use the following format:
{ "reason" : "..." }
Change an entitlement plan
Depending on how you set up your pricing plans, your customers might be able to change their plan. If a customer selects a new pricing plan, you receive a Pub/Sub message, in the following format:
{ "eventId" : "..." , "eventType" : "ENTITLEMENT_PLAN_CHANGE_REQUESTED" , "providerId" : " YOUR_PARTNER_ID " , "entitlement" : { "id" : " ENTITLEMENT_ID " , "newPlan" : "ultimate" , // New plan "updateTime" : "..." , "newOfferDuration" : "P2Y3M" , // Contract duration for the new offer, for offer-based entitlements "newProduct" : "test-product.cloud.goog" "newOffer" : "projects/1234567/services/test-product.cloud.goog/standardOffers/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa" }, }
If the offer has a specified duration, that duration is provided in years and months. If the offer has a specified end date, instead of a duration, the field indicating the duration is empty.
To approve the plan change, make the following HTTP POST
request to the
Partner Procurement API:
POST v1/providers/ YOUR_PARTNER_ID
/entitlements/ ENTITLEMENT_ID
:approvePlanChange
The request body must have the plan that is being approved:
{
"pendingPlanName"
:
PLAN_NAME
}
After the change is approved, you receive another Pub/Sub message
when the change takes effect. In the message, the eventType
field changes to ENTITLEMENT_PLAN_CHANGED
. To check the status of a plan, make the following HTTP GET
request to the Partner Procurement API.
GET v1/providers/ YOUR_PARTNER_ID /entitlements/ ENTITLEMENT_ID
The response is similar to the following, with the state
field indicating
whether the new plan is active, or whether the plan change is still pending:
{ "name" : "providers/ YOUR_PARTNER_ID /entitlements/ ENTITLEMENT_ID " , "provider" : " YOUR_PARTNER_ID " , "account" : " USER_ACCOUNT_ID " , "product" : "example-server" , "plan" : "pro" , "state" : "ENTITLEMENT_PENDING_PLAN_CHANGE" , "newPendingPlan" : "ultimate" , ... }
Cancel an entitlement
If a user decides to cancel their entitlement, you receive a Pub/Sub notification. Similar to changing a plan, the actual cancellation might take effect at the end of the current billing cycle.
The notification is in the following format:
{ "eventId" : "..." , // If the entitlement is canceled at the end of the month, // eventType is ENTITLEMENT_PENDING_CANCELLATION "eventType" : "ENTITLEMENT_CANCELLED" , "providerId" : " YOUR_PARTNER_ID " , "entitlement" : { "id" : " ENTITLEMENT_ID " , "updateTime" : "..." }, }
Delete an entitlement
If a user makes a direct request to Google support, or if they leave the Google platform, their entitlements are immediately canceled, and their entitlement and accounts are deleted after a 60 day grace period. To protect the user's privacy, you must delete their data from your servers when you're notified.
When the entitlements are canceled and the account is deleted, you receive notifications similar to the following:
{ "eventId" : "..." , "eventType" : "ENTITLEMENT_DELETED" , "providerId" : " YOUR_PARTNER_ID " , "entitlement" : { "id" : " ENTITLEMENT_ID " , "updateTime" : "..." , }, }
{ "eventId" : "..." , "eventType" : "ACCOUNT_DELETED" , "providerId" : " YOUR_PARTNER_ID " , "account" : { "id" : " USER_ACCOUNT_ID " , "updateTime" : "..." , }, }
List of event types for account tasks
The following is a list of the eventType
s that your app might receive in
Pub/Sub messages:
| ENTITLEMENT_DELETED | Indicates that information about a customer's plan was deleted from Cloud Marketplace. |
|---|
