Skip to main content
Vindicia Knowledge Center

Entitlement.fetchDeltaSince

Entitlement.fetchDeltaSince

Entitlement.fetchDeltaSince

The fetchDeltaSince call returns all the Entitlement objects that have changed since the specified time stamp. The change could be in the active status of an Entitlement, or in its endTimestamp if the entitlement is still active.

The purpose of this call differs from that of fetchByAccount() and fetchByEntitlementIdAndAccount(), which are used to look up the entitlements for a customer while they request access to a resource on your site. (fetchByAccount() and fetchByEntitlementIdAndAccount() often require that you make a request to the Vindicia servers during the customer’s active session.)

To avoid making such a heavyweight call during a customer session, and to improve user experience, maintain a local cache of Entitlements in a table similar to the one shown in the Entitlement.fetchByAccount method for a faster lookup. Update that table periodically, or at a system quiescent time for all your customers by calling fetchDeltaSince().

Entitlements for an Account object may change for one of the following reasons:

  • Your customer failed to pay their bill, and your grace period has been exhausted.
  • You have created a new AutoBill object for an Account object.
  • A cancellation for an AutoBill object with immediate disentitlement has occurred because either:
    • you have called AutoBill.cancel() or Account.stopAutoBilling() and set the flag for immediate disentitlement, or
    • Vindicia has received a chargeback from your payment processor against one of the transactions generated by the AutoBill object, and your profile configuration with Vindicia specifies that the customer be immediately disentitled in case of chargebacks.
  • You have added or deleted entitlement IDs (merchantEntitlementIds) from a Product or BillingPlan object associated with an active AutoBill object.
  • CashBox has postponed the end-date on an AutoBill object, as a result of a call that you made to delay the billing. See the delayBillingByDays() and delayBillingToDate() calls for AutoBill.

CashBox maintains a log of each event that can deactivate or extend an entitlement for all AutoBill and associated Account objects. When you call fetchDeltaSince(), CashBox constructs an Entitlement object from each log entry that has been added since the time stamp specified in the input, and includes it in the results returned to you. Thus, if an entitlement for a customer is changed several times during the fetchDeltaSince period, an Entitlement object that contains the same Account and Entitlement ID is in the result set for each of those changes. Because this method returns Entitlement objects in ascending order of the time when the log entries were made, in most cases you can determine the latest status of a customer’s entitlement from the last Entitlement object with that ID in the result set. (In some cases, additional sorting logic is required to determine the active Entitlement with the latest end date.)

If you are using a database table, as described in the Entitlement.fetchByAccount method, to check the entitlements for a customer (for example, Jdoe1970), first check if entries exist in the table for Jdoe1970 and then follow these steps in your application logic:

  • If entries exist, check if one exists in the table for the entitlement ID you wish to look up. If it exists, and if the active_till date is today or in the future, allow Jdoe1970 access. If the active_till date is in the past or is null, or if a row with the entitlement ID in question does not exist for Jdoe1970Jdoe1970 does not have access to the resources with that entitlement ID.
  • If no entries exist, call fetchByAccount() for Jdoe1970 and add the entries to the entitlement cache table with the data in the Entitlement objects returned. Next, check the entry for the entitlement ID you need to look up for Jdoe1970 and the active_till date. If that date is in the future, grant Jdoe1970 access. If no entry exists or if the active_till date is null or in the past, Jdoe1970 does not have that specific entitlement.

The fetchDeltaSince method supports paging to limit the number of records returned per call. Returning a large number of records in one call may swamp buffers and might cause a failure. Vindicia recommends that you call this method in a loop, incrementing the page for each loop iteration with an optimal page size (number of records returned in one call) until the page contains a number of records that is less than the given page size.

Input

srd: sparse response description, a SOAP string (which must be a JSON object), in which you specify the elements you want returned.This parameter enables the calling system to constrain a method call to return only components you specify. This gives you greater control over returned content, and improves response time within the Vindicia platform by reducing the processing needed for the call.

Some fields are required, either practically or in the WSDL, and will be returned regardless of the srd. A null srd returns the complete response.

timestamp: the date and time after which to return the Entitlement objects that have changed.

page: the page number, starting at 0, for which to return the results. For example, if the total number of results is 85 and pageSize is 10:

  • Specifying 0 for page gets the results from 1 through 10.
  • Specifying 2 for page gets the results from 21 through 30.

pageSize: the number of records to display per page per call. This value must be greater than 0.

endTimestamp: the time window’s upper threshold by which to limit the search. If unspecified, this value defaults to the current time.

Output

return: an object of type Return that indicates the success or failure of the call.

entitlements: an array of one or more Entitlement objects that have changed since timestamp.

Returns

In addition to those listed in Standard Return Codes, this call returns:

Return Code

Return String

400

Invalid value or values of timestamp, and/or page, and/or page size.

Example

$ent = new Entitlement();
$pg = 0;
$pageSize = 200;
$count = 0;
$endTimestamp = '2010-01-02T22:34:32.265Z';
$startTimestamp = '2010-01-01T22:34:32.265Z';

do {

$ret = $ent->fetchDeltaSince($startTimestamp, $pg, $pageSize, $endTimestamp);
$fetchedEnts = $ret['entitlements'];
$count = 0;
if ($fetchedEnts != null) {

$count = count($fetchedEnts);
foreach ($fetchedEnts as $ent) {

$customer_id = $ent->getAccount()->getMerchantAccountId();
$entitlement_id = $ent->getMerchantEntitlementId();
$active = $ent->getActive();
if($active == 1) {
$valid_till = $ent->endTimestamp();
}

// cache the data to your local database table here

}
$pg++;

}

} while ($count > 0);

For Users

Learn More
For Users

Cashbox Features

Learn More
Cashbox Features
Back to Top