Entitlement.fetchByAccount

The fetchByAccount method returns one or more Entitlement objects associated with the specified Account object. These Entitlements may be associated through an AutoBill, or directly with the Account. Use this method to look up entitlements for a specific customer. Use the frequency of customer access, to determine how often to make this call. For example, if a customer on a monthly Billing Plan logs into your service several times each day, it’s unnecessary and inefficient to make a call to Subscribe to look up their entitlements for every login. Instead, cache the entitlements obtained from this call locally. The Entitlement objects with the active flag set to true thus obtained and locally stored can be considered valid until the endTimestamp date. You may cache Entitlement objects locally on your site with the database table shown below. Here, the columns customer_id and entitlement_id form a joint primary key.

customer_id	entitlement_id	Last Update	Active Till …
`Jdoe1970`	`GoldAccessLevel1`	`2009-09-18`	`2009-10-13`
`Jdoe1970`	`VideoDownloadSpecial`	`2009-09-18`	`null`
`Jdoe1970`	`LiveTechSupport`	`2009-08-23`	`2009-09-01`

For example, to check the entitlements for customer Jdoe1970, check if entries exist in the table for Jdoe1970 and then follow these steps in your application logic:

If entries exist, check if an entry exists in the table for the entitlement ID you need. If yes and if the active_till date is today or in the future, allow Jdoe1970 access. If the active_till date is in the past, call fetchByAccount() or fetchByEntitlementIdAndAccount() and specify the related entitlement ID (entitlement_id). Afterwards, update the Jdoe1970 table entries with the data in the Entitlement. objects returned, and check the active_till date again. If it is not null and is in the future, allow Jdoe1970 access.
If no entries exist, call fetchByAccount() and add entries to the entitlement cache table with the data in the Entitlement. objects returned. Next, check the entry for the entitlement ID you need 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.

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. account: the Account object for which to retrieve entitlements. Use the merchantAccountId or VID to identify the object. showAll: a Boolean flag that, if set to true, causes fetchByAccount to return all the Entitlement. objects, including those that have expired. Otherwise, fetchByAccount returns only the active Entitlement. objects. includeChildren: a Boolean flag that, if set to true, includes any children associated with this Account. If this flag is omitted, Subscribe will interpret it as false, and constructs the query without looking at any child’s account.

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 whose Account object matches the input.

Returns

In addition to those listed in The Return Object, this call returns:

Return Code	Return String
`404`	`Account not found.`

Example

$account = new Account();
$acctId = 'xyz101';
$account->setMerchantAccountId($acctId);

// create the entitlement object to make the SOAP call
$entitlement = new Entitlement();
$showAll = true; 

// fetch the records
$response = $entitlement->fetchByAccount($account, $showAll);
if ($response['returnCode'] == 200) {
    $fetchedEnts = $response['data']->entitlements;
    if ($fetchedEnts != null){
        foreach ($fetchedEnts as $ent) {
            $customer_id = $ent->getAccount()->getMerchantAccountId();
            $entitlement_id = $ent->getMerchantEntitlementId();
            $active = $ent->getActive();
            $active_till = null;
            if ($active) {
            $active_till = $ent->getEndTimestamp();
            }
            // use or locally store info obtained above
        }
    }
}

Parent topic:Entitlement Methods

Home

Guides

APIs

Input

Output

Returns

Example

​Input

​Output

​Returns

​Example

Input

Output

Returns

Example