Report Orders

Assign content access and create payment records in Publica.la's financial system. Required for marketplace content sales or when you need financial tracking for externally processed payments.

See Choosing the Right Order Type for guidance on when to use report orders.

---

Creating a Report Order

Endpoint

POST /api/v3/orders

Request Body

{
  "type": "report",
  "external_id": "EXT-SALE-001",
  "return_url": "https://yoursite.com/receipt",
  "unit_price": 29.99,
  "currency_id": "USD",
  "user": {
    "id": "customer-123",
    "email": "[email protected]"
  },
  "products": [
    {
      "type": "content",
      "external_id": "9781234567890",
      "unit_price": 29.99,
      "currency_id": "USD"
    }
  ]
}

Required Fields

Field	Type	Description
type	string	Must be "report"
return_url	string	Informational URL for the order
unit_price	float	Total order amount
currency_id	string	ISO 4217 currency code
user	object	User information
user.id or user.email	string	At least one user identifier
products	array	Products in the order
products[].type	string	content or subscription
products[].external_id	string	Product external ID
products[].unit_price	float	Individual product price
products[].currency_id	string	Product currency

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
products[].name	string	Product name (for auto-creation)
products[].url	string	Product URL (for auto-creation)

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 Report 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": "report",
    "external_id": "POS-SALE-12345",
    "return_url": "https://yourstore.com/receipt/12345",
    "unit_price": 25.00,
    "currency_id": "USD",
    "user": {
      "id": "customer-789",
      "email": "[email protected]"
    },
    "products": [
      {
        "external_id": "MARKETPLACE-EBOOK",
        "type": "content",
        "unit_price": 25.00,
        "currency_id": "USD"
      }
    ]
  }'

Report 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": "report",
    "external_id": "BUNDLE-SALE-456",
    "return_url": "https://partner.com/sales/456",
    "unit_price": 45.00,
    "currency_id": "USD",
    "user": {
      "id": "partner-customer-123",
      "email": "[email protected]"
    },
    "products": [
      {
        "external_id": "EBOOK-001",
        "type": "content",
        "unit_price": 15.00,
        "currency_id": "USD"
      },
      {
        "external_id": "EBOOK-002",
        "type": "content",
        "unit_price": 15.00,
        "currency_id": "USD"
      },
      {
        "external_id": "EBOOK-003",
        "type": "content",
        "unit_price": 15.00,
        "currency_id": "USD"
      }
    ]
  }'

Report Order with Subscription

curl -X POST "https://yourstore.publica.la/api/v3/orders" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "report",
    "external_id": "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": [
      {
        "external_id": "ANNUAL-ENTERPRISE",
        "type": "subscription",
        "unit_price": 120.00,
        "currency_id": "EUR",
        "expiration_date": "2026-12-31"
      }
    ]
  }'

---

Response

Success Response (201 Created)

{
  "data": {
    "id": "12345",
    "uuid": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
    "external_id": "POS-SALE-12345",
    "type": "report",
    "status": "approved",
    "unit_price": 25.0,
    "currency_id": "USD",
    "created_at": "2025-12-03T22:43:44.000000Z",
    "updated_at": "2025-12-03T22:43:44.000000Z"
  }
}

Immediate Access

Report orders are created with status: approved. Users can access content immediately.

Full Response with Includes

Request with ?include=user,products:

{
  "data": {
    "id": "12345",
    "uuid": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
    "external_id": "POS-SALE-12345",
    "type": "report",
    "status": "approved",
    "unit_price": 25.0,
    "currency_id": "USD",
    "created_at": "2025-12-03T22:43:44.000000Z",
    "updated_at": "2025-12-03T22:43:44.000000Z",
    "user": {
      "id": "67890",
      "uuid": "b2c3d4e5-f6g7-8901-bcde-fg2345678901",
      "external_id": "customer-789",
      "email": "[email protected]"
    },
    "products": [
      {
        "id": "54321",
        "external_id": "MARKETPLACE-EBOOK",
        "type": "content",
        "name": "Digital Marketing Guide",
        "status": "approved",
        "expiration_date": null,
        "unit_price": 25.0,
        "currency_id": "USD",
        "cover_url": "https://cdn.publica.la/content/marketing-guide.jpg",
        "reader_url": "https://yourstore.publica.la/reader/digital-marketing-guide",
        "product_url": "https://yourstore.publica.la/library/publication/digital-marketing-guide"
      }
    ]
  }
}

---

Email Notifications

Automatic Notifications

When a report order is created, an email notification is automatically sent to the user confirming their purchase and providing access details. To disable automatic emails, go to your dashboard at /dashboard/settings#notifications.

---

Financial Records

Report orders create financial transaction records:

• Visible in dashboard reports and analytics
• Included in revenue calculations

---

Managing Report Orders

Retrieve Order

# By internal UUID
curl -X GET "https://yourstore.publica.la/api/v3/orders/a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6?include=user,products" \
  -H "X-User-Token: your-api-token"

# By external reference
curl -X GET "https://yourstore.publica.la/api/v3/orders/POS-SALE-12345?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/a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6" \
  -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/a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Customer requested refund"
  }'

---

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	Currency mismatch	Product currencies don't match order currency
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": {
    "unit_price": ["The unit_price field is required."],
    "products.0.currency_id": ["The products.0.currency_id field is required."]
  }
}

---

See Also

• Permission Orders - Access without payment records
• Sale Orders - Publica.la checkout flow
• Update & Cancel - Manage existing orders
• List Orders - Query orders