When a customer purchases a private offer, Google creates an entitlement, which indicates that the customer has bought the offer from Cloud Marketplace.
This document reviews how to manage entitlements for your private offers by using Producer Portal and the Partner Procurement API. You can use Producer Portal to approve offer entitlements. For other offer entitlement management tasks, you must use the Partner Procurement API.
Approve entitlements by using Producer Portal
You can use Producer Portal to approve entitlements for private offers. To approve an entitlement by using Producer Portal, complete the following steps:
In Producer Portal, go to the Private Offers page.
Click Manage your offers
.
Manage entitlements by using the Partner Procurement API
The following sections describe how to manage entitlements for private offers by using the Partner Procurement API.
For details on using the Partner Procurement API for private offers, visit the reference documentation.
Approve an entitlement
When a customer purchases a private offer, Cloud Marketplace creates an entitlement and sends the following Pub/Sub message to your product:
{ "eventId": "...", "eventType": "ENTITLEMENT_CREATION_REQUESTED", "entitlement": { "id": "ENTITLEMENT_ID", "updateTime": "...", "newOfferDuration": "P1Y6M", // Contract duration for the offer "newOfferEndTime": "", // Ending time for the offer }, }
In this example, ENTITLEMENT_ID is an ID created by Cloud Marketplace.
If the offer was created with a duration, the message displays the duration in
years and months, and the newOfferEndTime
field is empty. If the offer was
created with a specified ending time, the message displays the offer's end
time, and the newOfferDuration
field is empty.
In your system, update the user's account to reflect that they've purchased the
offer. 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, use the reject
method in your HTTP POST
request:
POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:reject
Replace an active offer
Depending on how you set up your private offer, your customer might be able to replace their offer. If a customer selects a new private offer, you receive a Pub/Sub message, in the following format:
{ "eventId": "...", "eventType": "ENTITLEMENT_PLAN_CHANGE_REQUESTED", "entitlement": { "id": "ENTITLEMENT_ID", "newPlan": "ultimate", // New plan for the offer, "newOffer": "OFFER2", // New offer, "updateTime": "...", "newOfferDuration": "P2Y", // Contract duration for the new offer }, }
In this example, OFFER2 is the replacement offer and ENTITLEMENT_ID is an ID created by Cloud Marketplace. The offer duration is provided in years and months.
To approve the offer replacement, 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 for the offer 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 offer is active, or whether the offer change is still pending:
{ "name": "providers/PARTNER_ID/entitlements/ENTITLEMENT_ID", "provider": "PARTNER_ID", "account": "USER_ACCOUNT_ID", "product": "example-server", "Offer": "OFFER1", "plan": "pro", "state": "ENTITLEMENT_PENDING_PLAN_CHANGE", "newPendingOffer": "OFFER2", "newPendingPlan": "ultimate", "newOfferDuration": "P2Y", "newOfferEndTime": "", ... }
Complete other entitlement tasks
For other entitlement tasks that aren't specific to private offers, refer to the Cloud Marketplace public documentation:
List of event types for private offer account tasks
The following table includes eventType
s that your product might receive in
Pub/Sub messages for private offers.
For the full list, see List of event types for account tasks.
eventType | Description |
---|---|
ENTITLEMENT_OFFER_ENDED |
Indicates that a customer's private offer has ended. The offer either
triggers an ENTITLEMENT_CANCELLED event or remains active with
non-discounted pricing. |
What's next
- Create a private offer for a specific customer.