Integrating your SaaS app's backend for private offers

This page explains how to integrate your SaaS product's backend for Private Offers, version 2, available on Producer Portal.

These steps aren't necessary for VM products. For additional instructions on using entitlements to track usage, see the documentation for Integrating your app's backend.

Before you begin

  • Your product must be integrated with, and listed on, Google 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.

Managing entitlements

When a customer purchases a private offer, Google creates an entitlement, which indicates that the customer has bought the offer from Google 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.

Approving or rejecting an entitlement

When a customer purchases a private offer, Google 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": "...",

  },
}

where ENTITLEMENT_ID is an ID created by Google Cloud Marketplace.

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

Replacing 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": "...",
  },
}

where OFFER2 is the replacement offer and ENTITLEMENT_ID is an ID created by Google Cloud Marketplace.

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",
  ...
}

Completing other entitlement tasks

For other entitlement tasks, refer to the Google 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.