> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vepler.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Address Billing & Sessions

> How search-and-retrieve billing works on the Vepler API — why it is sessionless, and how you are charged once per address.

## Overview

Most address and location workflows follow the same funnel:

1. **Discover** — a user types into a search box and you surface matching addresses (autocomplete / typeahead, or a postcode lookup). Each keystroke may fire a request.
2. **Retrieve** — the user picks one result and you fetch the full, verified record for it (the address detail, geocode, and identifiers).

The question every billing model has to answer is: **how do you avoid charging for the same address twice across that funnel** — once for surfacing it in autocomplete, and again for fetching its details?

Vepler answers this with a **sessionless, entity-keyed** model:

<Card title="The rule in one line" icon="circle-check">
  **Discovery is free. Retrieval is charged once per address, per billing period.** You never manage a session token — we deduplicate on the address itself, on the server.
</Card>

***

## Two ways to bill a search funnel

### The session-token model

Some mapping and autocomplete APIs solve double-billing with a **session token**. Your client generates a token, attaches it to every autocomplete keystroke, and then attaches the *same* token to the final "fetch details" call. The provider bundles everything carrying that token into **one billable session**, so the keystrokes and the final fetch are billed together rather than separately.

It works, but it pushes real responsibility onto your client:

* You must **generate, attach, and reset** the token at exactly the right moments.
* The token typically **expires after a few minutes**; get the lifecycle wrong and you are billed twice, or not at all.
* It only deduplicates **within one session** — the same address fetched again tomorrow, or fetched through a different endpoint, is a brand-new charge.

### The direct-access (sessionless) model — what Vepler uses

Vepler does not use session tokens. There is nothing for your client to generate, attach, or reset. Instead, billing is keyed on the **address entity itself** — its UPRN (Unique Property Reference Number), the stable identifier the rest of the API already uses as the `locationId`.

When you retrieve an address, we record that **this account has paid for this UPRN in this billing period**. Any later retrieval of the same UPRN — same endpoint or different, one minute later or three weeks later — recognises that ledger entry and is **not charged again** until the next period.

<Note>
  This is why we call it *direct access*: you call the endpoint you need, directly, with no session bookkeeping. The deduplication happens server-side on data we control (the returned UPRN), not on a token your client has to manage correctly.
</Note>

***

## Why direct access is the better fit

We chose the entity-keyed model deliberately. The logic:

<CardGroup cols={2}>
  <Card title="Nothing to get wrong" icon="hand-sparkles">
    No token to generate, attach, expire, or reset. A category of integration bugs simply does not exist for you.
  </Card>

  <Card title="Deduplicates across the whole API" icon="diagram-project">
    Autocomplete → `/address/uprn` → `/property` all collapse onto the same UPRN. A session token can only deduplicate within a single session; the address key spans endpoints and products.
  </Card>

  <Card title="Predictable invoices" icon="chart-line">
    You are billed for **distinct addresses retrieved in a period**, not for request volume. Retries, refreshes, and repeated lookups of an address you already paid for do not add to your bill.
  </Card>

  <Card title="Cache-friendly" icon="database">
    Because the charge is tied to the address and the period — not to a short-lived session — you can cache a retrieved record for the rest of the period and re-fetch it freely if you need to.
  </Card>
</CardGroup>

***

## How charging works

### Discovery is free

Surfacing addresses so a user can pick one is **not charged**. Use autocomplete and postcode search as freely as your rate limits allow — typeahead that fires on every keystroke does not run up a bill.

Discovery returns enough to identify and display a result — including its **UPRN**, which is the key you carry into the retrieval step.

```typescript theme={null}
import { SDK } from '@vepler/sdk';

const vepler = new SDK({ apiKey: process.env.VEPLER_API_KEY });

// Free: surface candidate addresses as the user types.
const suggestions = await vepler.search.suggest({ query: '10 Downing' });

// The user picks one; carry its UPRN into the (charged) retrieval step.
const chosenUprn = suggestions.results[0].uprn;
```

### Retrieval is charged — once per address, per period

Fetching the full record for an address is the **chargeable** step. The first time you retrieve a given UPRN in a billing period, it is charged. Every subsequent retrieval of that **same** UPRN in the **same** period is recognised as already paid and costs nothing.

```typescript theme={null}
// Charged the first time this UPRN is retrieved this period.
const first = await vepler.address.getByUprn({ uprn: chosenUprn });

// Same UPRN, same period — recognised as already paid, not charged again.
const again = await vepler.address.getByUprn({ uprn: chosenUprn });
```

<Note>
  The billing period is currently the **calendar month** (UTC). Retrieving an address you already paid for earlier in the same month is free; retrieving it again in a new month is a new charge.
</Note>

### A worked example

<Steps>
  <Step title="A user searches">
    They type "10 Downing Street" into your search box. Autocomplete fires several requests and surfaces matching addresses. **Cost: nothing** — discovery is free.
  </Step>

  <Step title="They select an address">
    You retrieve the full record for the chosen UPRN. **Cost: one charge** for that address.
  </Step>

  <Step title="They view it again later">
    The same user (or another user on your account) retrieves that UPRN again this month — from a detail page, a refresh, or a different endpoint. **Cost: nothing** — already paid this period.
  </Step>

  <Step title="Next month">
    The same address is retrieved again in a new billing period. **Cost: one charge** — a new period resets the ledger.
  </Step>
</Steps>

The funnel that surfaced the address and then fetched it is billed as **one address**, not as "autocomplete requests plus a details fetch".

***

## What this means for your integration

<CardGroup cols={2}>
  <Card title="Don't build session logic" icon="ban">
    If you are porting from a session-token API, you can drop all token generation and lifecycle code. Call the endpoints directly.
  </Card>

  <Card title="Retries are safe" icon="rotate">
    A retried retrieval after a timeout does not double-charge — the address is already claimed for the period. Retry with confidence.
  </Card>

  <Card title="Cache within the period" icon="box-archive">
    Store retrieved records and reuse them for the rest of the period. Re-fetching an address you have already paid for is free, so caching is an optimisation, not a billing necessity.
  </Card>

  <Card title="Bulk is one charge per address" icon="layer-group">
    Bulk and batch retrievals are billed per **distinct address** returned, deduplicated the same way as individual calls.
  </Card>
</CardGroup>

### Free tiers and licensed access

Some accounts hold a licence grant that **zero-rates** address retrieval. Where that applies, retrieval is free for that account, but the model is otherwise identical — addresses are still recorded as retrieved, simply at no cost. There is nothing different to do in your integration.

***

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Do autocomplete keystrokes cost anything?">
    No. Discovery — autocomplete, typeahead, and postcode search — is free. You are only charged when you retrieve the full record for a specific address.
  </Accordion>

  <Accordion title="If I fetch the same address ten times in a month, how much am I charged?">
    Once. The first retrieval in the billing period is charged; the other nine are recognised as already paid and cost nothing.
  </Accordion>

  <Accordion title="Does a retry after a network timeout charge me twice?">
    No. Billing is keyed on the address, not on the request. A retry re-claims the same address, sees it is already paid for the period, and is not charged again.
  </Accordion>

  <Accordion title="What counts as 'the same address'?">
    The UPRN. Two retrievals are deduplicated when they return the same UPRN, regardless of which endpoint surfaced or fetched it, or how the identifier was formatted.
  </Accordion>

  <Accordion title="When does an address become chargeable again?">
    At the start of the next billing period (currently the calendar month). The same address retrieved in a new period is a new charge.
  </Accordion>

  <Accordion title="Do I need to send a session token or request ID?">
    No. There is no session token. Direct access means you call the endpoint you need with no session bookkeeping — deduplication is handled for you on the server.
  </Accordion>
</AccordionGroup>

***

## Next steps

<CardGroup cols={2}>
  <Card title="Usage & Limits" icon="gauge" href="/guides/rate-limiting">
    How requests are metered and how to optimise throughput.
  </Card>

  <Card title="Address API" icon="location-dot" href="/quickstart">
    Explore the address and search endpoints.
  </Card>
</CardGroup>