Permission Orders

Permission orders grant content access without creating payment records. Use when you handle payments in your own system or for legacy access migration.

Creating a Permission Order

Endpoint

POST /integration-api/v1/orders

Required Fields

Field	Type	Description	Required
type	string	Must be "permission"	Yes
user	object	User information	Yes
user.id	string	User unique ID in your system (max 64 chars)	Yes (or email)
user.email	string	User's email address	Yes (or id)
products	array	Array of products to grant access to	Yes
products.*.type	string	Product type: content or subscription	Yes
products.*.id	string	Product unique ID in your system (max 64 chars)	Yes

Optional Fields

Field	Type	Description
external_reference	string	Your unique identifier for this order (max 64 chars)
products.*.expiration_date	string	Date when access expires (YYYY-MM-DD format)
unit_price	float	Optional price for record-keeping (not used for payment)
currency_id	string	Optional currency (ISO 4217 code)
products.*.name	string	Product name (not required, auto-retrieved if exists)
products.*.url	string	Product URL (not required)

Request Examples

Basic Permission Order

Grant access to a subscription and a content item:

{
  "type": "permission",
  "external_reference": "PROMO-2024-001",
  "user": {
    "id": "user-12345",
    "email": "[email protected]"
  },
  "products": [
    {
      "id": "MONTHLY-SUB",
      "type": "subscription"
    },
    {
      "id": "EBOOK-001",
      "type": "content"
    }
  ]
}

Permission Order with Expiration

Grant temporary access that expires on a specific date:

{
  "type": "permission",
  "external_reference": "FREE-TRIAL-789",
  "user": {
    "id": "trial-user-456",
    "email": "[email protected]"
  },
  "products": [
    {
      "id": "PREMIUM-PLAN",
      "type": "subscription",
      "expiration_date": "2025-12-31"
    }
  ]
}

Permission Order for New User

If the user doesn't exist, they will be created automatically:

{
  "type": "permission",
  "external_reference": "NEW-USER-GRANT",
  "user": {
    "id": "new-user-001",
    "email": "[email protected]"
  },
  "products": [
    {
      "id": "WELCOME-CONTENT",
      "type": "content"
    }
  ]
}

Response

Success Response (201 Created)

{
  "data": {
    "id": "03033649-de10-404b-aa8a-8682871001c2",
    "external_reference": "PROMO-2024-001",
    "type": "permission",
    "unit_price": 0,
    "currency_id": null,
    "status": "approved",
    "created_at": "2024-11-24",
    "user": {
      "id": "user-12345",
      "email": "[email protected]"
    },
    "products": [
      {
        "id": "MONTHLY-SUB",
        "type": "subscription",
        "name": "Monthly Premium Subscription",
        "status": "approved",
        "expiration_date": null,
        "cover": "https://cdn.publica.la/plan/monthly-cover.jpg",
        "reader_url": null,
        "unit_price": 0,
        "currency_id": null
      },
      {
        "id": "EBOOK-001",
        "type": "content",
        "name": "Digital Marketing Handbook",
        "status": "approved",
        "expiration_date": null,
        "cover": "https://cdn.publica.la/content/ebook-001.jpg",
        "reader_url": "https://yourstore.publica.la/reader/digital-marketing-handbook",
        "description": "Complete guide to digital marketing",
        "pages_quantity": 250,
        "file_type": "epub",
        "unit_price": 0,
        "currency_id": null
      }
    ]
  }
}

Response Fields

Field	Type	Description
id	string	Publica.la's unique order ID (UUID)
external_reference	string	Your unique ID for this order
type	string	Always "permission"
status	string	Always "approved" (immediate access)
user	object	User information
products	array	Products with access details
products[].status	string	Always "approved" for permission orders
products[].reader_url	string	Direct link to access the content

Managing Permission Orders

Retrieving Orders

# Get a specific permission order
GET /integration-api/v1/orders/{order_id}

# List all permission orders
GET /integration-api/v1/orders

Updating Orders

Update the expiration date for all products in a permission order.

Endpoint:

PUT /integration-api/v1/orders/{order_id}

Path Parameters:

Parameter	Description
order_id	The order's UUID (from id field) or external reference (from external_reference field)

Query Parameters:

Parameter	Type	Default	Description
id_type	string	internal	Use internal when order_id is a UUID, or external when it's an external reference

Request Body:

Field	Type	Description	Required
expiration_date	string	New expiration date (YYYY-MM-DD format)	Yes

Example - Update using UUID:

PUT /integration-api/v1/orders/648bb3b0-88da-4028-a3d5-325a3dc0c5c8?id_type=internal

{
  "expiration_date": "2025-12-31"
}

Example - Update using external reference:

PUT /integration-api/v1/orders/MY-ORDER-REF-123?id_type=external

{
  "expiration_date": "2025-12-31"
}

Response (200 OK): Returns the updated order with modified expiration date applied to all products.

Note: This endpoint updates the expiration date for ALL products in the order.

Canceling Orders

Remove user access by canceling the permission order.

Endpoint:

DELETE /integration-api/v1/orders/{order_id}

Request Fields:

Field	Type	Description	Required
reason	string	Cancellation reason (min: 3, max: 150 chars)	No
expiration_date	string	Effective cancellation date (YYYY-MM-DD format). If not provided, access is removed immediately.	No

Example Request:

{
  "reason": "User requested cancellation",
  "expiration_date": "2024-12-01"
}

Response (200 OK): Returns the cancelled order with updated status.

Error Handling

Common Errors

Status Code	Error	Cause
400	Invalid product ID	Product doesn't exist in your catalog
401	Unauthorized	Invalid or missing API token
422	Validation error	Missing required fields or invalid format

Error Response Example

{
  "status": 422,
  "errors": [
    {
      "title": "The products.0.id field has invalid data",
      "details": [
        "The product does not exist, please check the ID"
      ]
    }
  ]
}

Related Documentation

• Overview - Compare all order types
• Report Orders - Assign content + record payment
• Sale Orders - Publica.la checkout flow
• API Authentication - Authentication setup