> For the complete documentation index, see [llms.txt](https://docs.tebex.io/developers/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tebex.io/developers/headless-api/package-idents.md).

# Package Idents

Every package returned by the Headless API now has an `ident`: a string identifier that works for every package type.

Use it to refer to a package ( `packageId` ) whether you're fetching it or managing it in a basket.

{% hint style="info" %}
A numeric package `id` on a package can also work for identifying standard packages. We recommend switching to `ident` if you are using the numeric `id`.
{% endhint %}

### What an ident looks like

`ident` is returned on every package from these endpoints:

* `GET /packages`
* `GET /categories` and `GET /categories/{categoryId}` with `includePackages=1`
* `GET /packages/{packageId}`

```json
{
  "data": {
    "id": 456,
    "ident": "pkg_12_456",
    "name": "VIP Rank",
    "category": { "id": 12, "name": "Ranks" },
    ...
  }
}
```

Idents have the form `{prefix}_{categoryId}_{id}`:

| Prefix | Package type | Example               |
| ------ | ------------ | --------------------- |
| `pkg`  | Standard     | `pkg_12_456`          |
| `dyn`  | Dynamic      | `dyn_34_10`           |
| `ext`  | External     | `ext_10_{asset-uuid}` |

{% hint style="warning" %}
Store the package **`ident`** and use it in requests exactly as you received it - don't build idents yourself as the format may change.
{% endhint %}

#### External packages

For external packages, always use `ident`.

### Where you can use an ident

You can send an ident anywhere these endpoints take a package ID.

#### Get a package

```http
GET https://headless.tebex.io/api/accounts/{token}/packages/{packageId}
```

`{packageId}` can be an ident or a numeric ID:

```http
GET https://headless.tebex.io/api/accounts/{token}/packages/pkg_12_456
```

#### Add a package to a basket

```http
POST https://headless.tebex.io/api/baskets/{basketIdent}/packages
```

```json
{
  "package_id": "pkg_12_456",
  "quantity": 1
}
```

`package_id` can be an ident or a numeric ID. For external packages, it must be the ident.

#### Remove a package from a basket

```http
POST https://headless.tebex.io/api/baskets/{basketIdent}/packages/remove
```

```json
{
  "package_id": "pkg_12_456"
}
```

#### Update a package's quantity

```http
PUT https://headless.tebex.io/api/baskets/{basketIdent}/packages/{packageId}
```

```json
{
  "quantity": 2
}
```

`{packageId}` can be an ident or a numeric ID, for example `/packages/pkg_12_456`.

### Errors

When adding a package to a basket:

| Cause                                                                                            | Response                                                      |
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |
| `package_id` isn't a valid package ID or ident                                                   | Validation error: `package_id must be a package ID or ident.` |
| The ident doesn't match a package in your store, or doesn't match the package's category or type | `400` `The selected id is invalid.`                           |

### Migrating from numeric IDs

1. Read `ident` from package responses wherever you currently read `id`.
2. Store `ident` in place of, or alongside, the numeric ID.
3. Send `ident` as `package_id` or `{packageId}` in the requests above.

Standard packages continue to accept numeric IDs, so you can migrate gradually. Support for external packages requires `ident`.
