Skip to main content

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​

FieldTypeDescription
typestringMust be "permission"
userobjectUser information
user.id or user.emailstringAt least one user identifier required
productsarrayProducts to grant access to
products[].typestringcontent or subscription
products[].external_idstringProduct's external ID (max 64 chars)

Optional Fields​

FieldTypeDescription
external_idstringYour unique order ID (max 64 chars)
products[].expiration_datestringAccess expiration (YYYY-MM-DD)
unit_pricefloatOptional price for record-keeping
currency_idstringISO 4217 currency code

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": "2025-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": "2025-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​

StatusErrorCause
401UnauthenticatedInvalid or missing API token
404Product not foundProduct external ID doesn't exist
422Validation errorMissing required fields
422Duplicate orderExternal reference already exists

Error Response Example​

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

See Also​

X

Graph View