> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tilta.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieve a credit facility
> Fetch the active credit facility for a buyer, including total credit limit, available balance, current usage amount, currency, and expiration date.
Use this endpoint to retrieve the current state of a buyer's active credit facility. The response tells you the total approved credit limit, how much is currently available to use, how much is already committed to outstanding orders and invoices, and when the facility expires. This is useful for gating checkout flows – check the buyer's available credit before authorizing an order to prevent requests that would exceed the facility limit.
Before creating an order for a buyer, compare the order total against `available_amount`. This prevents order authorization
failures caused by insufficient credit. Amounts are in the smallest currency unit – divide by 100 to convert cents to euros.
This endpoint returns a `404` if the buyer has no credit facility – either because one was never requested, or because the
request was rejected. Use [Create facility](/api-reference/facilities/create-facility) to request one.
## OpenAPI
````yaml GET /v1/buyers/{external_id}/facility
openapi: 3.0.0
info:
version: 0.0.1
title: Tilta API
description: Tilta API documentation
servers:
- url: https://api.tilta.io
description: Tilta Production API
- url: https://api.tilta-sandbox.io
description: Tilta Sandbox API
security: []
paths:
/v1/buyers/{external_id}/facility:
get:
tags:
- Credit Facilities
summary: Retrieve a credit facility
description: |-
Returns a credit facility for the buyer if there is an active one.
Includes Total, Available and Used amounts of a credit facility, as well as the expiration date.
parameters:
- schema:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
description: Unique identifier of a buyer.
required: true
description: Unique identifier of a buyer.
name: external_id
in: path
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
buyer_external_id:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
description: Unique identifier for buyer.
example: 5f6374a46a5e8e0104aa5cd4
pending_orders_amount:
type: integer
description: >-
Blocked by pending deferred orders portion of the Credit
Limit. As minimum currency unit (e.g cents/pence).
example: 2500
risk_band:
type: string
enum:
- REJECT
- A1
- A2
- B1
- B2
- C1
- C2
- D1
- D2
created_at:
type: number
description: >-
Timestamp indicating when the facility was created (unix
time in seconds).
example: 1582896122
updated_at:
type: number
description: >-
Timestamp indicating the last time the facility was
updated (unix time in seconds).
example: 1582896122
pending_actions:
type: array
nullable: true
items:
type: object
properties:
type:
type: string
enum:
- CREATION
- RENEWAL
- INCREASE
description: Type of the pending action.
created_at:
type: number
description: >-
Timestamp indicating when the pending action was
created (unix time in seconds).
example: 1582896122
required:
- type
- created_at
description: List of pending actions for the facility.
status:
type: string
enum:
- ACTIVE
- PENDING
- FROZEN
- EXPIRED
description: Status of the Active facility
example: ACTIVE
reviewed_at:
type: number
nullable: true
description: Review Date of the Active facility
currency:
type: string
enum:
- EUR
- GBP
- USD
- CHF
- PLN
- CZK
- RON
- BGN
- DKK
- HUF
- SEK
- NOK
- JPY
- AUD
- NZD
- CAD
description: ISO 4217 three-letter currency code.
total_amount:
type: integer
description: >-
Total credit limit available to the Buyer. As minimum
currency unit (e.g cents/pence).
example: 10000
available_amount:
type: integer
description: >-
Available portion of the Credit Limit. As minimum currency
unit (e.g cents/pence).
example: 5200
used_amount:
type: integer
description: >-
Credit Limit portion currently in use (not repaid). As
minimum currency unit (e.g cents/pence).
example: 4800
required:
- buyer_external_id
- pending_orders_amount
- risk_band
- created_at
- updated_at
- pending_actions
- status
- reviewed_at
- currency
- total_amount
- available_amount
- used_amount
additionalProperties: false
description: Active facility of the buyer.
'202':
description: ''
content:
application/json:
schema:
type: object
properties:
buyer_external_id:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
description: Unique identifier for buyer.
example: 5f6374a46a5e8e0104aa5cd4
status:
type: string
enum:
- PENDING
description: Status of the Pending facility
required:
- buyer_external_id
- status
description: The creation of a credit facility is pending.
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/badRequestSchema'
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unauthorizedRequestSchema'
'404':
description: ''
content:
application/json:
schema:
$ref: >-
#/components/schemas/getBuyerActiveFacilityNotFoundSchemaNotFoundSchema
security:
- bearerAuth: []
components:
schemas:
badRequestSchema:
type: object
properties:
code:
type: string
description: Error code
example: BAD_REQUEST
error:
type: string
description: Error message for debugging purposes
example: Request validation failed. 1 issue found.
issues:
type: array
items:
type: object
properties:
code:
type: string
description: Issue code
example: INVALID_TYPE
path:
type: string
description: Issue path starting with body, params, querystring, or headers
example: body.registered_at
message:
type: string
description: Issue message for debugging purposes
example: Invalid type
required:
- code
- path
- message
description: List of issues
example:
- code: INVALID_TYPE
path: body.registered_at
message: Invalid type
required:
- code
- error
- issues
description: Bad Request, see error message for details.
example:
code: BAD_REQUEST
error: Request validation failed. 1 issue found.
issues:
- code: INVALID_TYPE
path: body.registered_at
message: Invalid type
unauthorizedRequestSchema:
type: object
properties:
error:
type: string
description: Error details.
example: Unauthorized
code:
type: string
description: Error code.
example: UNAUTHORIZED
required:
- error
- code
description: Unauthorized Request.
example:
error: Unauthorized
code: UNAUTHORIZED
getBuyerActiveFacilityNotFoundSchemaNotFoundSchema:
type: object
properties:
error:
type: string
description: Error details.
example: No Entity found
code:
type: string
description: Error code.
example: NOT_FOUND
required:
- error
- code
description: Buyer doesn't have an active facility
example:
error: No Entity found
code: NOT_FOUND
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Your Tilta API key, sent as `Bearer `.
````