# Credit Distribution API



Credit Distributions are used to apply customer credits from a Credit Balance to invoices or for disbursements.

<EndpointIndex
  names={[
  	'fetchCreditDistribution',
  	'fetchCreditDistributionsForAnInvoice',
  	'fetchMultipleCreditDistributions',
  	'createCreditDistribution',
  	'updateCreditDistribution',
  	'createOrReplaceCreditDistribution',
  	'validateCreditDistribution',
  	'executeCreditDistribution',
  	'reverseCreditDistribution',
  	'resetCreditDistribution',
  	'discardCreditDistribution',
  	'fetchInvoicesTargetedByACreditDistribution',
  ]}
/>

Fetch [#fetch]

Fetch Credit Distribution [#fetch-credit-distribution]

<ApiEndpoint name="fetchCreditDistribution" />

Fetch Credit Distributions For An Invoice [#fetch-credit-distributions-for-an-invoice]

<ApiEndpoint name="fetchCreditDistributionsForAnInvoice" />

Fetch Multiple Credit Distributions [#fetch-multiple-credit-distributions]

<ApiEndpoint name="fetchMultipleCreditDistributions" />

<ApiSchema name="CreditDistributionListResponse" />

<ApiSchema name="CreditDistributionResponse" />

Creation and Update [#creation-and-update]

Create Credit Distribution [#create-credit-distribution]

<ApiEndpoint name="createCreditDistribution" />

<ApiSchema name="CreditDistributionCreateRequest" />

Update Credit Distribution [#update-credit-distribution]

<ApiEndpoint name="updateCreditDistribution" />

<ApiSchema name="CreditDistributionUpdateRequest" />

Create Or Replace Credit Distribution [#create-or-replace-credit-distribution]

<ApiEndpoint name="createOrReplaceCreditDistribution" />

<ApiSchema name="CreditDistributionPutRequest" />

Execution [#execution]

Validate Credit Distribution [#validate-credit-distribution]

<ApiEndpoint name="validateCreditDistribution" />

Execute Credit Distribution [#execute-credit-distribution]

<ApiEndpoint name="executeCreditDistribution" />

Reversal [#reversal]

Reverse Credit Distribution [#reverse-credit-distribution]

<ApiEndpoint name="reverseCreditDistribution" />

<ApiSchema name="CreditDistributionReverseRequest" />

Reset and Discard [#reset-and-discard]

Reset Credit Distribution [#reset-credit-distribution]

<ApiEndpoint name="resetCreditDistribution" />

Discard Credit Distribution [#discard-credit-distribution]

<ApiEndpoint name="discardCreditDistribution" />

Invoices [#invoices]

Fetch Invoices Targeted By ACredit Distribution [#fetch-invoices-targeted-by-acredit-distribution]

<ApiEndpoint name="fetchInvoicesTargetedByACreditDistribution" />


## API Reference

GET /billing/{tenantLocator}/creditDistributions/{locator} — fetchCreditDistribution
Tags: credit-distributions-controller
Permissions: read
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 CreditDistributionResponse — OK

GET /billing/{tenantLocator}/invoices/{locator}/creditDistributions/list — fetchCreditDistributionsForAnInvoice
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 CreditDistributionListResponse — OK

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

POST /billing/{tenantLocator}/creditDistributions — createCreditDistribution
Tags: credit-distributions-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
Request body (CreditDistributionCreateRequest):
Responses:
  200 CreditDistributionResponse — OK

PATCH /billing/{tenantLocator}/creditDistributions/{locator} — updateCreditDistribution
Tags: credit-distributions-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Request body (CreditDistributionUpdateRequest):
Responses:
  200 CreditDistributionResponse — OK

PUT /billing/{tenantLocator}/creditDistributions/{locator} — createOrReplaceCreditDistribution
Tags: credit-distributions-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Request body (CreditDistributionPutRequest):
Responses:
  200 CreditDistributionResponse — OK

PATCH /billing/{tenantLocator}/creditDistributions/{locator}/validate — validateCreditDistribution
Tags: credit-distributions-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 CreditDistributionResponse — OK

PATCH /billing/{tenantLocator}/creditDistributions/{locator}/execute — executeCreditDistribution
Tags: credit-distributions-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 CreditDistributionResponse — OK

PATCH /billing/{tenantLocator}/creditDistributions/{locator}/reverse — reverseCreditDistribution
Tags: credit-distributions-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Request body (CreditDistributionReverseRequest):
Responses:
  200 CreditDistributionResponse — OK

PATCH /billing/{tenantLocator}/creditDistributions/{locator}/reset — resetCreditDistribution
Tags: credit-distributions-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 CreditDistributionResponse — OK

PATCH /billing/{tenantLocator}/creditDistributions/{locator}/discard — discardCreditDistribution
Tags: credit-distributions-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 CreditDistributionResponse — OK

GET /billing/{tenantLocator}/creditDistributions/{locator}/invoices/list — fetchInvoicesTargetedByACreditDistribution
Tags: credit-distributions-controller
Permissions: read, list
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
  offset (integer, query)
  count (integer, query)
  extended (boolean, query)
Responses:
  200 InvoiceListResponse — OK

CreditDistributionListResponse
Properties:
  listCompleted (boolean, required)
  items (CreditDistributionResponse[], required)

CreditDistributionResponse
Properties:
  locator (ulid, required)
  creditDistributionState (Enum draft | validated | executed | reversed | discarded, required)
  currency (string, required)
  amount (number, required)
  createdAt (datetime, required)
  createdBy (uuid, required)
  accountLocator (ulid)
  sources (CreditItem[], required)
  targets (CreditItem[], required)
  validationResult (ValidationResult)
  executedAt (datetime)
  reversalReason (string)
  reversedAt (datetime)
  shortfallCreditLocators (ulid[], required)

CreditDistributionCreateRequest
Properties:
  accountLocator (ulid)
  amount (number, required)
  currency (string)
  sources (CreditItem[], required)
  targets (CreditItem[], required)

CreditDistributionUpdateRequest
Properties:
  accountLocator (ulid)
  amount (number)
  addSources (CreditItem[], required)
  removeSources (ulid[], required)
  addTargets (CreditItem[], required)
  removeTargets (ulid[], required)
  currency (string)

CreditDistributionPutRequest
Properties:
  accountLocator (ulid)
  amount (number, required)
  currency (string)
  sources (CreditItem[], required)
  targets (CreditItem[], required)

CreditDistributionReverseRequest
Properties:
  reversalType (string, required)