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

The read-only `credit` attribute of the `Account` object holds the current credits available to the `Account`. Use the `grantCredit` and `revokeCredit` calls to manipulate credit. These methods generate appropriate audit trails of credit changes. Do not set the value of this attribute directly. (For example, when creating a new `Account` object by calling `update()`.)

**Note:** Use token-related methods such as `Account.incrementTokens()` or `decrementTokens\(\)` to manipulate tokens available to the `Account`. Subscribe can handle tokens both as payment methods outside the credit framework, and as part of the credit system.

Although you can use Tokens interchangeably across the two systems, Vindicia recommends that in your implementation, you choose one system, rather than mixing the two. If you have not previously implemented a token-as-payment-method system, choose credit-based token management, because the `Credit` object allows you to abstract the type of credit, and therefore offers more flexibility for future replacement.

## Granting Credit to an `Account`

If a customer performs a specific activity at your site, you may choose to give that customer credit. For example, if a customer redeems a phone card, a cell phone company may add a number of cell phone minutes to the customer’s account. You may also apply currency credits to the account. Use the Credit’s name-value pairs to define the reason for the Grant, and to provide another field by which your Credit activity may be analyzed.

Use `Account.grantCredit` to add credit to an Account:

```

$acct = new Account();
 
// account id for an existing customer
 
$acct->setMerchantAccountId('jdoe101');
$tok = new Token();
 
// specify the id of an existing token type.
// (the assumption here is that you have already created
// a Token object with this id.)
 
$tok->setMerchantTokenId('ANYTIME_PHONE_MINUTES_2010');
 
$tokAmt = new TokenAmount();
$tokAmt->setToken($tok);
$tokAmt->setAmount(100);
 
$cr = new Credit();
$cr->setTokenAmounts(array($tokAmt));
 
// make the SOAP API call to grant credit to the acct
$response = $acct->grantCredit($cr);
 
if ($response[’returnCode’] == 200) {
 
// Credit successfully granted to the account
 
$updatedAcct = $response->['account'];
$availableCredits = $updatedAcct->getCredit();
$availableTokens = $availableCredits->getTokenAmounts();
 
print "Available token credits: \n";
foreach($availableTokens as $tkAmt) {
print "Token type: " . $tkAmt->getMerchantTokenId() . " ";
print "Amount: " . $tkAmt->getAmount() . "\n";
}
}
else {
 
// Error while granting credit to the account
 
print $response['returnString'] . "\n";
}
```

**Note:** Subscribe does not allow you to grant time-based credit to an `Account` object.

## Revoking Credit from an `Account`

For some customer activities, you might revoke credit from the customer’s account. For example, if a customer uses airline frequent flier miles to book a flight, an airline company would deduct frequent flier miles from the customer’s account. If you accept currency credits, you may also deduct currency from the account.

Use `Account.revokeCredit` to deduct credit from an Account:

```

$acct = new Account();
 
// account id for an existing customer
 
$acct->setMerchantAccountId('ff_flier_101');
 
$tok = new Token();
 
// specify the id of an existing token type.
// (the assumption here is that you have already created
// a Token object with this id.)
 
$tok->setMerchantTokenId('UA_FF_MILES');
 
$tokAmt = new TokenAmount();
$tokAmt->setToken($tok);
$tokAmt->setAmount(25000);
 
$cr = new Credit();
$cr->setTokenAmounts(array($tokAmt));
 
// make the SOAP API call to deduct miles
$response = $acct->revokeCredit($cr);
 
if ($response[’returnCode’] == 200) {
 
// Credit successfully revoked from the account
 
$updatedAcct = $response->['account'];
$availableCredits = $updatedAcct->getCredit();
$availableTokens = $availableCredits->getTokenAmounts();
 
print "Available token credits: \n";
foreach($availableTokens as $tkAmt) {
print "Token type: " . $tkAmt->getMerchantTokenId() . " ";
print "Amount: " . $tkAmt->getAmount() . "\n";
}
}
else {
 
// Error while revoking credit from the account
print $response['returnString'] . "\n";
}
```

**Note:** If the amount of token-based credit to be revoked results in a negative balance, Subscribe sets the balance to 0.

## Using Credits for a One-Time Transaction

One-time transactions may use credit available to an `Account`. To use Credits for one-time transactions, make certain that the `Transaction` object includes a `PaymentMethod` that matches the currency or token type you wish to use to conduct the transaction. If the customer `Account` has enough credit to support the transaction, Subscribe authorizes the transaction, and adds a new `transaction` item to the `Transaction` object returned to you in response to your `authCapture()` call. This `transaction` item has its `sku` attribute set to `VIN_Credit`, and its `price` set to a negative value (equivalent to the amount of the transaction), signifying that Subscribe deducted the credit from the customer’s account.

**Note:** You can also have Subscribe process a one-time transaction that does not consume available currency credits. In the Transaction object, populate the name-value pair `vin:ignoreCredits = true` and the Transaction will charge against the payment method, using no currency credits.

Create a one-time credit transaction:

```

$acct = new Account();
 
// account id for an existing customer
 
$acct->setMerchantAccountId('jdoe101');
 
$tok = new Token();
 
// specify the id of an existing token type.
// (the assumption here is that the customer with
// account id 'jdoe101' has credit available in this
// type of token.)
 
$tok->setMerchantTokenId('ANYTIME_PHONE_MINUTES_2010');
 
// source payment method for the transaction should be
// a token-based payment method
$srcPm = new PaymentMethod();
$srcPm->setType('Token');
$srcPm->setToken($tok);
$srcPm->setMerchantPaymentMethodId('5933054820');
 
$txn = new Transaction();
$txn->setAccount($acct);
$txn->setSourcePaymentMethod($srcPm);
 
// This transaction will deduct 50 credit units from the account
$txn->setAmount(50);
 
$txn->merchantTransactionId('TK00234918'); // must be unique
 
// Add a transaction item describing the transaction detail
 
$txItem = new TransactionItem();
$txItem->setSku('MONTH50');
$txItem->setName('Monthly Anytime Minutes');
$txItem->setPrice(50);
$txItem->setQuantity(1);
 
// set the transaction item into the transaction
$txn->setTransactionItems(array($txItem);
 
$sendEmail = false;
 
// Make the SOAP call to authorize and capture the transaction
$response = $txn->authCapture($sendEmail);
 
if ($response[’returnCode’] == 200) {
 
// the SOAP call succeeded. Now check if the
// transaction was authorized
$retTxn = $response->['transaction'];
if($retTxn->statusLog[0]->status=='Authorized') { 
print "Transaction approved"; 
} 
else if($retTxn->statusLog[0]->status=='Cancelled') { 
print "Transaction not approved \n"; 
} 
else { 
print "Error: Unexpected transaction status\n"; 
}
}
else {
// Error while conducting transaction
print $response['returnString'] . "\n";
}
```

## Fetching `Account` Credit History

Subscribe maintains a log of credit-related events for each `Account`. This log keeps track of various credit-related events such as credit granted, revoked, consumed, or earned from a gift card redemption. Retrieve the audit log by calling the `Account` object’s `fetchCreditHistory()` method. The method includes paging and a time range, so you can limit the number of records returned. It returns an array of `CreditEventLog` objects. Each `CreditEventLog` object holds the `Credit` object, a timestamp, the type of activity performed with the `Credit` object, and a `note` text field.

Call `Account`.`fetchCreditHistory`:

```

$acct = new Account(); 
 
// account id for an existing customer whose
// credit history you want to retrieve
 
$acct->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 = 
$acct->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.