> ## 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.

# Buyer onboarding

> Step-by-step guide to creating buyers, uploading transaction history, and requesting credit facilities with automated underwriting on Tilta.

Buyers are the businesses you sell to – the ones that purchase goods or services and receive deferred payment terms. Before a buyer can use Tilta's financing, whether at an online checkout or on an order agreed offline, they must have an active credit facility. This guide walks you through the three-step onboarding process and explains how to use Tilta's pre-built onboarding UI to reduce development time.

## How the credit facility works

A credit facility is a per-buyer credit line of up to **€250,000**, approved through Tilta's automated underwriting engine. Once approved, the facility covers every financed order for that buyer.

Tilta automatically renews each credit facility every three months – no action is required from you or the buyer to keep it active. If a buyer's risk profile changes significantly, Tilta may adjust the facility limit at renewal.

<Note>
  Only buyers with an **active** credit facility can have their receivables financed. Attempting to create an invoice for a buyer without an active facility will return an error.
</Note>

***

## Onboarding process

<Steps>
  <Step title="Create the buyer">
    Start by creating the buyer record in Tilta. Submit the buyer's company information using the `POST /v1/buyers` endpoint. Required fields vary by country and legal form, but the core set includes the company's country of registration, VAT number, and contact details.

    You must also provide contact information for the buyer's representative – the person who will interact with Tilta on behalf of the company. For larger enterprises with a dedicated accounts payable team, you can provide AP team contact details instead.

    ```http theme={null}
    POST /v1/buyers
    Authorization: Bearer YOUR_API_KEY
    Content-Type: application/json
    ```

    ```json theme={null}
    {
      "external_id": "buyer_de_001",
      "legal_name": "Buyer GmbH",
      "legal_form": "LIMITED_COMPANY",
      "business_address": {
        "street": "Kaufstraße",
        "house": "12",
        "postcode": "80331",
        "city": "Munich",
        "country": "DE"
      },
      "business_identifiers": [
        {
          "type": "VAT_ID",
          "value": "DE987654321",
          "country": "DE"
        }
      ]
    }
    ```

    `external_id`, `legal_name`, `legal_form`, and `business_address` are required. Add the buyer's contact people separately with [Create a contact](/api-reference/contacts/create-contact) – they are the recipients of Tilta's automated emails.

    At this stage the buyer exists in Tilta but does not yet have a credit facility.

    <Tip>
      Use a stable, unique identifier for `external_id` – typically the buyer's ID in your own system. This value is used throughout the API to reference the buyer and cannot be changed after creation.
    </Tip>
  </Step>

  <Step title="Upload transaction history (optional but recommended)">
    Tilta's underwriting engine uses third-party data to assess creditworthiness, but supplementing this with your platform's own transaction history can meaningfully improve the credit facility limit offered to the buyer.

    Submit historical order data using `POST /v1/buyers/{external_id}/orders`. The body is an array of completed orders. Each record needs `external_id`, `ordered_at`, `payment_method`, `payment_term`, `amount`, and `status`, where `status` is either `CLOSED` (repaid) or `CANCELLED`.

    ```http theme={null}
    POST /v1/buyers/{external_id}/orders
    Authorization: Bearer YOUR_API_KEY
    Content-Type: application/json
    ```

    ```json theme={null}
    [
      {
        "external_id": "hist_order_001",
        "amount": {
          "net": 120000,
          "gross": 142800,
          "tax": 22800,
          "currency": "EUR"
        },
        "ordered_at": 1705312800,
        "payment_method": "TRANSFER",
        "payment_term": "DEFER_30D",
        "status": "CLOSED"
      },
      {
        "external_id": "hist_order_002",
        "amount": {
          "net": 85000,
          "gross": 101150,
          "tax": 16150,
          "currency": "EUR"
        },
        "ordered_at": 1708439400,
        "payment_method": "TRANSFER",
        "payment_term": "DEFER_30D",
        "status": "CLOSED"
      }
    ]
    ```

    <Info>
      All monetary values are expressed in the smallest currency unit (e.g., euro cents). An order worth €1,200.00 net is represented as `120000`.
    </Info>

    You can upload up to 24 months of historical orders. More data generally leads to better underwriting outcomes, particularly for buyers with high order volumes or large average order values.
  </Step>

  <Step title="Request a credit facility">
    Once you have created the buyer and optionally uploaded transaction history, request a credit facility. This triggers Tilta's automated underwriting process, which queries third-party data sources (commercial registers, credit bureaus, etc.) alongside any transaction history you provided.

    ```http theme={null}
    POST /v1/buyers/{external_id}/facility
    Authorization: Bearer YOUR_API_KEY
    Content-Type: application/json
    ```

    ```json theme={null}
    {
      "requested_amount": {
        "amount": 5000000,
        "currency": "EUR"
      }
    }
    ```

    Tilta will return a response indicating the facility has been requested. The underwriting process is typically near-instant for automated decisions. The facility status transitions to `ACTIVE` when approved.

    You can check facility status at any time by calling `GET /v1/buyers/{external_id}/facility`, or configure a webhook to receive a notification when the status changes.

    <Warning>
      If underwriting cannot be completed automatically – for example, if the buyer's data is insufficient or a manual review is triggered – Tilta will notify you via webhook. The buyer will not be able to use payment terms until the facility is approved.
    </Warning>
  </Step>
</Steps>

***

## Pre-built onboarding UI

If you do not want to build a custom onboarding form from scratch, Tilta offers a pre-built Buyer Onboarding UI that handles data collection and submission. The UI automatically pre-fills any data you already provided when creating the buyer, reducing the amount the buyer needs to enter manually.

<Note>
  The pre-built Onboarding UI is only available for buyers who do **not** yet have an active credit facility. Once a facility is approved, the UI is no longer accessible.
</Note>

To use the pre-built UI, first create an onboarding session for the buyer:

```http theme={null}
POST /v1/buyers/{external_id}/sessions/onboarding
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

```json theme={null}
{
  "success_url": "https://yourplatform.com/checkout/success",
  "error_url": "https://yourplatform.com/checkout/error"
}
```

The response includes two values:

| Field   | Description                                                 |
| ------- | ----------------------------------------------------------- |
| `token` | A short-lived JWT used to initialise the Web Element widget |
| `url`   | A fully qualified URL to Tilta's hosted onboarding form     |

### Delivery options

<Tabs>
  <Tab title="Web Element (embedded widget)">
    Use the JWT token to embed the onboarding experience directly within your platform's UI. The Web Element renders inside your page – the buyer never leaves your site.

    Initialise the widget using Tilta's JavaScript SDK:

    ```javascript theme={null}
    import { createWidget } from '@tilta/onboarding-sdk';

    const widget = createWidget({
      token: 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...', // JWT from session response
      containerId: 'tilta-onboarding-container',
      onSuccess: () => {
        // Buyer has completed onboarding – proceed to checkout
        window.location.href = '/checkout';
      },
      onCancel: () => {
        // Buyer cancelled – handle accordingly
      }
    });

    widget.mount();
    ```

    Alternatively, open it as a modal overlay:

    ```javascript theme={null}
    import { createModal } from '@tilta/onboarding-sdk';

    const modal = createModal({
      token: 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...',
      onSuccess: () => {
        modal.close();
        proceedToCheckout();
      }
    });

    modal.open();
    ```

    <Tip>
      The Web Element is the recommended approach for platforms that want to maintain a consistent look and feel. You can apply your platform's brand colours through the SDK's theming options.
    </Tip>
  </Tab>

  <Tab title="Hosted redirect">
    Redirect the buyer's browser directly to the `url` returned by the session endpoint. Tilta's hosted form handles the entire onboarding journey, then redirects the buyer back to your `success_url` or `error_url` when complete.

    ```javascript theme={null}
    // Redirect the Buyer to Tilta's hosted onboarding form
    const response = await fetch(`/v1/buyers/${buyerId}/sessions/onboarding`, {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${API_KEY}` },
      body: JSON.stringify({
        success_url: 'https://yourplatform.com/checkout/success',
        error_url: 'https://yourplatform.com/checkout/error'
      })
    });

    const { url } = await response.json();
    window.location.href = url;
    ```

    The Hosted Redirect is the fastest implementation path. It requires no frontend SDK integration and works in any web environment. Use it when you want to minimise integration effort or when embedding an iframe is not appropriate.
  </Tab>
</Tabs>

***

## Credit facility renewals

Tilta renews each active credit facility automatically every **three months**. The renewal uses the same underwriting signals as the initial approval and may result in an increased, maintained, or decreased credit limit based on updated data.

Neither you nor the buyer need to take any action to trigger a renewal. If a renewal results in a significant change to the facility limit, Tilta will notify you via webhook so you can update any UI elements that display the available credit amount.

***

## API reference summary

| Endpoint                                       | Method | Purpose                               |
| ---------------------------------------------- | ------ | ------------------------------------- |
| `/v1/buyers`                                   | `POST` | Create a new buyer                    |
| `/v1/buyers/{external_id}/orders`              | `POST` | Upload historical order data          |
| `/v1/buyers/{external_id}/facility`            | `POST` | Request a credit facility             |
| `/v1/buyers/{external_id}/facility`            | `GET`  | Retrieve facility status and limit    |
| `/v1/buyers/{external_id}/sessions/onboarding` | `POST` | Create a pre-built onboarding session |