REST Resource: accounts.customers.entitlements

Resource: Entitlement

An entitlement is a representation of a customer's ability to use a service.

JSON representation
{
  "name": string,
  "createTime": string,
  "updateTime": string,
  "offer": string,
  "commitmentSettings": {
    object (CommitmentSettings)
  },
  "provisioningState": enum (ProvisioningState),
  "provisionedService": {
    object (ProvisionedService)
  },
  "suspensionReasons": [
    enum (SuspensionReason)
  ],
  "purchaseOrderId": string,
  "trialSettings": {
    object (TrialSettings)
  },
  "associationInfo": {
    object (AssociationInfo)
  },
  "parameters": [
    {
      object (Parameter)
    }
  ]
}
Fields
name

string

Output only. Resource name of an entitlement in the form: accounts/{account_id}/customers/{customer_id}/entitlements/{entitlement_id}.

createTime

string (Timestamp format)

Output only. The time at which the entitlement is created.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

updateTime

string (Timestamp format)

Output only. The time at which the entitlement is updated.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

offer

string

Required. The offer resource name for which the entitlement is to be created. Takes the form: accounts/{account_id}/offers/{offer_id}.

commitmentSettings

object (CommitmentSettings)

Commitment settings for a commitment-based Offer. Required for commitment based offers.

provisioningState

enum (ProvisioningState)

Output only. Current provisioning state of the entitlement.

provisionedService

object (ProvisionedService)

Output only. Service provisioning details for the entitlement.

suspensionReasons[]

enum (SuspensionReason)

Output only. Enumerable of all current suspension reasons for an entitlement.

purchaseOrderId

string

Optional. This purchase order (PO) information is for resellers to use for their company tracking usage. If a purchaseOrderId value is given, it appears in the API responses and shows up in the invoice. The property accepts up to 80 plain text characters.

trialSettings

object (TrialSettings)

Output only. Settings for trial offers.

associationInfo

object (AssociationInfo)

Association information to other entitlements.

parameters[]

object (Parameter)

Extended entitlement parameters. When creating an entitlement, valid parameters' names and values are defined in the offer's parameter definitions.

CommitmentSettings

Commitment settings for commitment-based offers.

JSON representation
{
  "startTime": string,
  "endTime": string,
  "renewalSettings": {
    object (RenewalSettings)
  }
}
Fields
startTime

string (Timestamp format)

Output only. Commitment start timestamp.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

endTime

string (Timestamp format)

Output only. Commitment end timestamp.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

renewalSettings

object (RenewalSettings)

Optional. Renewal settings applicable for a commitment-based Offer.

RenewalSettings

Renewal settings for renewable Offers.

JSON representation
{
  "enableRenewal": boolean,
  "resizeUnitCount": boolean,
  "paymentPlan": enum (PaymentPlan),
  "paymentCycle": {
    object (Period)
  }
}
Fields
enableRenewal

boolean

If false, the plan will be completed at the end date.

resizeUnitCount

boolean

If true and enableRenewal = true, the unit (for example seats or licenses) will be set to the number of active units at renewal time.

paymentPlan

enum (PaymentPlan)

Describes how a reseller will be billed.

paymentCycle

object (Period)

Describes how frequently the reseller will be billed, such as once per month.

PaymentPlan

Describes how the reseller will be billed.

Enums
PAYMENT_PLAN_UNSPECIFIED Not used.
COMMITMENT Commitment.
FLEXIBLE No commitment.
FREE Free.
TRIAL Trial.
OFFLINE Price and ordering not available through API.

Period

Represents period in days/months/years.

JSON representation
{
  "duration": integer,
  "periodType": enum (PeriodType)
}
Fields
duration

integer

Total duration of Period Type defined.

periodType

enum (PeriodType)

Period Type.

PeriodType

Period Type.

Enums
PERIOD_TYPE_UNSPECIFIED Not used.
DAY Day.
MONTH Month.
YEAR Year.

ProvisioningState

Indicates the current provisioning state of the entitlement.

Enums
PROVISIONING_STATE_UNSPECIFIED Default value. This state doesn't show unless an error occurs.
ACTIVE The entitlement is currently active.
SUSPENDED The entitlement is currently suspended.

ProvisionedService

Service provisioned for an entitlement.

JSON representation
{
  "provisioningId": string,
  "productId": string,
  "skuId": string
}
Fields
provisioningId

string

Output only. Provisioning ID of the entitlement. For Google Workspace, this would be the underlying Subscription ID.

productId

string

Output only. The product pertaining to the provisioning resource as specified in the Offer.

skuId

string

Output only. The SKU pertaining to the provisioning resource as specified in the Offer.

SuspensionReason

Suspension reason for an entitlement if provisioningState = SUSPENDED.

Enums
SUSPENSION_REASON_UNSPECIFIED Default value. This state doesn't show unless an error occurs.
RESELLER_INITIATED Entitlement was manually suspended by the Reseller.
TRIAL_ENDED Trial ended.
RENEWAL_WITH_TYPE_CANCEL Entitlement renewal was canceled.
PENDING_TOS_ACCEPTANCE Entitlement was automatically suspended on creation for pending ToS acceptance on customer.
OTHER Other reasons (internal reasons, abuse, etc.).

TrialSettings

Settings for trial offers.

JSON representation
{
  "trial": boolean,
  "endTime": string
}
Fields
trial

boolean

Determines if the entitlement is in a trial or not:

  • true - The entitlement is in trial.
  • false - The entitlement is not in trial.
endTime

string (Timestamp format)

Date when the trial ends. The value is in milliseconds using the UNIX Epoch format. See an example Epoch converter.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

AssociationInfo

Association links that an entitlement has to other entitlements.

JSON representation
{
  "baseEntitlement": string
}
Fields
baseEntitlement

string

The name of the base entitlement, for which this entitlement is an add-on.

Parameter

Definition for extended entitlement parameters.

JSON representation
{
  "name": string,
  "value": {
    object (Value)
  },
  "editable": boolean
}
Fields
name

string

Name of the parameter.

value

object (Value)

Value of the parameter.

editable

boolean

Output only. Specifies whether this parameter is allowed to be changed. For example, for a Google Workspace Business Starter entitlement in commitment plan, num_units is editable when entitlement is active.

Value

Data type and value of a parameter.

JSON representation
{

  // Union field kind can be only one of the following:
  "int64Value": string,
  "stringValue": string,
  "doubleValue": number,
  "protoValue": {
    "@type": string,
    field1: ...,
    ...
  },
  "boolValue": boolean
  // End of list of possible types for union field kind.
}
Fields
Union field kind. The kind of value. kind can be only one of the following:
int64Value

string (int64 format)

Represents an int64 value.

stringValue

string

Represents a string value.

doubleValue

number

Represents a double value.

protoValue

object

Represents an 'Any' proto value.

An object containing fields of an arbitrary type. An additional field "@type" contains a URI identifying the type. Example: { "id": 1234, "@type": "types.example.com/standard/id" }.

boolValue

boolean

Represents a boolean value.

Methods

activate

Activates a previously suspended entitlement.

cancel

Cancels a previously fulfilled entitlement.

changeOffer

Updates the Offer for an existing customer entitlement.

changeParameters

Change parameters of the entitlement.

changeRenewalSettings

Updates the renewal settings for an existing customer entitlement.

create

Creates an entitlement for a customer.

get

Returns the requested Entitlement resource.

list

Lists Entitlements belonging to a customer.

lookupOffer

Returns the requested Offer resource.

startPaidService

Starts paid service for a trial entitlement.

suspend

Suspends a previously fulfilled entitlement.