Manage user accounts for your SaaS product

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

A user makes a request or change in Cloud Marketplace, such as signing up for your product.
Cloud Marketplace sends your app a notification through Pub/Sub, containing information about the request in the eventType field. For example, if a user changes their entitlement, the eventType is ENTITLEMENT_PLAN_CHANGED.

See the full list of possible eventTypes.
To approve the request, your app 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 app must do to handle the requests.

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

https://cloudcommerceprocurement.googleapis.com/

Before you begin

Set up access to the Cloud Commerce Partner Procurement API, as described in Integrate your app.

Create an account for a new user

When a user first purchases your product, Cloud Marketplace creates an account resource that tracks the user's relationship with you. For subsequent purchases against products owned by you, same account resource will be reused. Whenever a user makes their first purchase of any of your products, if you've turned on account notifications for that product, then you're notified through the Pub/Sub topic created for you. The Pub/Sub message is in the following format:

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

where USER_ACCOUNT_ID is the account ID created by Cloud Marketplace and YOUR_PARTNER_ID is an ID assigned to you when your Partner Engineer enables access to the Partner Procurement API.

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 app's frontend.

Approve a user's account

After the user has successfully signed up, your app must call the Partner Procurement 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'}

Check the status of a user's account

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

For a list of possible account states, see the providers.accounts API reference.

Manage customer entitlements