---
title: Identity (TypeID)
description: How Ledger uses prefix-qualified, globally unique identifiers for every billing entity.
---

Every entity in Ledger has a TypeID. TypeIDs are globally unique, sortable, URL-safe identifiers built on UUIDv7 with a human-readable prefix that tells you what kind of entity you're looking at.

A TypeID looks like this:

```
plan_01h455vb4pex5vsknk084sn02q
```

The `plan` prefix identifies this as a plan. The suffix is a base32-encoded UUIDv7 that encodes creation time, so IDs sort chronologically.

## The `id` package

The `id` package wraps the [TypeID Go library](https://github.com/jetify-com/typeid-go) (v2) with a single `ID` struct. All entity types share the same struct -- the prefix distinguishes them.

### Creating IDs

```go
import "github.com/xraph/ledger/id"

planID         := id.New(id.PrefixPlan)          // plan_01h455vb...
subscriptionID := id.New(id.PrefixSubscription)  // sub_01h455vb...
invoiceID      := id.New(id.PrefixInvoice)       // inv_01h455vb...
```

Convenience constructors: `id.NewPlanID()`, `id.NewFeatureID()`, `id.NewPriceID()`, `id.NewSubscriptionID()`, `id.NewUsageEventID()`, `id.NewEntitlementID()`, `id.NewInvoiceID()`, `id.NewLineItemID()`, `id.NewCouponID()`, `id.NewPaymentID()`.

### Parsing IDs

```go
parsed, err := id.Parse("plan_01h455vb4pex5vsknk084sn02q")
parsed, err := id.ParseWithPrefix("plan_01h455vb...", id.PrefixPlan)  // validates prefix
parsed, err := id.ParsePlanID("plan_01h455vb...")                     // convenience
```

### Nil ID

```go
var empty id.ID
empty.IsNil()  // true
empty.String() // ""
id.Nil.IsNil() // true
```

### Database storage

`id.ID` implements `Scanner` and `driver.Valuer`. Stores as a string, returns `NULL` for nil IDs.

### JSON serialization

`id.ID` implements `TextMarshaler` and `TextUnmarshaler`. Nil IDs serialize as empty strings.

## Prefix reference

| Constant | Prefix | Entity |
|----------|--------|--------|
| `id.PrefixPlan` | `plan` | Plan |
| `id.PrefixFeature` | `feat` | Feature |
| `id.PrefixPrice` | `price` | Price |
| `id.PrefixSubscription` | `sub` | Subscription |
| `id.PrefixUsageEvent` | `uevt` | Usage event |
| `id.PrefixEntitlement` | `ent` | Entitlement |
| `id.PrefixInvoice` | `inv` | Invoice |
| `id.PrefixLineItem` | `li` | Line item |
| `id.PrefixCoupon` | `cpn` | Coupon |
| `id.PrefixPayment` | `pay` | Payment |