> ## Documentation Index > Fetch the complete documentation index at: https://docs.publica.la/llms.txt > Use this file to discover all available pages before exploring further. # Get Order Retrieve a specific order by its UUID or external ID. ## Endpoint ``` GET /api/v3/orders/{order_id} ``` --- ## Path Parameters | Parameter | Type | Description | | ---------- | ------ | ------------------------- | | `order_id` | string | Order UUID or external ID | --- ## Query Parameters | Parameter | Type | Default | Description | | --------- | ------ | ---------- | ------------------------------------------------------- | | `id_type` | string | `internal` | `internal` for UUID, `external` for external ID | | `include` | string | - | Comma-separated: `user`, `products`, `pending_checkout` | | `fields` | string | - | Comma-separated list of fields to return | --- ## Response Structure ### Base Response ```json { "data": { "id": "12345", "uuid": "275ca6c4-a815-4f64-8198-759a296dd495", "external_id": "ORDER-123", "type": "permission", "status": "approved", "unit_price": 29.99, "currency_id": "USD", "created_at": "2025-12-03T22:43:44.000000Z", "updated_at": "2025-12-03T22:43:44.000000Z" } } ``` ### Full Response with All Includes ```json { "data": { "id": "12345", "uuid": "275ca6c4-a815-4f64-8198-759a296dd495", "external_id": "ORDER-123", "type": "permission", "status": "approved", "created_at": "2025-12-03T22:43:44.000000Z", "updated_at": "2025-12-03T22:43:44.000000Z", "user": { "id": "67890", "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "external_id": "user-ext-123", "email": "customer@example.com" }, "products": [ { "id": "54321", "external_id": "9781234567890", "type": "content", "name": "Digital Marketing Handbook", "status": "approved", "expiration_date": "2026-12-31", "unit_price": 29.99, "currency_id": "USD", "cover_url": "https://cdn.publica.la/covers/book.jpg", "reader_url": "https://yourstore.publica.la/reader/digital-marketing", "product_url": "https://yourstore.publica.la/library/publication/digital-marketing" } ], "unit_price": 29.99, "currency_id": "USD" } } ``` ### Response for Pending Sale Order with Checkout ```json { "data": { "id": "12346", "uuid": "4db50ffb-80fd-42b1-9bdb-c572e1a5487f", "external_id": "SALE-123", "type": "sale", "status": "pending", "created_at": "2025-12-03T22:44:07.000000Z", "updated_at": "2025-12-03T22:44:07.000000Z", "user": { "id": "67890", "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "external_id": "sale-user-123", "email": "customer@example.com" }, "products": [...], "unit_price": 29.99, "currency_id": "USD", "pending_checkout": { "url": "https://yourstore.publica.la/auth/token?external-auth-token=eyJ...", "ttl": 3600 } } } ``` :::note Checkout URL The `pending_checkout` object is included for any order with `pending` status when `include=pending_checkout` is requested. Useful for recovering abandoned checkouts. The URL expires after the TTL period (in seconds). **Important:** Before sending a checkout recovery link, verify the user hasn't already purchased the same products in a different order. ::: --- ## Field Reference ### Core Fields | Field | Type | Description | | ------------- | ------ | ------------------------------------------------------------- | | `id` | string | Publica.la internal order ID (numeric as string) | | `uuid` | string | Publica.la order UUID | | `external_id` | string | Your external order ID | | `type` | string | Order type: `permission`, `report`, `internal_report`, `sale` | | `status` | string | Order status: `pending`, `approved`, `paused`, `cancelled` | | `unit_price` | float | Order total amount | | `currency_id` | string | ISO 4217 currency code | | `created_at` | string | ISO 8601 creation timestamp | | `updated_at` | string | ISO 8601 last update timestamp | ### User Object (include=user) | Field | Type | Description | | ------------- | ------ | -------------------------------------- | | `id` | string | User's internal ID (numeric as string) | | `uuid` | string | User's UUID | | `external_id` | string | User's external ID (your system) | | `email` | string | User's email address | ### Product Object (include=products) | Field | Type | Description | | ----------------- | ------ | ----------------------------------------- | | `id` | string | Product's internal ID (numeric as string) | | `external_id` | string | Product's external ID (ISBN, SKU, etc.) | | `type` | string | `content` or `subscription` | | `name` | string | Product name | | `status` | string | Product status in order | | `expiration_date` | string | Access expiration (YYYY-MM-DD) or null | | `unit_price` | float | Product price | | `currency_id` | string | ISO 4217 currency code | | `cover_url` | string | Cover image URL (content only) | | `reader_url` | string | Direct reader link (content only) | | `product_url` | string | Product page URL (content only) | ### Checkout Object (include=pending_checkout, sale orders only) | Field | Type | Description | | ----- | ------- | ----------------------- | | `url` | string | Checkout redirect URL | | `ttl` | integer | URL validity in seconds | --- ## Examples ### Get by Internal ID (UUID) ```bash curl -X GET "https://yourstore.publica.la/api/v3/orders/275ca6c4-a815-4f64-8198-759a296dd495" \ -H "X-User-Token: your-api-token" \ -H "Accept: application/json" ``` ### Get by External ID ```bash curl -X GET "https://yourstore.publica.la/api/v3/orders/ORDER-123?id_type=external" \ -H "X-User-Token: your-api-token" ``` ### With User and Products ```bash curl -X GET "https://yourstore.publica.la/api/v3/orders/275ca6c4-a815-4f64-8198-759a296dd495?include=user,products" \ -H "X-User-Token: your-api-token" ``` ### Get Sale Order with Checkout URL ```bash curl -X GET "https://yourstore.publica.la/api/v3/orders/4db50ffb-80fd-42b1-9bdb-c572e1a5487f?include=user,products,pending_checkout" \ -H "X-User-Token: your-api-token" ``` ### Sparse Fieldsets ```bash curl -X GET "https://yourstore.publica.la/api/v3/orders/275ca6c4-a815-4f64-8198-759a296dd495?fields=id,status,type" \ -H "X-User-Token: your-api-token" ``` --- ## Error Responses ### Order Not Found (404) ```json { "message": "Order not found." } ``` This occurs when: - The UUID doesn't exist - The external ID doesn't exist (with `id_type=external`) - The order belongs to a different tenant ### Invalid Include (422) ```json { "message": "The given data was invalid.", "errors": { "include": [ "Invalid include: invalid. Allowed: user, products, pending_checkout" ] } } ``` --- ## Best Practices 1. **Use external IDs** - Store orders with your external IDs for easy lookup 2. **Request only needed includes** - Reduce payload size and response time 3. **Cache responses** - Order data changes infrequently after creation 4. **Handle 404 gracefully** - Orders may be deleted or belong to other tenants --- ## See Also - [List Orders](./orders-v3-list.md) - Query multiple orders - [Update Order](./orders-v3-update-cancel.md) - Modify order expiration - [Overview](./orders-v3-overview.md) - API overview