> ## 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.

# Using Credits with an AutoBill

The read-only `credit` attribute of the `AutoBill` object holds the array of Credit amount objects available to the AutoBill. Do not set this field directly by calling `AutoBill.update`. Instead, use `AutoBill` methods such as `grantCredit()` and `revokeCredit()` to alter credits available to the `AutoBill`, and provide an audit trail in the credit log. Currency-, time-, and token-based credits may be used with `AutoBill` objects. Subscribe manages credits available to an `AutoBill` object as follows:

* Subscribe draws currency- and token-based credits from the `AutoBill` for each periodic transaction it generates for the `AutoBill`.
* If the `Account` associated with the `AutoBill` also has currency- or token-based credits available to it, when the `AutoBill` is billed, `AutoBill` credits are redeemed before `Account` credits.
* If an `AutoBill` has an associated time credit, Subscribe uses this credit before redeeming any token-based or currency credits.
* Subscribe uses currency and token-based credit to process an `AutoBill`’s periodic transaction only if both of the following are true:
  * The payment method specified on the `AutoBill` is a currency or token-based payment method that specifies a type of applicable token.
  * The billing plan associated with the `AutoBill` has a price listed in terms of the same token type or currency.
* When Subscribe applies time-based credit to an `AutoBill`, it adjusts the next billing date of the `AutoBill` accordingly. For example, a 15-day credit will postpone an `AutoBill` object’s next billing date by 15 days. Application of such a credit does not generate a transaction.

## Granting Credit to an `AutoBill`

Some situations may require you to extend a customer’s subscription to your site. For example, if a technical problem at your site prevented a customer from accessing the site for two days, a customer service representative might decide to extend the customer’s subscription by two days, to guarantee customer satisfaction. The `grantCredit()` method of the `AutoBill` object allows you to add time credit to an `AutoBill` object to implement such an extension.

Use `grantCredit` to add time credit to an AutoBill:

```

$abill = new AutoBill();
 
// autobill id for an existing subscription
 
$abill->setMerchantAutoBillId('SBCR312345');
 
// We want to grant 2 days of credit
$time = new TimeInterval();
$time->setType('Day');
$time->setAmount(2);
 
$cr = new Credit();
$cr->setTimeIntervals(array($time));
 
// Now make the SOAP API call to grant credit to the autobill
$response = $abill->grantCredit($cr);
 
if ($response[’returnCode’] == 200) {
 
// Credit successfully granted to the autobill
 
$updatedABill = $response['data']->autobill;
 
print "Current entitlements are valid till: ";
print $updatedABill->getEndDate() . "\n";
}
else {
// Error while granting credit to the account
print $response['returnString'] . "\n";
}
```

## Revoking Credit from an `AutoBill`

Some activities a customer performs at your site might revoke credit from an `AutoBill` object. For example, an online game company might offer subscriptions that are paid for by points a customer earns in the game. If the customer loses some points in the game, the company might deduct the same number of points from the customer’s subscription. (Note: Time-based credit granted to an `AutoBill` cannot be revoked.)

Use `revokeCredit` to revoke currency or Token-based credits from an AutoBill:

```

$abill = new AutoBill();
 
// autobill id for customer's existing subscription to a game
 
$abill->setMerchantAutoBillId('STARWARS-239181');
 
$tok = new Token();
 
// specify the id of an existing token type.
// the autobill has a payment method defined in terms of this
// token type. Also the billing plan used by the autobill 
// specifies a price in terms of this token type.
 
$tok->setMerchantTokenId('STARWARS_POINTS');
 
$tokAmt = new TokenAmount();
$tokAmt->setToken($tok);
$tokAmt->setAmount(100); // customer lost 100 points in the game
 
$cr = new Credit();
$cr->setTokenAmounts(array($tokAmt));
 
// Now make the SOAP API call to deduct points from customer's
// subscription
 
$response = $abill->revokeCredit($cr);
 
if ($response[’returnCode’] == 200) {
 
// Credit successfully revoked from the autobill
 
$updatedAbill = $response->['data']->autobill;
$availableCredits = $updatedAbill->getCredit();
$availableTokens = $availableCredits->getTokenAmounts();
 
print "Available points to subscription: \n";
foreach($availableTokens as $tkAmt) {
print "Token type: " . $tkAmt->getMerchantTokenId() . " ";
print "Amount: " . $tkAmt->getAmount() . "\n";
}
}
else {
// Error while revoking credit from the autobill
print $response['returnString'] . "\n";
}
```

If the amount of currency or token-based credit to be revoked results in a negative balance, Subscribe sets the balance to 0. Disentitlement (loss of customer access to the product) will occur when Subscribe attempts to process the next billing transaction for the `AutoBill`, and the transaction fails due to insufficient credit.

## Fetching AutoBill Credit Transactions

Subscribe stores token- and currency-based periodic transactions in the same way that it stores `AutoBill` paid for with currency payment methods. Fetch token-based transactions with API calls such as the `Transaction` object’s `fetchByAutoBill()` method. These transactions contain a `Transaction` item with `sku` attribute set to `VIN_Credit`, and `price` attribute set to a negative value equivalent to the amount of the transaction (signifying that Subscribe deducted the credit).

## Fetching `AutoBill` Credit History

Subscribe maintains a log of credit-related events for each `AutoBill` object. This log tracks credit-related events such as credit granted, revoked, consumed, and earned due to a gift card redemption. Retrieve the audit log with the `AutoBill` object’s `fetchCreditHistory()` method. (Because the method includes paging and a time range, you may limit the number of records returned.)

`fetchCreditHistory()` returns an array of `CreditEventLog` objects. Each `CreditEventLog` object holds the `Credit` object used for that specific event, a timestamp, the type of activity performed with the `Credit` object, and a text `note` field.

Use `fetchCreditHistory` to return an array of `CreditEventLog` objects:

```

$abill = new AutoBill(); 
 
// autobill id for an existing customer whose
// credit history you wish to retrieve
 
$abill->setMerchantAccountId('jdoe101');
 
$page = 0; // paging begins at 0
$pageSize = 5; // five records 
$startTime = '2010-01-01T22:34:32.265Z'; 
$endTime = '2010-01-30T22:34:32.265Z'; 
 
do { 
$ret = 
$abill->fetchCreditHistory($startTime, $endTime $page, $pageSize); 
$count = 0; 
if ($ret[’returnCode’] == 200) { 
$fetchedLogs = $ret['creditEventLogs']; 
$count = sizeof($fetchedLogs); 
foreach ($fetchedLogs as $log) { 
$credit = $log->getCredit();
$ts = $log->getTimeStamp();
$eventType = $log->getType();
// process retrieved credit event log
// details here.
} 
$page++; 
} 
} while ($count > 0);
```

**Parent topic:**[Working with Credit](../topics/Working_with_Credit)


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