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 for guidance on when to use permission orders.

---

Creating a Permission Order

Endpoint

POST /api/v3/orders

Request Body

{
  "type": "permission",
  "external_id": "YOUR-UNIQUE-REF",
  "user": {
    "id": "user-external-id",
    "email": "[email protected]"
  },
  "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

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, which still accepts past dates.

---

Request Examples

Basic Permission Order

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": "[email protected]"
    },
    "products": [
      {
        "external_id": "9781234567890",
        "type": "content"
      }
    ]
  }'

Permission Order with Expiration

Grant temporary access that expires on a specific date:

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": "[email protected]"
    },
    "products": [
      {
        "external_id": "PREMIUM-PLAN",
        "type": "subscription",
        "expiration_date": "2026-12-31"
      }
    ]
  }'

Permission Order with Multiple Products

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

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

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:

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

Best Practice

Always provide both user.id and user.email for reliable user matching across systems.

---

Managing Permission Orders

Retrieve Order

# 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

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

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

{
  "message": "The given data was invalid.",
  "errors": {
    "products.0.external_id": ["The product does not exist."]
  }
}

---

See Also

• Report Orders - External sales with payment records
• Sale Orders - Publica.la checkout flow
• Update & Cancel - Manage existing orders
• List Orders - Query orders