This page explains how to integrate your SaaS product's backend for Private Offers, version 2.
These steps aren't necessary for VM products. For additional instructions on using entitlements to track usage, refer to Integrate your app's backend.
Before you begin
Your product must be integrated with, and listed on, Cloud Marketplace. At least one of your pricing plans must be publicly available.
You must have onboarded the product to Producer Portal and integrated your app's backend for the pricing plan that you are using for the offer. For steps, visit Integrating your app's backend.
Manage entitlements
When a customer purchases a private offer, Google creates an entitlement, which indicates that the customer has bought the offer from Cloud Marketplace. This section reviews how to manage entitlements for your private offers using the Partner Procurement API.
For details on using the Partner Procurement API for private offers, see the reference documentation.
Some management tasks, like approving entitlements, can also be performed in Producer Portal when viewing your list of offers.
Approve or reject an entitlement
When a customer purchases a private offer, Cloud Marketplace creates an entitlement and sends the following Pub/Sub message to your app:
{
"eventId": "...",
"eventType": "ENTITLEMENT_CREATION_REQUESTED",
"entitlement": {
"id": "ENTITLEMENT_ID",
"updateTime": "...",
"newOfferDuration": "P1Y6M", // Contract duration for the offer
"newOfferEndTime": "", // Ending time for the offer
},
}
where 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 will be empty. If the offer
was created with a specified ending time, the message displays the offer's end
time, and the newOfferDuration field will be empty.
In your system, update the user's account to reflect that they have 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
To reject an entitlement, instead 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
},
}
where 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/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID",
"provider": "YOUR_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": "",
...
}
Completing other entitlement tasks
For other entitlement tasks, refer to the Cloud Marketplace public documentation:
List of event types for private offer account tasks
The following table includes eventTypes that your app 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. |