When a customer purchases a [private offer](https://docs.cloud.google.com/marketplace/docs/partners/offers.md.txt),
Google creates an *entitlement*, which indicates that the customer has bought
the offer from Cloud Marketplace.

This document reviews how to manage entitlements for your private offers by
using Producer Portal and the Partner Procurement API. You can use
Producer Portal or the Partner Procurement API to approve
offer entitlements. For other offer entitlement management tasks, you must use
the Partner Procurement API.

> [!CAUTION]
> **Caution:** If you've turned on [automatic offer approval](https://docs.cloud.google.com/marketplace/docs/partners/offers/automatic-approval.md.txt) for your software as a service (SaaS) product, you receive different Pub/Sub messages from those described in this document. You should instead refer to [Manage entitlements for private offers with automatic offer approval](https://docs.cloud.google.com/marketplace/docs/partners/offers/manage-entitlements-automatic-approval.md.txt).

## Approve entitlements by using Producer Portal

You can use Producer Portal to approve entitlements for private
offers that have the
[status](https://docs.cloud.google.com/marketplace/docs/partners/offers/view-offer-status.md.txt) **Needs your
approval**. To approve an entitlement, complete the following steps:

1. In Producer Portal, go to the **Private Offers** page.

2. For the offer that you want to approve, click **Manage your offers**
   , and then click **Approve**.

3. In the **Approve offer** dialog, select the **I have done everything I need
   to do on my end for this customer to use my product** checkbox, and then
   click **Approve**.

   > [!NOTE]
   > **Note:** If you aren't able to approve the entitlement by using Producer Portal, verify that you've [approved the customer's account resource](https://docs.cloud.google.com/marketplace/docs/partners/offers/manage-accounts.md.txt).

## Manage entitlements by using the Partner Procurement API

The following sections describe how to manage entitlements for private offers by
using the Partner Procurement API.

For details on using the Partner Procurement API for private offers, visit
the [reference documentation](https://docs.cloud.google.com/marketplace/docs/partners/offers/rest-resources).

### Approve an entitlement

When a customer purchases a private offer, Cloud Marketplace creates an
entitlement and sends the following Pub/Sub message to your product:

```json
{
  "eventId": "...",
  "eventType": "ENTITLEMENT_CREATION_REQUESTED",
  "entitlement": {
  "id": "ENTITLEMENT_ID",
  "updateTime": "...",
  "newPendingOfferDuration": "P1Y6M", // Contract duration for the offer
  "newOfferEndTime": "", // Ending time for the offer
  },
}
```

In this example, <var translate="no">ENTITLEMENT_ID</var> 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 is empty. If the offer was
created with a specified ending time, the message displays the offer's end
time, and the `newPendingOfferDuration` field is empty.

In your system, update the user's account to reflect that they've purchased the
offer. Then, to approve the entitlement, make an `HTTP POST` request to the
Partner Procurement API, and send the <var translate="no">ENTITLEMENT_ID</var> that you're
approving:

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

> [!CAUTION]
> **Caution:** If you don't approve your customer's entitlement before the scheduled start date of their offer, that offer is automatically rejected, for both new offers and amendments to existing offers.

### Reject an entitlement

To reject an entitlement, 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:

```json
{
  "eventId": "...",
  "eventType": "ENTITLEMENT_PLAN_CHANGE_REQUESTED",
  "entitlement": {
  "id": "ENTITLEMENT_ID",
  "newPendingPlan": "ultimate",   // New plan for the offer,
  "newPendingOffer": "OFFER2",    // New offer,
  "updateTime": "...",
  "newPendingOfferDuration": "P2Y",   // Contract duration for the new offer
  },
}
```

In this example, <var translate="no">OFFER2</var> is the replacement offer and
<var translate="no">ENTITLEMENT_ID</var> 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:

```json
{
  "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:

```json
{
  "name": "providers/PARTNER_ID/entitlements/ENTITLEMENT_ID",
  "provider": "PARTNER_ID",
  "account": "USER_ACCOUNT_ID",
  "product": "example-server",
  "Offer":   "OFFER1",
  "plan": "pro",
  "state": "ENTITLEMENT_PENDING_PLAN_CHANGE",
  "newPendingOffer": "OFFER2",
  "newPendingPlan": "ultimate",
  "newPendingOfferDuration": "P2Y",
  "newOfferEndTime": "",
  ...
}
```

### Complete other entitlement tasks

For other entitlement tasks that aren't specific to private offers, refer to the
Cloud Marketplace public documentation:

- [Cancel an entitlement](https://docs.cloud.google.com/marketplace/docs/partners/integrated-saas/manage-entitlements.md.txt#cancel_an_entitlement)
- [Delete an entitlement](https://docs.cloud.google.com/marketplace/docs/partners/integrated-saas/manage-entitlements.md.txt#delete_an_entitlement)

## List of event types for private offer account tasks

The following table includes `eventType`s that your product might receive in
Pub/Sub messages for private offers.

For the full list, see
[List of event types for account tasks](https://docs.cloud.google.com/marketplace/docs/partners/integrated-saas/manage-entitlements.md.txt#eventtypes).

| 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. |

## What's next

- [Create a private offer](https://docs.cloud.google.com/marketplace/docs/partners/offers/create-private-offers.md.txt) for a specific customer.