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

# Migrating from v1

> What changed in v2 and how to upgrade your integration.

v2 keeps the same concepts as v1 but modernises authentication, ordering, and the catalog.
v1 remains available; migrate when you’re ready.

## Key changes

<CardGroup cols={2}>
  <Card title="API-key auth" icon="key">
    v2 uses a simple `x-api-key` header instead of bearer-token login/refresh.
  </Card>

  <Card title="Async ordering" icon="arrows-spin">
    Orders return immediately as `processing`; you poll for codes. No long, blocking requests.
  </Card>

  <Card title="Filtering & pagination" icon="filter">
    The catalog supports country/language/brand/category/tag filters and `skip`/`take` (max 100).
  </Card>

  <Card title="Wallet endpoint" icon="wallet">
    A dedicated `GET /v2/wallet` returns balances; order responses also embed a wallet snapshot.
  </Card>
</CardGroup>

## Endpoint mapping

| v1                                                 | v2                                       | Notes                                                                     |
| -------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------- |
| `POST /v1/orders/place-order` (sync, returns pins) | `POST /v2/orders` (async)                | Returns `orderId` + `processing`; poll for pins                           |
| `GET /v1/orders/retrieve-order?id=`                | `GET /v2/orders/{reference}`             | By UUID `orderId` **or** `externalOrderCode`; codes only when `completed` |
| `GET /v1/catalog/products`                         | `GET /v2/catalog/products`               | Adds filters + `skip`/`take` (max 100)                                    |
| `GET /v1/catalog/product?sku=`                     | `GET /v2/catalog/products/{productCode}` | Fetch by catalog `productCode`                                            |
| *(none)*                                           | `GET /v2/wallet`                         | New dedicated wallet endpoint                                             |

## Behavioural differences

<Warning>
  The biggest change: **ordering is asynchronous**. Code that expected pins in the
  `place-order` response must now poll `GET /v2/orders/{reference}` until `status` is
  `completed`. See [Order lifecycle](/concepts/order-lifecycle).
</Warning>

<Note>
  v2 identifies products by **`productCode`** - a stable 14-digit string identifier (for
  example `10020000213575`) used in order lines and product URLs. Internal numeric product
  ids are no longer exposed. productCodes are stable **and identical in sandbox and
  production**: integrate against sandbox, then switch the base URL and API key and the same
  productCodes work in production. Catalog responses also expose per-locale `sku` values.
  Pricing validation is unchanged for fixed products (price must match) and range-checked
  for [open-denomination](/concepts/open-denomination) products.
</Note>

<Note>
  v1 returned numeric order ids. v2 returns a UUID **`orderId`** (for example
  `b9f6f9a2-4d0a-4f5c-9a1e-7c2d8f3b6e10`) when you place an order. Poll
  `GET /v2/orders/{reference}` with that UUID or with your own `externalOrderCode` -
  numeric order ids are not accepted.
</Note>

## Response shape changes (v2.1)

| v1 / early v2                             | Current v2                                                       |
| ----------------------------------------- | ---------------------------------------------------------------- |
| Numeric product `id` / `productId`        | `productCode` (string) in catalog, order lines, and order status |
| Numeric order id                          | `orderId` as a UUID string                                       |
| `PIN` / `pin: [{ pin }]`                  | `codes: [{ code }]`                                              |
| `tags` as comma-separated string          | `tags` as `string[]`                                             |
| `rrp`, `rrpCurrency`, `state` on products | Removed - use `price` and `status`                               |

See the [Changelog](/changelog) for the full list.