> ## 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. # Permission Orders Grant content access without creating payment records. Use when you process payments externally and only need Publica.la for content delivery. See [Choosing the Right Order Type](../orders-v3-overview.md#choosing-the-right-order-type) for guidance on when to use permission orders. --- ## Creating a Permission Order ### Endpoint ``` POST /api/v3/orders ``` ### Request Body ```json { "type": "permission", "external_id": "YOUR-UNIQUE-REF", "user": { "id": "user-external-id", "email": "customer@example.com" }, "products": [ { "type": "content", "external_id": "product-external-id", "expiration_date": "2026-12-31" } ] } ``` ### Required Fields | Field | Type | Description | | ------------------------- | ------ | ------------------------------------- | | `type` | string | Must be `"permission"` | | `user` | object | User information | | `user.id` or `user.email` | string | At least one user identifier required | | `products` | array | Products to grant access to | | `products[].type` | string | `content` or `subscription` | | `products[].external_id` | string | Product's external ID (max 64 chars) | ### Optional Fields | Field | Type | Description | | ---------------------------- | ------ | --------------------------------------------------------------------------------- | | `external_id` | string | Your unique order ID (max 64 chars) | | `products[].expiration_date` | string | Access expiration (YYYY-MM-DD). Must be later than today in your store's timezone | | `unit_price` | float | Optional price for record-keeping | | `currency_id` | string | ISO 4217 currency code | :::caution Expiration dates must be in the future `expiration_date` must be later than the current day in your store's timezone, so the earliest value you can send is tomorrow. Today's date and past dates return `422` with "The expiration date must be a future date". To end access on an order that already exists, use [Update & Cancel](../orders-v3-update-cancel.md), which still accepts past dates. ::: --- ## Request Examples ### Basic Permission Order ```bash curl -X POST "https://yourstore.publica.la/api/v3/orders" \ -H "X-User-Token: your-api-token" \ -H "Content-Type: application/json" \ -d '{ "type": "permission", "external_id": "PROMO-2024-001", "user": { "id": "user-12345", "email": "customer@example.com" }, "products": [ { "external_id": "9781234567890", "type": "content" } ] }' ``` ### Permission Order with Expiration Grant temporary access that expires on a specific date: ```bash curl -X POST "https://yourstore.publica.la/api/v3/orders" \ -H "X-User-Token: your-api-token" \ -H "Content-Type: application/json" \ -d '{ "type": "permission", "external_id": "FREE-TRIAL-789", "user": { "id": "trial-user-456", "email": "trial@example.com" }, "products": [ { "external_id": "PREMIUM-PLAN", "type": "subscription", "expiration_date": "2026-12-31" } ] }' ``` ### Permission Order with Multiple Products ```bash curl -X POST "https://yourstore.publica.la/api/v3/orders" \ -H "X-User-Token: your-api-token" \ -H "Content-Type: application/json" \ -d '{ "type": "permission", "external_id": "BUNDLE-GRANT-001", "user": { "email": "customer@example.com" }, "products": [ { "external_id": "EBOOK-001", "type": "content" }, { "external_id": "EBOOK-002", "type": "content" }, { "external_id": "MONTHLY-SUB", "type": "subscription", "expiration_date": "2026-06-30" } ] }' ``` --- ## Response ### Success Response (201 Created) ```json { "data": { "id": "12345", "uuid": "275ca6c4-a815-4f64-8198-759a296dd495", "external_id": "PROMO-2024-001", "type": "permission", "status": "approved", "unit_price": 0, "currency_id": null, "created_at": "2025-12-03T22:43:44.000000Z", "updated_at": "2025-12-03T22:43:44.000000Z" } } ``` :::note Immediate Access Permission orders are created with `status: approved`. Users can access content immediately after order creation. ::: ### Full Response with Includes Request with `?include=user,products`: ```json { "data": { "id": "12345", "uuid": "275ca6c4-a815-4f64-8198-759a296dd495", "external_id": "PROMO-2024-001", "type": "permission", "status": "approved", "unit_price": 0, "currency_id": null, "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-12345", "email": "customer@example.com" }, "products": [ { "id": "54321", "external_id": "9781234567890", "type": "content", "name": "Digital Marketing Handbook", "status": "approved", "expiration_date": null, "unit_price": null, "currency_id": null, "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" } ] } } ``` --- ## User Auto-Creation If the user doesn't exist, they will be created automatically: - With `user.id` only: User created with external ID - With `user.email` only: User created with email, ID auto-generated - With both: User created with both identifiers :::tip Best Practice Always provide both `user.id` and `user.email` for reliable user matching across systems. ::: --- ## Managing Permission Orders ### Retrieve Order ```bash # By internal UUID 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" # By external reference curl -X GET "https://yourstore.publica.la/api/v3/orders/PROMO-2024-001?id_type=external&include=user,products" \ -H "X-User-Token: your-api-token" ``` ### Update Expiration ```bash curl -X PUT "https://yourstore.publica.la/api/v3/orders/275ca6c4-a815-4f64-8198-759a296dd495" \ -H "X-User-Token: your-api-token" \ -H "Content-Type: application/json" \ -d '{ "expiration_date": "2026-12-31" }' ``` ### Cancel Order ```bash curl -X DELETE "https://yourstore.publica.la/api/v3/orders/275ca6c4-a815-4f64-8198-759a296dd495" \ -H "X-User-Token: your-api-token" \ -H "Content-Type: application/json" \ -d '{ "reason": "User requested cancellation" }' ``` --- ## Error Handling ### Common Errors | Status | Error | Cause | | ------ | --------------------------------- | ------------------------------------------------------------- | | 401 | Unauthenticated | Invalid or missing API token | | 404 | Product not found | Product external ID doesn't exist | | 422 | Validation error | Missing required fields | | 422 | Duplicate order | External reference already exists | | 422 | Expiration date not in the future | `expiration_date` is today or earlier in the store's timezone | ### Error Response Example ```json { "message": "The given data was invalid.", "errors": { "products.0.external_id": ["The product does not exist."] } } ``` --- ## See Also - [Report Orders](./orders-v3-report.md) - External sales with payment records - [Sale Orders](./orders-v3-sale.md) - Publica.la checkout flow - [Update & Cancel](../orders-v3-update-cancel.md) - Manage existing orders - [List Orders](../orders-v3-list.md) - Query orders