# Search offers

import { Link } from "zudoku/components";
import { Card, CardDescription } from "zudoku/ui/Card";

:::lead
This guide gets you from zero to your first Sales v2 :def[sales-v2-offer|offer].
:::

:::note

Eager to start experimenting with code? Explore the Sales v2 API spec directly at `https://developer.entur.no/apis/sales/latest/openapi.json` (does not require auth).

:::

## Before you begin
To use this guide, you need to:

- Be an authorised Entur partner.
- Have OAuth2 client credentials (`client_id` and `client_secret`).
- Have header values for :def[Entur-Distribution-Channel] and :def[Entur-POS].
- Use the Sales v2 dev base URL `https://api.dev.entur.io/sales/v2`.

:::info

See [Authentication](/docs/authentication#partner-apis).

:::

## 1. Specify who is travelling
When searching for offers, Sales v2 supports two traveller models:

- `individual_traveller`: an identifiable traveller (with specific attributes such as age, name, and possibly other personal details).
- `user_profile`: an anonymous traveller profile with a count.

You can use one of them, or both in the same request.

Both models require an `id` that you supply. It can be any string up to 200 characters, so you can reuse IDs from your own system.

Sales v2 keeps these IDs throughout the purchase. You refer to them as `travellerId` when you update or remove a traveller in a draft package.

```json
{
  "travellers": [
    {
      "type": "individual_traveller",
      "id": "9f7f69ec-d68c-4751-8ec4-fd059f820cb8",
      "age": 30
    }
  ],
  "profiles": [
    {
      "type": "user_profile",
      "id": "1c9b2b5a-f291-404b-8235-50641ef2b733",
      "ageGroup": "ADULT",
      "count": 1
    }
  ]
}
```

## 2. Search for your first offer
Use the `search-offers` process to send your first request.

::endpoint[sales/searchOfferHandler]

### Using place references

Sales v2 supports several place models in `specification`, most commonly:

- Fare zones (`ORG:FareZone:*`)
- Stop places (`NSR:StopPlace:*`)
- GPS coordinates (`GPS:lat,long[,alt]`)

Searching with zones or stop places is a common way to search for simple single-product offers, typically to let the user purchase a single ticket in a specific zone or set of zones.

:::info

These place references are used throughout the Entur platform and are based on :def[NeTEx] concepts. Read about the :def[FareZone] and :def[StopPlace] concepts, or see all accepted formats for Sales v2 :def[sales-v2-place-id|Place ID].

:::

```json
{
  "inputs": {
    "type": "search_offer",
    "specification": {
      "from": {
        "placeId": "ORG:FareZone:1"
      },
      "to": {
        "placeId": "ORG:FareZone:3"
      },
      "startTime": "2026-07-17T14:46:00.000Z"
    },
    "travellers": [
      {
        "id": "9f7f69ec-d68c-4751-8ec4-fd059f820cb8",
        "type": "individual_traveller",
        "fullName": "Ola Nordmann",
        "age": 30
      }
    ]
  }
}
```

:::note

Use `FareZone` in your application. Sales v2 does not support the deprecated spelling `TariffZone`, which some other Entur services still accept.

:::

### Using trip patterns from Journey Planner

You can also use a TripPattern from the Entur Journey Planner to search for offers, which is often the preferred way to search for offers.

```json
{
  "inputs": {
    "type": "search_offer",
    "travellers": [
      {
        "id": "9f7f69ec-d68c-4751-8ec4-fd059f820cb8",
        "type": "individual_traveller",
        "age": 30
      }
    ],
    "pattern": [
      {
        "serviceJourney": "KOL:ServiceJourney:3010_250903083240427_1014",
        "date": "2026-07-17",
        "from": {
          "placeId": "NSR:StopPlace:61355",
          "name": "Haugesund bussterminal"
        },
        "to": {
          "placeId": "NSR:StopPlace:28230",
          "name": "Austre Karmøyveg"
        }
      }
    ]
  }
}
```

:::note

When using a `TripPattern`, the client is responsible for the integration with Entur's [Journey Planner](/docs/open-services/journey-planner) and any use of Entur's [Geocoder API](/docs/open-services/geocoder) for autocompletion or reverse geocoding.

:::


## 3. Understand the response
Confirm that:

- The request returns HTTP `200`.
- The response contains at least one :def[sales-v2-offer|offer].
- Returned offers match expected :def[sales-v2-place-id|place ID]s and traveller inputs.

### Example response
```json
{
  "type": "OfferCollection",
  "offers": [
    {
      "id": "a3509357-b5c2-4c7d-910a-11e638d48f4b",
      "type": "offer",
      "properties": {
        "legs": [
          {
            "id": "a3509357-b5c2-4c7d-910a-11e638d48f4b",
            "type": "leg",
            "sequenceNumber": 1,
            "traveller": "9f7f69ec-d68c-4751-8ec4-fd059f820cb8",
            "state": "NOT_STARTED",
            "price": {
              "amount": 354.0,
              "currencyCode": "NOK"
            },
            "products": [
              "ORG:PreassignedFareProduct:4e913d65"
            ]
          }
        ],
        "products": [
          {
            "type": "product",
            "productId": {
              "productId": "ORG:PreassignedFareProduct:4e913d65",
              "name": "Operator X 7-day ticket"
            },
            "productName": "Operator X 7-day ticket"
          }
        ],
        "price": {
          "amount": 354.0,
          "currencyCode": "NOK"
        }
      }
    }
  ]
}
```

Sales v2 returns offers with Leg objects, even for simple `Zone`-`Zone` or `StopPlace`-`StopPlace` searches. In these cases, the leg represents a single traveller on a single product. To see which traveller belongs to which product, check the legs.

### Troubleshooting tips
- If you receive an empty `offers` array, check that your `specification` parameters (place IDs, time range) align with available data in the dev environment.
- Common errors are invalid place IDs, duplicate traveller IDs, and missing required fields or headers.
- If requests fail with `401` or `403`, check that your OAuth2 token is valid and has the scopes for Sales v2, and that the headers match your distribution channel and POS.
- If you need help, contact Entur support with your request and response. Include the `X-Correlation-ID` response header so we can trace the request.

## Next steps

<div className="grid grid-cols-1 md:grid-cols-2 gap-4 not-prose my-4">
  <Card className="p-6 gap-2 rounded">
    <p className="text-xs uppercase tracking-widest text-muted-foreground font-medium">Guide</p>
    <Link to="/guides/sales-v2/make-first-purchase" className="text-base font-bold! underline text-foreground!">Make your first purchase</Link>
    <CardDescription>Prepare, pay for, and confirm a package from one of the offers in the response.</CardDescription>
  </Card>
  <Card className="p-6 gap-2 rounded">
    <p className="text-xs uppercase tracking-widest text-muted-foreground font-medium">API reference</p>
    <Link to="/apis/sales" className="text-base font-bold! underline text-foreground!">Sales v2 API reference</Link>
    <CardDescription>The full list of processes and collections.</CardDescription>
  </Card>
</div>

:::note[Coming soon]
- Apply discounts for eligible travellers, such as students and employees, with `entitlements`.
- Search for a group of travellers.
:::
