Manage entitlements for private offers

When a customer purchases a private offer, Google creates an entitlement, which indicates that the customer has bought the offer from Cloud Marketplace.

This article reviews how to manage entitlements for your private offers by using the Partner Procurement API.

Caution: If you've turned on automatic offer approval for your software as a service (SaaS) product, you receive different Pub/Sub messages from those described in this article. You should instead refer to Manage entitlements for private offers with automatic offer approval.

For details on using the Partner Procurement API for private offers, visit the reference documentation.

Note: You can also perform some management tasks, like approving entitlements, in Producer Portal when you view your list of offers.

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

Caution: If you don't approve your customer's entitlement before the scheduled start date of their offer, that offer is automatically rejected, for both new offers and amendments to existing offers.

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:

• Send a status message to users
• Cancel an entitlement
• Delete an entitlement

List of event types for private offer account tasks

The following table includes eventTypes 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.