Skip to main content

Get Order

Retrieve a specific order by its UUID or external ID.

Endpoint​

GET /api/v3/orders/{order_id}

Path Parameters​

ParameterTypeDescription
order_idstringOrder UUID or external ID

Query Parameters​

ParameterTypeDefaultDescription
id_typestringinternalinternal for UUID, external for external ID
includestring-Comma-separated: user, products, pending_checkout
fieldsstring-Comma-separated list of fields to return

Response Structure​

Base Response​

{
  "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​

{
  "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": "[email protected]"
    },
    "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​

{
  "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": "[email protected]"
    },
    "products": [...],
    "unit_price": 29.99,
    "currency_id": "USD",
    "pending_checkout": {
      "url": "https://yourstore.publica.la/auth/token?external-auth-token=eyJ...",
      "ttl": 3600
    }
  }
}
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​

FieldTypeDescription
idstringPublica.la internal order ID (numeric as string)
uuidstringPublica.la order UUID
external_idstringYour external order ID
typestringOrder type: permission, report, internal_report, sale
statusstringOrder status: pending, approved, paused, cancelled
unit_pricefloatOrder total amount
currency_idstringISO 4217 currency code
created_atstringISO 8601 creation timestamp
updated_atstringISO 8601 last update timestamp

User Object (include=user)​

FieldTypeDescription
idstringUser's internal ID (numeric as string)
uuidstringUser's UUID
external_idstringUser's external ID (your system)
emailstringUser's email address

Product Object (include=products)​

FieldTypeDescription
idstringProduct's internal ID (numeric as string)
external_idstringProduct's external ID (ISBN, SKU, etc.)
typestringcontent or subscription
namestringProduct name
statusstringProduct status in order
expiration_datestringAccess expiration (YYYY-MM-DD) or null
unit_pricefloatProduct price
currency_idstringISO 4217 currency code
cover_urlstringCover image URL (content only)
reader_urlstringDirect reader link (content only)
product_urlstringProduct page URL (content only)

Checkout Object (include=pending_checkout, sale orders only)​

FieldTypeDescription
urlstringCheckout redirect URL
ttlintegerURL validity in seconds

Examples​

Get by Internal ID (UUID)​

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​

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​

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​

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​

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)​

{
  "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)​

{
  "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​

X

Graph View