# Fare data

:::lead
Fare data is everything that decides what a traveller can buy and what it costs: the rules and
parameters that apply to a product, the product itself, the prices, and the sales packages that
make the product available in sales channels. As an Entur partner you can create and maintain
your own fare data through the API.
:::

The API enforces the rules that connect these elements. It checks that the parameters a product
refers to exist and are published for the whole time the product is valid, and that the effective dates of an element's published versions have no overlaps or gaps. If a request breaks a rule, the API rejects it with a
message that says why. See
[Versions and lifecycle](/docs/partner-services/fare-data/versions-and-lifecycle) for the
rules.

## Access

To create and maintain fare data, you need:

- An Entur partner agreement. Your organisation must be onboarded as a partner before it can use
  the API.
- A client with OAuth 2.0 client credentials. See
  [Authentication](/docs/authentication).
- The [`ET-Client-Name` header](/docs/getting-started#client-identification-et-client-name) on
  every request.
- The permissions the endpoints you use need. The API reference lists the required permission
  for each endpoint.

Every element belongs to an organisation. When you create an element, it belongs to the
organisation in your token. You can only change elements your organisation owns.

## Data model

The fare data you maintain is made up of these elements:

```mermaid
flowchart LR
    SOP["SalesOfferPackage<br/>(sales package)"] -->|"contains"| P["Product"]
    SOP -->|"one per channel"| DA["DistributionAssignment<br/>(who may sell it)"]
    P -->|"refers to"| R["Rules and parameters<br/>(when, where, for whom, on which conditions)"]
    P --> |"priced by"| FT["FareTable<br/>(prices)"]
```

| Element | What it is |
| --- | --- |
| Product | What the traveller gets, for example a ticket or a supplement. Supplement products (`SupplementProduct`), such as parking, bicycle or seat reservation, are one type. |
| Rules and parameters | Separate elements that decide when, where, for whom and on which conditions a product can be bought and used. Examples: a purchase window (`PurchaseWindow`) for when it can be bought, and a usage validity period (`UsageValidityPeriod`) for how long it can be used after purchase or activation. New types are added over time. See the [Product parameters API](/apis/product-parameters-api). |
| `FareTable` | The prices for a product. A product refers to its fare tables by id. |
| `SalesOfferPackage` | What is actually sold in a sales channel. It contains one or more products. |
| `DistributionAssignment` | Which sales channels may sell a sales package, and whether they may sell, refund or exchange it. |

Rules and parameters are shared. Several products can refer to the same parameter.

You change an element by creating a new version of it. Each version has effective dates, the travel dates it applies to, and a status that says which Entur environment it is available in:
none yet, the staging environment for testing, or the production environment.

## APIs

Fare data is spread across three partner APIs:

| API | Use it for |
| --- | --- |
| [Products](/apis/products-api) | Products and sales packages |
| [Product parameters](/apis/product-parameters-api) | Rules and parameters |
| [Pricing](/apis/pricing-api) | Fare tables |

## Next steps

Read on:

- [Versions and lifecycle](/docs/partner-services/fare-data/versions-and-lifecycle)
  explains versions, effective dates, statuses, the order to publish in, and the most common errors.
- [Set up fare data](/guides/fare-data) takes you step by step from access to a published,
  priced product in a sales package.
