Integrating your SaaS app's backend for private offers

Stay organized with collections Save and categorize content based on your preferences.

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.