> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slm.m1amdocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Entitlement.fetchByAccount

The `fetchByAccount` method returns one or more `Entitlement` objects associated with the specified `Account` object. These `Entitlement`s 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](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](../topics/Entitlement_Methods)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.