Name: UK Supplier Payment Practices API — days to pay & late.
Brand: 193market
SKU: api-193market-uk-supplier-payment-practices
Availability: InStock
Author: API Market

# UK Supplier Payment Practices API

## Overview

The UK Supplier Payment Practices API exposes the payment performance that large UK companies are legally required to report: average days to pay, the share of invoices paid outside agreed terms, and the payment terms themselves. It covers 9,149 companies keyed on Companies House number, with the full history of reporting periods for each one.

It is built for suppliers assessing whether a prospective customer actually pays on time, and for credit and procurement teams pricing payment risk. The benchmarks endpoint puts any single company in context, returning the market distribution from the 10th through the 90th percentile.

## Features

*   **9,149 Companies:** Payment practice records keyed on Companies House company number.
*   **Reporting History:** Every reported period per company, paginated with `page` and `per_page`.
*   **Market Benchmarks:** Percentile distribution for days-to-pay and invoices outside terms, p10 through p90.
*   **Name Search:** Find a company by name before pulling its profile.
*   **History Flag:** `history` on the company endpoint controls whether prior periods are included.
*   **Reference Codes:** `/v1/codes` documents the coded values used across responses.

## Use Cases

*   **Customer Payment Risk:** Check how a prospective customer pays before agreeing terms.
*   **Credit Decisions:** Price payment risk into credit limits using reported performance.
*   **Procurement Benchmarking:** Compare a company against the market distribution.
*   **Cash Flow Forecasting:** Use reported days-to-pay to model expected collection timing.

## API Documentation

### Base URL

All API requests for the UK Supplier Payment Practices API should be made to the following base URL:

```
https://prod.api.market/api/v1/193market/uk-supplier-payment-practices
```

### Authentication

Authentication is handled via an API key. You must include your key in the `x-api-market-key` header of every request:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Service Health

Health check

**Method:** `GET`
**Endpoint:** `/health`

**Example Response (200 OK):**

```json
{
  "ok": true,
  "meta": {
    "reports": "114989",
    "companies": "10249",
    "latest_filing": "2026-09-18",
    "built_at": "2026-09-19T05:01:09+00:00",
    "source_rows": "114989"
  },
  "refresh": {
    "last_run": "2026-09-19",
    "last_ok": {
      "reports": 114989
    },
    "message": null
  }
}
```

#### 2. Search Companies

Find companies that file payment practices reports

**Method:** `GET`
**Endpoint:** `/v1/companies/search`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `q` | query | Company name words, e.g. tesco stores | `string` | Yes |  | `100` |
| `limit` | query | 1-50 | `integer` | No | `20` |  |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/193market/uk-supplier-payment-practices/v1/companies/search?q=tesco&limit=2" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "query": "tesco",
  "count": 2,
  "results": [
    {
      "company_number": "04780736",
      "company_name": "TESCO MOBILE LIMITED",
      "reports": 18,
      "first_period_end": "2018-06-30",
      "last_period_end": "2026-06-30",
      "match_type": "prefix"
    },
    {
      "company_number": "00519500",
      "company_name": "TESCO STORES LIMITED",
      "reports": 16,
      "first_period_end": "2018-08-26",
      "last_period_end": "2026-03-01",
      "match_type": "prefix"
    }
  ],
  "data_freshness": {
    "latest_filing": "2026-09-18",
    "built_at": "2026-09-19T05:01:09+00:00"
  },
  "attribution": {
    "source": "UK Payment Practices Reporting, Department for Business and Trade",
    "source_url": "https://check-payment-practices.service.gov.uk/",
    "license": "Contains public sector information licensed under the Open Government Licence v3.0.",
    "license_url": "https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/",
    "changes": "Reports grouped by company number, figures typed, free-text answers omitted (read them at source_url), implausible values flagged, benchmarks and signals computed by this API.",
    "notice": "Figures are 
  …
```

#### 3. Get Company Payment Profile

Latest payment figures, history, benchmark and signals for one company

**Method:** `GET`
**Endpoint:** `/v1/companies/{company_number}`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `company_number` | path | — | `string` | Yes |  |  |
| `history` | query | How many past reports to include, 1-40 | `integer` | No | `6` |  |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/193market/uk-supplier-payment-practices/v1/companies/04780736" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{"company_number":"04780736","company_name":"TESCO MOBILE LIMITED","reports_filed":18,"first_period_end":"2018-06-30","latest":{"report_id":113630,"regime":"Regime-3","period":{"start":"2026-01-01","end":"2026-06-30"},"filed_on":"2026-07-24","average_days_to_pay":40.0,"invoices_paid_pct":{"within_30_days":16.0,"31_to_60_days":78.0,"over_60_days":6.0},"invoices_value_paid_gbp":{"within_30_days":291556834.0,"31_to_60_days":294225279.0,"over_60_days":49120423.0,"later_than_agreed_terms":3441207.0},"pct_invoices_not_paid_within_agreed_terms":9.0,"pct_invoices_not_paid_due_to_dispute":0.0,"payment_terms":{"shortest_standard_days":0.0,"longest_standard_days":90.0,"maximum_contractual_days":90.0,"changed_in_period":null,"suppliers_notified_of_change":null,"standard_terms_text_filed":true},"practices":{"payment_code_member":"No","e_invoicing_offered":false,"supply_chain_finance_offered":false,"charges_suppliers_to_stay_on_list":false},"data_quality_issues":[],"source_url":"https://check-payment-practices.service.gov.uk/report/113630"},"benchmark":{"compared_with":"latest report of each of 9149 reporting companies","average_days_to_pay_percentile":66.3,"pct_not_within_terms_percentile":32.5
  …
```

#### 4. Get Company Payment Reports

Every report a company has filed

**Method:** `GET`
**Endpoint:** `/v1/companies/{company_number}/reports`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `company_number` | path | — | `string` | Yes |  |  |
| `page` | query | — | `integer` | No | `1` |  |
| `per_page` | query | 1-50 | `integer` | No | `20` |  |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/193market/uk-supplier-payment-practices/v1/companies/04780736/reports?per_page=2" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "company_number": "04780736",
  "total": 18,
  "page": 1,
  "per_page": 2,
  "results": [
    {
      "report_id": 113630,
      "regime": "Regime-3",
      "period": {
        "start": "2026-01-01",
        "end": "2026-06-30"
      },
      "filed_on": "2026-07-24",
      "average_days_to_pay": 40,
      "invoices_paid_pct": {
        "within_30_days": 16,
        "31_to_60_days": 78,
        "over_60_days": 6
      },
      "invoices_value_paid_gbp": {
        "within_30_days": 291556834,
        "31_to_60_days": 294225279,
        "over_60_days": 49120423,
        "later_than_agreed_terms": 3441207
      },
      "pct_invoices_not_paid_within_agreed_terms": 9,
      "pct_invoices_not_paid_due_to_dispute": 0,
      "payment_terms": {
        "shortest_standard_days": 0,
        "longest_standard_days": 90,
        "maximum_contractual_days": 90,
        "changed_in_period": null,
        "suppliers_notified_of_change": null,
        "standard_terms_text_filed": true
      },
      "practices": {
        "payment_code_member": "No",
        "e_invoicing_offered": false,
        "supply_chain_finance_offered": false,
        "charges_suppliers_to_stay_on_list": false
      }
  …
```

#### 5. Get Market Benchmarks

How UK large companies pay, across all latest reports

**Method:** `GET`
**Endpoint:** `/v1/benchmarks`

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/193market/uk-supplier-payment-practices/v1/benchmarks" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "companies": 9149,
  "average_days_to_pay": {
    "p10": 15,
    "p25": 23,
    "median": 32,
    "p75": 45,
    "p90": 59
  },
  "pct_not_within_terms": {
    "p25": 6,
    "median": 17,
    "p75": 36,
    "p90": 60
  },
  "note": "latest report per company; implausible averages (over 365 days) excluded",
  "data_freshness": {
    "latest_filing": "2026-09-18",
    "built_at": "2026-09-19T05:01:09+00:00"
  },
  "attribution": {
    "source": "UK Payment Practices Reporting, Department for Business and Trade",
    "source_url": "https://check-payment-practices.service.gov.uk/",
    "license": "Contains public sector information licensed under the Open Government Licence v3.0.",
    "license_url": "https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/",
    "changes": "Reports grouped by company number, figures typed, free-text answers omitted (read them at source_url), implausible values flagged, benchmarks and signals computed by this API.",
    "notice": "Figures are as filed by each company and are not verified by the UK government or by this API. This API is not affiliated with or endorsed by the UK government."
  }
}
```

#### 6. Get Reference Codes

What the fields and signals mean

**Method:** `GET`
**Endpoint:** `/v1/codes`

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/193market/uk-supplier-payment-practices/v1/codes" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "regimes": {
    "Regime-1": "reporting periods from April 2017",
    "Regime-2": "revised regulations from 2025 (adds invoice values)",
    "Regime-3": "further revised form from mid-2025"
  },
  "signals": {
    "average_over_60_days": "latest average time to pay above 60 days",
    "most_invoices_paid_late": "50% or more of invoices not paid within agreed terms",
    "paying_slower": "average rose by 10 days or more across the last three usable reports",
    "paying_faster": "average fell by 10 days or more across the last three usable reports",
    "charges_suppliers_to_stay_on_list": "company reported charging suppliers to stay on its list",
    "no_recent_report": "no reporting period ending in the last 18 months"
  },
  "data_quality_issues": {
    "average_days_implausible": "average above 365 days or negative; likely a filing error",
    "period_end_in_far_future": "period end date more than a year ahead; likely a typo",
    "percentages_do_not_sum_to_100": "the three payment-time shares do not add up to 100 (±2)"
  },
  "who_reports": "UK companies and LLPs that exceed two of: turnover £54m, balance sheet £27m, 250 employees (thresholds as of the 2025 regulations) at 
  …
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| `200` | OK | The request succeeded and data has been returned. |
| `400` | Bad Request | The request contains invalid parameters or a malformed query. Review your request syntax. |
| `401` | Unauthorized | The `x-api-market-key` header is missing or contains an invalid key. |
| `403` | Forbidden | Your API key is valid but the origin rejected the request. |
| `404` | Not Found | The requested endpoint or record does not exist. Verify the URL path and identifier. |
| `429` | Too Many Requests | You have used all the API units included in your plan, or exceeded the per-second rate. See the Rate Limits section. |
| `500` | Internal Server Error | An unexpected server-side error occurred. Retry the request after a brief delay. |
| `503` | Service Unavailable | The service is temporarily unavailable. Retry with exponential backoff. |

## Rate Limits

The Basic plan includes 30 API units, Pro 1,000, Ultra 5,000 and Mega 25,000, each with a hard limit. When the included units are used up the API returns `429 Too Many Requests` until the plan renews. Paginate report history with `page` and `per_page`.

## FAQ

*   **What is the company number?**
    The Companies House registration number, for example `04780736`. Find it with `/v1/companies/search`, then use it for the profile and reports endpoints.

*   **How should I read the benchmarks?**
    `/v1/benchmarks` returns the distribution across all covered companies — median, quartiles and the 10th/90th percentiles — so you can see where one company sits rather than judging its days-to-pay in isolation.

*   **Why do some companies have several reports?**
    Large UK companies report payment practices each reporting period. The reports endpoint returns that history, most recent first.

*   **Does this cover every UK company?**
    No. Only companies above the statutory reporting thresholds are required to report, which is why coverage is 9,149 companies rather than the full register.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


How quickly large UK companies pay suppliers: average days to pay, late payment share, payment terms, trend and percentile benchmark per company number. JSON.

UK Supplier Payment Practices API — days to pay & late.

Basic