# Billing Holds API



Billing Holds are used to temporarily suspend invoicing and delinquency processes including lapse.

<EndpointIndex
  names={[
  	'fetchHold',
  	'fetchAllHoldsForAnAccount',
  	'createHold',
  	'updateHold',
  	'validateHold',
  	'activateHold',
  	'releaseHold',
  	'resetHold',
  	'discardHold',
  ]}
/>

Fetch [#fetch]

Fetch Hold [#fetch-hold]

<ApiEndpoint name="fetchHold" />

<ApiSchema name="HoldResponse" />

Fetch All Holds For An Account [#fetch-all-holds-for-an-account]

<ApiEndpoint name="fetchAllHoldsForAnAccount" />

<ApiSchema name="HoldListResponse" />

Creation and Update [#creation-and-update]

Create Hold [#create-hold]

<ApiEndpoint name="createHold" />

<ApiSchema name="HoldCreateRequest" />

Update Hold [#update-hold]

<ApiEndpoint name="updateHold" />

<ApiSchema name="HoldUpdateRequest" />

Execution [#execution]

Validate Hold [#validate-hold]

<ApiEndpoint name="validateHold" />

Activate Hold [#activate-hold]

<ApiEndpoint name="activateHold" />

Release, Reset, and Discard [#release-reset-and-discard]

Release Hold [#release-hold]

<ApiEndpoint name="releaseHold" />

Reset Hold [#reset-hold]

<ApiEndpoint name="resetHold" />

Discard Hold [#discard-hold]

<ApiEndpoint name="discardHold" />

See Also [#see-also]

* [Billing Holds Feature Guide](/features/billing/billing-holds)


## API Reference

GET /billing/{tenantLocator}/holds/{locator} — fetchHold
Tags: holds-controller
Permissions: read
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 HoldResponse — OK

GET /billing/{tenantLocator}/holds/accounts/{accountLocator}/list — fetchAllHoldsForAnAccount
Tags: holds-controller
Permissions: read, list
Parameters:
  tenantLocator (uuid, path, required)
  accountLocator (ulid, path, required)
  state (Enum draft | validated | active | discarded | released, query)
  offset (integer, query)
  count (integer, query)
  extended (boolean, query)
Responses:
  200 HoldListResponse — OK

POST /billing/{tenantLocator}/holds — createHold
Tags: holds-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
Request body (HoldCreateRequest):
Responses:
  200 HoldResponse — OK

PATCH /billing/{tenantLocator}/holds/{locator} — updateHold
Tags: holds-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Request body (HoldUpdateRequest):
Responses:
  200 HoldResponse — OK

PATCH /billing/{tenantLocator}/holds/{locator}/validate — validateHold
Tags: holds-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 HoldResponse — OK

PATCH /billing/{tenantLocator}/holds/{locator}/activate — activateHold
Tags: holds-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 HoldResponse — OK

PATCH /billing/{tenantLocator}/holds/{locator}/release — releaseHold
Tags: holds-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 HoldResponse — OK

PATCH /billing/{tenantLocator}/holds/{locator}/reset — resetHold
Tags: holds-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 HoldResponse — OK

PATCH /billing/{tenantLocator}/holds/{locator}/discard — discardHold
Tags: holds-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 HoldResponse — OK

HoldResponse
Properties:
  locator (ulid, required)
  accountLocator (ulid, required)
  targetType (Enum invoicing | delinquency, required)
  holdState (Enum draft | validated | active | discarded | released, required)
  createdAt (datetime, required)
  updatedAt (datetime, required)
  validationResult (ValidationResult)

HoldListResponse
Properties:
  listCompleted (boolean, required)
  items (HoldResponse[], required)

HoldCreateRequest
Properties:
  accountLocator (ulid, required)
  targetType (Enum invoicing | delinquency, required)

HoldUpdateRequest
Properties:
  accountLocator (ulid)
  targetType (Enum invoicing | delinquency)