> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/transit-digitization/get-started/concepts/fare-products.md).

# Fare Products

The fare products are the travel contracts the users can purchase.

### Overview <a href="#overview" id="overview"></a>

There are 3 main fare products categories defined within D1 Transit:

1. Stored-value fare products
2. Count-based fare products
3. Time-based fare products

#### Stored-Value Fare Products <a href="#stored-value-fare-products" id="stored-value-fare-products"></a>

Stored-value fare products allow users to preload a set amount of money onto a their transit card, which can then be used to ride on the transit network.

Transit operators may offer fare capping which ensures users never pay more than a certain amount within a specified period, providing them cost savings.

#### Count-Based Fare Products <a href="#count-based-fare-products" id="count-based-fare-products"></a>

Count-based fare products allow users to purchase a set number of trips in advance, rather than paying for unlimited travel within a specific period (such as weekly or monthly products).

These products offer a finite number of uses that users can utilize. Typically, count-based fare products can be used until the count is exhausted, however they may have an expiration.

#### Time-Based Fare Products <a href="#time-based-fare-products" id="time-based-fare-products"></a>

Time-based fare products are typically available as monthly or weekly basis and allow unlimited number of trips within a predefined period.

Unlike traditional pay-per-ride tickets, time-based products are activated for a set duration:

* from the moment of purchase
* on a scheduled future date
* or upon the first use

and remain valid for the entirety of that period.

### Data Model <a href="#data-model" id="data-model"></a>

The following section describes how a fare product is defined within D1 Transit solution.

There are 2 notions to consider:

* Product metadata: metadata linked to a product that has been purchased and is linked to the user card account.
* Purchasable product metadata: metadata linked to a purchasable product, i.e. a product users may purchase.

#### Product / Purchasable Product common metadata <a href="#product--purchasable-product-common-metadata" id="product--purchasable-product-common-metadata"></a>

**ProductId**

The fare product unique identifier

**ProductType**

Defines the nature of the fare product, as indicated above, it can be stored-value, count-based or time-based.

**ProductName**

Localized product name, displayed within the digital wallet.

**Fare**

Fare object is composed of:

* **fareId**: an identifier of the GTFS feed exposed by the Transit operator
* **fareClass**: when product is associated with a certain price/category, users can purchase (e.g. business, first, standard...)
* **concession**: student, elder, full fare...

**ValidityParameters**

ValidityParameters object is composed of:

* **numberOfTrips**: number of trips a product can be used for. Typically used for count-based products.
* **timeLimits (start time / end time)**: time window within which a product is valid. Typically used for time-based products, but can be applied to count-based products too.
* **validityAfterTapIn**: period of time for which a product is valid after the first tap-in.
* **validityAfterTapOut**: period of time for which a product is valid after tap-out. Typically used for transfer purpose.
* **zoneLimits**: from/to zones the product is valid for.
* **stationLimits**: from/to stations the product is valid for.
* **topupLimits**: limits that apply to topping up a stored-value product.

#### Product Specific Metadata <a href="#product-specific-metadata" id="product-specific-metadata"></a>

**PurchaseDetails**

PurchaseDetails object is composed of:

* **purchaseId**: receipt number/identifier for tracking the product purchase.
* **purchaseTime**: purchase time of the original product.
* **price**: price of the product.
* **currencyCode**: currency code.
* **repurchaseUrl**: link to repurchase the same product.
* **refundUrl**: link to refund website for that product.

#### Purchasable Product Specific Metadata <a href="#purchasable-product-specific-metadata" id="purchasable-product-specific-metadata"></a>

**SalePeriod**

SalePeriod object is composed of:

* **startDate**: The earliest date time (inclusive) that this product can be purchased.
* **endDate**: The latest date time (exclusive) that this product can be purchased.

**EligibleForTopup**

Flag indicating whether the product can be topped up or not.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.payments.thalescloud.io/transit-digitization/get-started/concepts/fare-products.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.