> ## Documentation Index
> Fetch the complete documentation index at: https://docs.publica.la/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](../orders-v3-overview.md#choosing-the-right-order-type) for guidance on when to use report orders.

---

## Creating a Report Order

### Endpoint

```
POST /api/v3/orders
```

### Request Body

```json
{
  "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": "customer@example.com"
  },
  "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)                                                   |

:::caution 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](../orders-v3-update-cancel.md), which still accepts past dates.
:::

---

## Request Examples

### Basic Report Order

```bash
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": "customer@example.com"
    },
    "products": [
      {
        "external_id": "MARKETPLACE-EBOOK",
        "type": "content",
        "unit_price": 25.00,
        "currency_id": "USD"
      }
    ]
  }'
```

### Report Order with Multiple Products

```bash
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": "buyer@example.com"
    },
    "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

```bash
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": "accounts@company.com"
    },
    "products": [
      {
        "external_id": "ANNUAL-ENTERPRISE",
        "type": "subscription",
        "unit_price": 120.00,
        "currency_id": "EUR",
        "expiration_date": "2026-12-31"
      }
    ]
  }'
```

---

## Response

### Success Response (201 Created)

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

:::note Immediate Access
Report orders are created with `status: approved`. Users can access content immediately.
:::

### Full Response with Includes

Request with `?include=user,products`:

```json
{
  "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": "customer@example.com"
    },
    "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

:::info 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

```bash
# 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

```bash
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

```bash
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

```json
{
  "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](./orders-v3-permission.md) - Access without payment records
- [Sale Orders](./orders-v3-sale.md) - Publica.la checkout flow
- [Update & Cancel](../orders-v3-update-cancel.md) - Manage existing orders
- [List Orders](../orders-v3-list.md) - Query orders