Skip to main content
An entitlement is the customer’s right to access a product, as defined by their contractual agreement with a merchant. An Entitlement object (associated with an Account object) specifies whether a customer has the appropriate entitlement when the object is retrieved from the Subscribe database. This object allows you to determine whether a customer can access a specific resource on your site at any given time. Subscribe uses several pieces of information to determine the content of an Entitlement object:
  • The merchantEntitlementId, (the Entitlement Identifier), which is defined when creating new Entitlements for Products or Billing Plans.
    • When creating Entitlements, use the merchantEntitlementId(the Entitlement Identifier) field to describe the entitlement conveyed. For example, to allow customers access to a Gold-Level subscription, create an Entitlement with merchantEntitlementId: GoldAccess.
    • When creating Product and BillingPlan objects, specify the appropriate merchantEntitlementId in the object definition. Note: Use of the forward slash character (/) in identifiers is not allowed. See Merchant Identifiers for more information.
  • Subscribe calculates the endTimestamp of an Entitlement based on the AutoBill’s Billing Plan. Until a payment attempt fails, or the AutoBill is stopped for any other reason, Subscribe will assume that payments will continue to be made for the duration of the Billing Plan, and sets the Entitlement’s endTimestamp according to its parameters. If the Billing Plan has a finite number of Billing Periods, the endTimestamp will be the termination date for the Billing Plan. If the Billing Plan has an infinite number of Billing Periods, the endTimestamp is null.
  • The active flag on the Entitlement object defines whether the related entitlement is valid on the date you received the object from Vindicia. If the flag’s value is true, this means that when Subscribe constructed the Entitlement object, the customer was entitled to the access the object represents. To determine the duration, check the endTimestamp date.
  • The account attribute of an Entitlement object specifies the customer to whom the object applies.
Subscribe automatically grants entitlements upon successful creation of an AutoBill, and changes the end date only upon a payment failure or customer cancellation. Note: If you are upgrading from Subscribe 4.1 or previous, you must contact Vindicia Client Services to enable a merchant configuration setting which will allow Entitlements to work properly for Subscribe 4.2 and greater.