Quick Start

Add the mixin to your model

# models.py
import uuid
from django.db import models
from django_display_ids import DisplayIDModel

class Invoice(DisplayIDModel, models.Model):
    display_id_prefix = "inv"
    uuid_field = "uuid"
    uuid = models.UUIDField(default=uuid.uuid7, unique=True)
    slug = models.SlugField(unique=True)

This registers the prefix and adds a display_id property to your model instances.

Note

uuid.uuid7 requires Python 3.14+. For earlier versions, use uuid.uuid4.

Update your URLconf

# urls.py
from django.urls import path, register_converter
from django_display_ids import DisplayIDOrUUIDOrSlugConverter

register_converter(DisplayIDOrUUIDOrSlugConverter, "identifier")

urlpatterns = [
    path("invoices/<identifier:id>/", InvoiceDetailView.as_view()),
]

Tip

Using <str:id> also works but accepts any string. Path converters validate the format at the routing layer, returning 404 for invalid formats. See URL Path Converters for all available converters.

Add the mixin to your view

# Django CBV
from django.views.generic import DetailView
from django_display_ids import DisplayIDMixin

class InvoiceDetailView(DisplayIDMixin, DetailView):
    model = Invoice
    lookup_param = "id"

# Django REST Framework
from rest_framework.viewsets import ModelViewSet
from django_display_ids.contrib.rest_framework import DisplayIDMixin

class InvoiceViewSet(DisplayIDMixin, ModelViewSet):
    queryset = Invoice.objects.all()
    serializer_class = InvoiceSerializer
    lookup_url_kwarg = "id"

Your views now accept:

  • inv_2aUyqjCzEIiEcYMKj7TZtw (display ID)

  • 550e8400-e29b-41d4-a716-446655440000 (UUID)

  • my-invoice (slug)

What’s Happening

  1. DisplayIDModel registers the prefix on the model

  2. The path converter validates the identifier format in the URL

  3. lookup_param / lookup_url_kwarg tells the view mixin which URL parameter to read

  4. The view mixin auto-detects display_id_prefix from the model

  5. The default lookup_strategies tries display IDs, UUIDs, and slugs (in that order)

The mixin decodes the identifier and looks up the object by UUID (or slug).

Next Steps