# Credits API



Credits are added to the system to as desired to credit customer accounts.

<Callout>
  Currently the only credits supported (other than payments and credit distributions) are write-offs to resolve invoice payment shortfalls within the tolerance threshold.
</Callout>

<EndpointIndex
  names={[
  	'fetchCredits',
  	'fetchShortfallCredit',
  	'fetchMultipleShortfallCredits',
  ]}
/>

Fetch Credits [#fetch-credits]

<ApiEndpoint name="fetchCredits" />

<ApiSchema name="CreditListResponse" />

<ApiSchema name="CreditResponse" />

Fetch Shortfall Credit [#fetch-shortfall-credit]

<ApiEndpoint name="fetchShortfallCredit" />

<ApiSchema name="ShortfallCreditListResponse" />

<ApiSchema name="ShortfallCreditResponse" />

Fetch Multiple Shortfall Credits [#fetch-multiple-shortfall-credits]

<ApiEndpoint name="fetchMultipleShortfallCredits" />

Fetch Credits For An Invoice [#fetch-credits-for-an-invoice]

<ApiEndpoint name="fetchCreditsForAnInvoice" />


## API Reference

GET /billing/{tenantLocator}/credits/list — fetchCredits
Tags: credits-controller
Permissions: read, list
Parameters:
  tenantLocator (uuid, path, required)
  accountLocator (ulid, query)
  offset (integer, query)
  count (integer, query)
  extended (boolean, query)
Responses:
  200 CreditListResponse — OK

GET /billing/{tenantLocator}/shortfallCredits/{locator} — fetchShortfallCredit
Tags: shortfall-credits-controller
Permissions: read
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 ShortfallCreditResponse — OK

GET /billing/{tenantLocator}/shortfallCredits/list — fetchMultipleShortfallCredits
Tags: shortfall-credits-controller
Permissions: read, list
Parameters:
  tenantLocator (uuid, path, required)
  offset (integer, query)
  count (integer, query)
  accountLocator (ulid, query)
  extended (boolean, query)
Responses:
  200 ShortfallCreditListResponse — OK

GET /billing/{tenantLocator}/invoices/{locator}/credits/list — fetchCreditsForAnInvoice
Tags: invoices-controller
Permissions: read, list
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
  includeReversed (boolean, query)
  offset (integer, query)
  count (integer, query)
  extended (boolean, query)
Responses:
  200 CreditListResponse — OK

CreditListResponse
Properties:
  listCompleted (boolean, required)
  items (CreditResponse[], required)

CreditResponse
Properties:
  locator (ulid, required)
  creditState (Enum discarded | draft | posted | reversed | validated | executed | distributed | approved | rejected | requested | executing | failed | cancelled, required)
  creditType (Enum creditDistribution | disbursement | payment | subpayment | shortfallWriteOff | writeOff, required)
  currency (string, required)
  amount (number, required)
  createdAt (datetime, required)
  accountLocator (ulid)
  realizedAt (datetime)
  reversedAt (datetime)
  reversalReason (string)

ShortfallCreditListResponse
Properties:
  listCompleted (boolean, required)
  items (ShortfallCreditResponse[], required)

ShortfallCreditResponse
Properties:
  locator (ulid, required)
  creditType (Enum creditDistribution | disbursement | payment | subpayment | shortfallWriteOff | writeOff, required)
  shortfallCreditState (Enum draft | distributed | reversed, required)
  currency (string, required)
  amount (number, required)
  createdAt (datetime, required)
  createdBy (uuid, required)
  accountLocator (ulid, required)
  targets (CreditItem[], required)
  parentCreditLocator (ulid, required)
  reversalReason (string)