Integrating Your Application's Backend

This section describes the steps to integrate your application's backend with GCP Marketplace. With this integration, you can manage users' accounts and entitlements, which indicate that users have bought your product from GCP Marketplace. If you chose a usage-based pricing model, you also integrate your backend to report usage to Boogle.

For an example of integrating a basic application with GCP Marketplace and a walkthrough of the sample code, see the codelab to integrate a managed service.

For the sample code used in the codelab, see the GitHub repository.

Before you begin

  • Set up access to the Cloud Commerce Partner Procurement API, as described in Integrating Your Application: Setting Up.
  • If you chose a usage-based pricing scheme, verify that your Partner Engineer has created a service that you can report usage against.

User account tasks

At a high level, your application must handle the following scenario:

  1. A user makes a request or change in GCP Marketplace, such as signing up for your solution.

  2. GCP Marketplace sends your application a notification through Cloud Pub/Sub, containing information about the request in the eventType field. For example, if a user changes their entitlement, the eventType is ENTITLEMENT_PLAN_CHANGE.

  3. To approve the request, your application sends an HTTP POST request to the Partner Procurement API.

The following sections describe the types of requests that users can make, and what your application must do to handle the requests.

For the API calls described in this section, use this endpoint:

https://cloudcommerceprocurement.googleapis.com/

Creating an account for a new user

When a user first purchases your solution, GCP Marketplace creates an account resource that tracks the user's relationship with you. When the account resource is created, you get notified through the Cloud Pub/Sub topic that was created for you. The Cloud Pub/Sub message is in the following format:

{
  "eventId": "...",
  "account": {
    "id": "USER_ACCOUNT_ID",
    "updateTime": "..."
  }
}

Where USER_ACCOUNT_ID is the account ID created by GCP Marketplace.

Simultaneously, the user is directed to your sign-up page, where they create an account in your system. For information on creating the sign-up page, see Integrating Your Application's Frontend.

After the user has successfully signed up, your application must call the Partner API and indicate that the account has been approved. Accounts are created in the ACCOUNT_ACTIVE state, but they have a PENDING entry in the approvals field called signup, which indicates that the user has not yet signed up. To approve the account after the user has signed up, use the following HTTP POST request:

POST v1/providers/YOUR_PARTNER_ID/accounts/USER_ACCOUNT_ID:approve {'approvalName': 'signup'}

Where YOUR_PARTNER_ID is an ID assigned to you when your Partner Engineer enables access to the Partner Procurement API.

To check the status of a linked account, use the following HTTP GET request:

GET v1/providers/YOUR_PARTNER_ID/accounts/USER_ACCOUNT_ID

The response is in the following format:

{
  "name": "providers/YOUR_PARTNER_ID/accounts/USER_ACCOUNT_ID",
  "provider": "acme-services",
  "state": "ACCOUNT_ACTIVE",
  "approvals": [{
    "name": "signup",
    "state": "APPROVED",
    "updateTime": "...",
  }],
  "updateTime": "...",
  "createTime": "..."
}

Creating an entitlement

When customers choose a pricing plan for your software, Boogle creates an entitlement, which indicates that the customer has bought your solution from GCP Marketplace.

When a customer chooses a plan, the following Cloud Pub/Sub message is sent to your application:

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_CREATION_REQUESTED",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
  },
}

Where ENTITLEMENT_ID is an ID created by GCP Marketplace.

In your system, update the user's account to reflect that they have purchased a plan. Then, to approve the entitlement, make an HTTP POST request to the Partner Procurement API, and send the ENTITLEMENT_ID that you are approving:

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approve

Changing an entitlement plan

Depending on how you set up your pricing plans, your customers might be able to change their plan. If a customer selects a new pricing plan, you receive a Cloud Pub/Sub message, in the following format:

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_PLAN_CHANGE_REQUESTED",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "newPlan": "ultimate",   // New plan
    "updateTime": "...",
  },
}

To approve the plan change, make the following HTTP POST request to the Partner API:

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approvePlanChange

The request body must have the plan that is being approved:

{
  "pendingPlanName": PLAN_NAME
}

After the change is approved, you receive another Cloud 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 plan is active, or whether the plan change is still pending.

{
  "name": "providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID",
  "provider": "YOUR_PARTNER_ID",
  "account": "USER_ACCOUNT_ID",
  "product": "example-server",
  "plan": "pro",
  "state": "ENTITLEMENT_PENDING_PLAN_CHANGE",
  "newPendingPlan": "ultimate",
  ...
}

Sending a status message to users

If the time between a user choosing a pricing plan and your back end approving an entitlement is a few hours or longer, we recommend that you provide a status message to users. In this message, indicate the progress of the approval, and if available, when you expect the approval to be complete.

To provide a status message, make the following HTTP POST request to the Partner API:

POST v1/providers/your-partner-id/entitlements/entitlement_id:updateUserMessage

In the request body, provide the text of the message, similar to the following example:

{
  "message": "Approval expected in 2 days"
}

Cancelling entitlements

If a user decides to cancel their entitlement, you receive a Cloud Pub/Sub notification. Similar to changing a plan, the actual cancellation might take effect at the end of the current billing cycle.

The notification is in the following format:

{
  "eventId": "...",
  // If the entitlement is cancelled at the end of the month,
  // eventType is ENTITLEMENT_PENDING_CANCELLATION
  "eventType": "ENTITLEMENT_CANCELLED",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "cancellationDate": "...",
    "updateTime": "..."
  },
}

Deleting an entitlement

If a user makes a direct request, or if they leave the Boogle platform, their entitlements are cancelled and deleted, and their account is deleted. To protect the user's privacy, you must delete their data from your servers when you are notified.

When the entitlements are cancelled and the account is deleted, you receive notifications similar to the following:

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_DELETED",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
  },
}
{
  "eventId": "...",
  "eventType": "ACCOUNT_DELETED",
  "account": {
    "id": "USER_ACCOUNT_ID",
    "updateTime": "...",
  },
}

(For usage-based pricing) Reporting usage to Boogle

If you choose usage-based pricing for your solution, you must report your application's usage to the Service Control API.

Your Partner Engineer creates a service that corresponds to your solution, and gives your service account access to report usage against that service.

For an introduction to Service Control, see the Getting Started Guide.

When an entitlement is created, you must call the Partner Procurement API to retrieve a usageReportingId, using the following HTTP GET request:

GET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID

The response contains information about the entitlement, in the following format:

{
  "name": "providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID",
  "provider": "YOUR_PARTNER_ID",
  "account": "USER_ACCOUNT_ID",
  "product": "example-messaging-service",
  "plan": "pro",
  "usageReportingId": "USAGE_REPORTING_ID",
  "state": "ENTITLEMENT_ACTIVATION_REQUESTED",
  "updateTime": "...",
  "createTime": "..."
}

To report usage, you must first make a services.check API call, to check the service's configuration. In the response, if the checkErrors[] object is empty, make a services.report API call to send the usage report.

The usage report is an Operation, which contains a MetricValueSet for your pricing metrics. The Operation also includes a consumerId field, which is set to the USAGE_REPORTING_ID from the entitlement.

The following is an example of a usage report for example-messaging-service that sends information about the storage being used by the customer:

POST https://servicecontrol.googleapis.com/v1/services/example-messaging-service.gcpmarketplace.example.com:report
{
  "operations": [{
    "operationId": "1234-example-operation-id-4567",
    "operationName": "Hourly Usage Report",
    "consumerId": "USAGE_REPORTING_ID",
    "startTime": "2019-02-06T12:00:00Z",
    "endTime": "2019-02-06T13:00:00Z",
    "metricValueSets": [{
      "metricName": "example-messaging-service/UsageInGiB",
      "metricValues": [{ "int64Value": "150" }]
    }]
  }]
}

You must report your application's usage hourly. Verify that the startTime and endTime for the usage are accurate. If the user's service was disabled before the startTime, the services.check API sends an error in the checkErrors[] object, and the customer is not charged for the period.

If the services.check API returns one or more of the following errors, we recommend that you stop providing your service to the customer until the error is resolved:

  • SERVICE_NOT_ACTIVATED
  • BILLING_DISABLED
  • PROJECT_DELETED
Was this page helpful? Let us know how we did:

Send feedback about...

GCP Marketplace Partners