> ## 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.
# Request a facility renewal
> Trigger an early renewal of a buyer credit facility ahead of the standard 3-month cycle. Initiates a fresh underwriting review and extends the expiry.
Tilta automatically renews every credit facility approximately every three months, running a fresh underwriting review and extending the expiry date before the current period ends. If you need to renew a facility ahead of that schedule – for example, because a high-value buyer is approaching expiry and you want to ensure continuity, or because the buyer's business profile has significantly improved since the last review – you can request an early renewal using this endpoint. The renewal triggers a new underwriting assessment and delivers the result via a `FACILITY.RENEWAL.*` webhook event.
## Webhook events
The renewal result is delivered asynchronously. Subscribe to the following events in your webhook configuration:
| Event | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `FACILITY.RENEWAL.ACCEPTED` | The renewal was approved. The limit may differ from the previous one, based on the new underwriting result. |
| `FACILITY.RENEWAL.REJECTED` | The renewal was rejected. If the current facility is still within its active period, it remains usable until it expires. |
| `FACILITY.RENEWAL.IN_REVIEW` | Underwriting requires additional review and has not yet concluded. |
Tilta handles automatic renewal for all active facilities before they expire. You only need to call this endpoint if you want
to renew a facility ahead of the normal schedule – for example, to get a fresh credit assessment for a buyer who has grown
substantially since their last review.
If a buyer's credit facility has already expired, use this endpoint to request a renewal and restore their ability to place
orders. After a `FACILITY.RENEWAL.ACCEPTED` event, the buyer's `available_amount` is restored and new orders can be authorized
immediately.
A renewal may result in a different credit limit than the buyer's current one – the new underwriting review may increase or
decrease the limit based on the buyer's current creditworthiness. Ensure your platform handles limit changes gracefully,
particularly if a buyer's limit decreases after renewal.
## OpenAPI
````yaml POST /v1/buyers/{external_id}/facility/renew
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/renew:
post:
tags:
- Credit Facilities
summary: Request a credit facility renewal
description: Request the renewal of a credit facility for a buyer.
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:
'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
required:
- buyer_external_id
description: The renewal of a credit facility has been requested.
'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:
anyOf:
- $ref: '#/components/schemas/buyerNotFoundSchema'
- $ref: '#/components/schemas/facilityNotFoundSchema'
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
buyerNotFoundSchema:
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 not found
example:
error: No Entity found
code: NOT_FOUND
facilityNotFoundSchema:
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: Facility not found
example:
error: No Entity found
code: NOT_FOUND
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Your Tilta API key, sent as `Bearer `.
````