Report Orders

Report orders assign content access and create payment records in Publica.la's financial system. Use for marketplace content sales (requires support enablement) or when you need financial tracking for externally processed sales.

Creating a Report Order

Endpoint

POST /integration-api/v1/orders

Required Fields

Field	Type	Description	Required
`type`	string	Must be `"report"`	Yes
`return_url`	string	URL for redirection (informational)	Yes
`unit_price`	float	Total order price	Yes
`currency_id`	string	Order currency (ISO 4217 code: USD, ARS, etc.)	Yes
`user`	object	User information	Yes
`user.id`	string	User unique ID (max 64 chars)	Yes (or email)
`user.email`	string	User's email address	Yes (or id)
`products`	array	Array of products in the order	Yes
`products.*.id`	string	Product unique ID (max 64 chars)	Yes
`products.*.type`	string	Product type: `content` or `subscription`	Yes
`products.*.unit_price`	float	Individual product price	Yes
`products.*.currency_id`	string	Product currency (ISO 4217 code)	Yes

Optional Fields

Field	Type	Description
`external_reference`	string	Your unique order identifier (max 64 chars)
`products.*.name`	string	Product name (required for auto-creation)
`products.*.url`	string	Product URL (required for auto-creation)
`products.*.expiration_date`	string	Access expiration date (YYYY-MM-DD)

Request Examples

Basic Report Order

Selling marketplace content through external POS:

{
  "type": "report",
  "external_reference": "POS-MARKETPLACE-12345",
  "return_url": "https://yourstore.publica.la/order/receipt/12345",
  "unit_price": 25.00,
  "currency_id": "USD",
  "user": {
    "id": "customer-789",
    "email": "[email protected]"
  },
  "products": [
    {
      "id": "MARKETPLACE-EBOOK",
      "type": "content",
      "name": "Third-Party Content",
      "url": "https://example.com/products/marketplace-content",
      "unit_price": 25.00,
      "currency_id": "USD"
    }
  ]
}

Result:

Payment recorded: $25.00
Content access granted immediately
Financial records created for accounting

Report Order with Multiple Products

{
  "type": "report",
  "external_reference": "PARTNER-BUNDLE-456",
  "return_url": "https://partner.com/sales/456",
  "unit_price": 45.00,
  "currency_id": "USD",
  "user": {
    "id": "partner-customer-123",
    "email": "[email protected]"
  },
  "products": [
    {
      "id": "EBOOK-001",
      "type": "content",
      "name": "Book Volume 1",
      "unit_price": 15.00,
      "currency_id": "USD"
    },
    {
      "id": "EBOOK-002",
      "type": "content",
      "name": "Book Volume 2",
      "unit_price": 15.00,
      "currency_id": "USD"
    },
    {
      "id": "EBOOK-003",
      "type": "content",
      "name": "Book Volume 3",
      "unit_price": 15.00,
      "currency_id": "USD"
    }
  ]
}

Report Order with Subscription

{
  "type": "report",
  "external_reference": "PARTNER-SUB-789",
  "return_url": "https://partner.com/subscription/confirmation",
  "unit_price": 120.00,
  "currency_id": "EUR",
  "user": {
    "id": "corporate-client-456",
    "email": "[email protected]"
  },
  "products": [
    {
      "id": "ANNUAL-ENTERPRISE",
      "type": "subscription",
      "unit_price": 120.00,
      "currency_id": "EUR",
      "expiration_date": "2025-12-31"
    }
  ]
}

Email Notifications

When a report order is created, an email notification is automatically sent to the user confirming their purchase and providing access details. If you want to disable these automatic emails, you can turn them off in your dashboard at /dashboard/settings#notifications.

Response

Success Response (201 Created)

{
  "data": {
    "id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
    "external_reference": "BOOKSHOP-POS-12345",
    "type": "report",
    "unit_price": 25.00,
    "currency_id": "USD",
    "status": "approved",
    "created_at": "2024-11-24",
    "user": {
      "id": "customer-789",
      "email": "[email protected]"
    },
    "products": [
      {
        "id": "EBOOK-BESTSELLER",
        "type": "content",
        "name": "Digital Marketing Guide",
        "status": "approved",
        "expiration_date": null,
        "cover": "https://cdn.publica.la/content/marketing-guide.jpg",
        "reader_url": "https://yourstore.publica.la/reader/digital-marketing-guide",
        "description": "Complete guide to digital marketing strategies",
        "pages_quantity": 320,
        "file_type": "pdf",
        "unit_price": 25.00,
        "currency_id": "USD"
      }
    ]
  }
}

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 `"report"`
`status`	string	Always `"approved"` (immediate access)
`unit_price`	float	Total order amount
`currency_id`	string	Order currency code
`user`	object	User information
`products`	array	Products with full details

Managing Report Orders

Retrieving Orders

Get a specific report order:

GET /integration-api/v1/orders/{order_id}?id_type=internal

Get by external reference:

GET /integration-api/v1/orders/{external_ref}?id_type=external

List all report orders:

GET /integration-api/v1/orders

Updating Orders

Update the expiration date for all products in a report 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/a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6?id_type=internal

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

Example - Update using external reference:

PUT /integration-api/v1/orders/BOOKSHOP-POS-12345?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

Cancel a report order and revoke user access.

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). Defaults to immediate if not provided.	No

Example Request:

{
  "reason": "Customer requested refund",
  "expiration_date": "2024-11-24"
}

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

Error Handling

Common Errors

Status Code	Error	Cause
`400`	Invalid currency	Currency code not supported
`401`	Unauthorized	Invalid or missing API token
`422`	Validation error	Missing required fields
`422`	Invalid product	Product doesn't exist (when auto-creation fails)
`422`	Currency mismatch	Products have different currencies than order

Error Response Example

{
  "status": 422,
  "errors": [
    {
      "title": "The unit_price field is required",
      "details": [
        "Report orders must include a unit_price"
      ]
    },
    {
      "title": "The products.0.currency_id field is required",
      "details": [
        "Each product must specify a currency_id"
      ]
    }
  ]
}

Overview - Compare all order types
Permission Orders - Grant access without payment records
Sale Orders - Publica.la checkout flow
API Authentication - Authentication setup

Creating a Report Order​

Endpoint​

Required Fields​

Optional Fields​

Request Examples​

Basic Report Order​

Report Order with Multiple Products​

Report Order with Subscription​

Response​

Success Response (201 Created)​

Response Fields​

Managing Report Orders​

Retrieving Orders​

Updating Orders​

Canceling Orders​

Error Handling​

Common Errors​

Error Response Example​

Related Documentation​

Graph View