# Make your first purchase

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

:::lead
This guide takes you from a Sales v2 offer to a paid and confirmed package.
:::

## Before you begin

To use this guide, you need to:

- Complete the [Search offers guide](/guides/sales-v2/search-offers) and keep an offer ID from the response.
- Use the Sales v2 dev base URL `https://api.dev.entur.io/sales/v2`.

:::info

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

:::

## Choose a purchase flow

Sales v2 supports two ways to prepare an offer for purchase:

- Use `purchase-offers` to turn one or more offer IDs directly into a purchase-ready package.
- Use `select-offers` to create a draft package, make any required changes, then use `purchase-package` to make it purchase-ready.

Both flows continue with external payment and `confirm-package`. Use the direct flow for your first purchase. Use the custom draft flow when you need to add travellers, ancillary products, or assets before payment.

## Prepare a package directly

Send the offer ID from your `search-offers` response to the `purchase-offers` process. This skips the custom draft steps and returns a purchase-ready package.

::endpoint[sales/purchaseOffersProcessHandler]

```json
{
  "inputs": {
    "type": "purchase_offers",
    "offerIds": [
      "a3509357-b5c2-4c7d-910a-11e638d48f4b"
    ]
  }
}
```

The response contains the resulting :def[sales-v2-package|package]. Store its `id` for payment and confirmation.

```json
{
  "type": "package",
  "id": "D92YGB7L",
  "status": "PENDING",
  "price": {
    "amount": 354,
    "currencyCode": "NOK"
  },
  "offers": [
    {
      "type": "offer",
      "id": "a3509357-b5c2-4c7d-910a-11e638d48f4b"
    }
  ]
}
```

Continue with [Take payment](#take-payment).

## Prepare a custom package

Use this flow when you must change the package before payment.

### Select the offer

Send the offer ID to the `select-offers` process. The response contains a draft package.

::endpoint[sales/selectOffersHandler]

```json
{
  "inputs": {
    "type": "select_offers",
    "offerIds": [
      "a3509357-b5c2-4c7d-910a-11e638d48f4b"
    ]
  }
}
```

Keep the returned package `id`. You need it to purchase the package.

```json
{
  "type": "package",
  "id": "D92YGB7L",
  "status": "SELECTED",
  "price": {
    "amount": 354,
    "currencyCode": "NOK"
  },
  "offers": [
    {
      "type": "offer",
      "id": "a3509357-b5c2-4c7d-910a-11e638d48f4b"
    }
  ]
}
```

### Customise the package

Make any required changes while the package is in the draft sales phase. Depending on the offer and mobility operator, you can:

- Add or update travellers.
- Add ancillary products with `assign-ancillary`.
- Add assets with `assign-asset`.

Check the package response and the API specification before presenting an option to the customer.

### Make the package purchase-ready

After making the required draft changes, send the package ID to the `purchase-package` process. This makes the package ready for payment.

::endpoint[sales/purchasePackageProcessHandler]

```json
{
  "inputs": {
    "type": "package",
    "packageId": "D92YGB7L"
  }
}
```

The response contains the purchase-ready package.

```json
{
  "type": "package",
  "id": "D92YGB7L",
  "status": "PENDING",
  "price": {
    "amount": 354,
    "currencyCode": "NOK"
  },
  "offers": [
    {
      "type": "offer",
      "id": "a3509357-b5c2-4c7d-910a-11e638d48f4b"
    }
  ]
}
```

## Take payment

Take payment through your payment integration. Payment happens outside Sales v2, either with your chosen PSP or the Entur [Payment API](/apis/payment-partner).

Keep the package ID with the payment transaction. Continue only after payment succeeds.

## Confirm the package

Send the paid package ID to the `confirm-package` process. The process is idempotent. If a request times out, retry with the same package ID without creating a duplicate purchase.

::endpoint[sales/confirmPackageProcessHandler]

```json
{
  "inputs": {
    "type": "package",
    "packageId": "D92YGB7L"
  }
}
```

The response contains the confirmed package.

```json
{
  "type": "package",
  "id": "D92YGB7L",
  "status": "CONFIRMED",
  "price": {
    "amount": 354,
    "currencyCode": "NOK"
  },
  "offers": [
    {
      "type": "offer",
      "id": "a3509357-b5c2-4c7d-910a-11e638d48f4b"
    }
  ]
}
```

Retrieve the package by ID if you need to check its latest status.

::endpoint[sales/getPackage]

Confirm that:

- The request returns HTTP `200`.
- The package `id` matches the package returned by the purchase process.
- The package status is `CONFIRMED`.
- The price and offers match the purchase.

:::warning

Do not confirm the purchase to the customer before the package status is `CONFIRMED`.

:::

## Troubleshoot the purchase

- If the offer is no longer valid, run `search-offers` again and purchase a new offer.
- If the package is `EXPIRED`, create a new package from a current offer.
- If `confirm-package` returns `409 ORDER_NOT_SETTLED`, payment has not settled yet. The package stays `PENDING`. Wait for payment to succeed, then retry.
- If a request returns `423 PACKAGE_LOCKED`, another request is modifying the package. Retry shortly.
- If a request returns `401` or `403`, check the access token and partner permissions.
- If a request fails unexpectedly, include the `X-Correlation-ID` response header when contacting Entur support.

## Next steps

After confirming the purchase, retrieve and deliver the travel documents for the package.

<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">API reference</p>
    <Link to="/apis/sales" className="text-base font-bold! underline text-foreground!">Sales v2 API reference</Link>
    <CardDescription>Find the <code>travel-documents</code> collection and the processes for changes, cancellations, and refunds.</CardDescription>
  </Card>
  <Card className="p-6 gap-2 rounded">
    <p className="text-xs uppercase tracking-widest text-muted-foreground font-medium">Documentation</p>
    <Link to="/docs/partner-services/sales-v2/new-integration#sales-lifecycle" className="text-base font-bold! underline text-foreground!">Sales lifecycle</Link>
    <CardDescription>How a sale moves through Sales v2.</CardDescription>
  </Card>
</div>
