> ## 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.

# Update & Cancel Orders

Manage existing orders by updating expiration dates or canceling access entirely.

---

## Update Order

Update the expiration date for all products in an order. This is useful for extending or limiting access periods.

### Endpoint

```
PUT /api/v3/orders/{order_id}
```

### Path Parameters

| Parameter  | Type   | Description                      |
| ---------- | ------ | -------------------------------- |
| `order_id` | string | Order UUID or external reference |

### Query Parameters

| Parameter | Type   | Default    | Description                                             |
| --------- | ------ | ---------- | ------------------------------------------------------- |
| `id_type` | string | `internal` | `internal` for UUID, `external` for external reference  |
| `include` | string | -          | Comma-separated: `user`, `products`, `pending_checkout` |
| `fields`  | string | -          | Comma-separated list of fields to return                |

### Request Body

| Field             | Type   | Description                              | Required                                   |
| ----------------- | ------ | ---------------------------------------- | ------------------------------------------ |
| `expiration_date` | string | New expiration date (YYYY-MM-DD)         | Required if `status` not provided          |
| `status`          | string | New order status: `paused` or `approved` | Required if `expiration_date` not provided |

:::warning Status Updates
The `status` field can only be updated for **subscription orders** created with a **manual gateway** (external payment). Attempting to update status on non-subscription orders will return a 422 error.
:::

---

### Update Examples

#### Update by Internal UUID

```bash
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"
  }'
```

#### Update by External Reference

```bash
curl -X PUT "https://yourstore.publica.la/api/v3/orders/MY-ORDER-123?id_type=external" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "expiration_date": "2026-12-31"
  }'
```

#### Extend Access

```bash
# Extend subscription access by one year
curl -X PUT "https://yourstore.publica.la/api/v3/orders/SUBSCRIPTION-001?id_type=external" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "expiration_date": "2027-12-31"
  }'
```

---

### Update Response

#### Success Response (200 OK)

```json
{
  "data": {
    "id": "12345",
    "uuid": "275ca6c4-a815-4f64-8198-759a296dd495",
    "external_id": "MY-ORDER-123",
    "type": "permission",
    "status": "approved",
    "unit_price": 29.99,
    "currency_id": "USD",
    "created_at": "2025-12-03T22:43:44.000000Z",
    "updated_at": "2025-12-03T23:15:22.000000Z"
  }
}
```

#### Response with Includes

Request with `?include=user,products`:

```json
{
  "data": {
    "id": "12345",
    "uuid": "275ca6c4-a815-4f64-8198-759a296dd495",
    "external_id": "MY-ORDER-123",
    "type": "permission",
    "status": "approved",
    "unit_price": 29.99,
    "currency_id": "USD",
    "created_at": "2025-12-03T22:43:44.000000Z",
    "updated_at": "2025-12-03T23:15:22.000000Z",
    "user": {
      "id": "67890",
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "external_id": "user-123",
      "email": "customer@example.com"
    },
    "products": [
      {
        "id": "54321",
        "external_id": "9781234567890",
        "type": "content",
        "name": "Digital Marketing Handbook",
        "status": "approved",
        "expiration_date": "2026-12-31",
        "unit_price": 29.99,
        "currency_id": "USD",
        "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"
      }
    ]
  }
}
```

:::note All Products Updated
The expiration date update applies to **all products** in the order. You cannot update individual product expirations.
:::

---

## Cancel Order (Delete)

Cancel an order and revoke user access to all products.

### Endpoint

```
DELETE /api/v3/orders/{order_id}
```

### Path Parameters

| Parameter  | Type   | Description                      |
| ---------- | ------ | -------------------------------- |
| `order_id` | string | Order UUID or external reference |

### Query Parameters

| Parameter | Type   | Default    | Description                                            |
| --------- | ------ | ---------- | ------------------------------------------------------ |
| `id_type` | string | `internal` | `internal` for UUID, `external` for external reference |

### Request Body (Optional)

| Field             | Type   | Description                              | Required |
| ----------------- | ------ | ---------------------------------------- | -------- |
| `reason`          | string | Cancellation reason (3-150 chars)        | No       |
| `expiration_date` | string | Effective cancellation date (YYYY-MM-DD) | No       |

---

### Cancel Examples

#### Immediate Cancellation

```bash
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": "Customer requested refund"
  }'
```

#### Cancel by External Reference

```bash
curl -X DELETE "https://yourstore.publica.la/api/v3/orders/MY-ORDER-123?id_type=external" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Subscription not renewed"
  }'
```

#### Scheduled Cancellation

Set a future date when access will be revoked:

```bash
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": "Subscription ending at period end",
    "expiration_date": "2025-12-31"
  }'
```

#### Cancel Without Reason

```bash
curl -X DELETE "https://yourstore.publica.la/api/v3/orders/275ca6c4-a815-4f64-8198-759a296dd495" \
  -H "X-User-Token: your-api-token"
```

---

### Cancel Response

#### Success Response (200 OK)

```json
{
  "data": {
    "id": "12345",
    "uuid": "275ca6c4-a815-4f64-8198-759a296dd495",
    "external_id": "MY-ORDER-123",
    "type": "permission",
    "status": "cancelled",
    "unit_price": 29.99,
    "currency_id": "USD",
    "created_at": "2025-12-03T22:43:44.000000Z",
    "updated_at": "2025-12-03T23:30:15.000000Z"
  }
}
```

#### Scheduled Cancellation Response

When using `expiration_date`, the order remains active until that date:

```json
{
  "data": {
    "id": "12345",
    "uuid": "275ca6c4-a815-4f64-8198-759a296dd495",
    "external_id": "MY-ORDER-123",
    "type": "permission",
    "status": "approved",
    "unit_price": 29.99,
    "currency_id": "USD",
    "created_at": "2025-12-03T22:43:44.000000Z",
    "updated_at": "2025-12-03T23:30:15.000000Z"
  }
}
```

:::info Scheduled Cancellations
When you provide an `expiration_date`, the order remains `approved` until that date. Access is automatically revoked when the date passes.
:::

:::note Past dates are valid here
Updates and cancellations accept past `expiration_date` values, which end access retroactively. Order creation does not. See [Expiration Dates](./orders-v3-overview.md#expiration-dates).
:::

---

## Error Handling

### Order Not Found (404)

```json
{
  "message": "Order not found."
}
```

### Invalid Expiration Date (422)

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "expiration_date": ["The expiration_date must be a valid date."]
  }
}
```

### Status Update Not Allowed (422)

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "status": ["Status updates are only allowed for subscription orders."]
  }
}
```

### Invalid Reason Length (422)

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "reason": ["The reason must be between 3 and 150 characters."]
  }
}
```

### Order Already Cancelled (422)

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "order": ["Order is already cancelled."]
  }
}
```

---

## Common Error Causes

| Error                     | Cause                                             |
| ------------------------- | ------------------------------------------------- |
| Order not found           | UUID doesn't exist or wrong `id_type`             |
| Invalid date format       | Date not in YYYY-MM-DD format                     |
| Status update not allowed | Trying to update status on non-subscription order |
| Reason too short          | Reason less than 3 characters                     |
| Reason too long           | Reason exceeds 150 characters                     |
| Order already cancelled   | Attempting to cancel a cancelled order            |

---

## Use Cases

### Subscription Renewal

Extend access when subscription is renewed:

```bash
curl -X PUT "https://yourstore.publica.la/api/v3/orders/SUB-12345?id_type=external" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "expiration_date": "2026-12-31"
  }'
```

### Refund Processing

Immediately revoke access after refund:

```bash
curl -X DELETE "https://yourstore.publica.la/api/v3/orders/ORDER-789?id_type=external" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Full refund issued - order #789"
  }'
```

### Grace Period Cancellation

Allow access until end of billing period:

```bash
curl -X DELETE "https://yourstore.publica.la/api/v3/orders/SUB-12345?id_type=external" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Subscription cancelled by user",
    "expiration_date": "2025-12-31"
  }'
```

### Corporate Access Revocation

Revoke employee access when they leave:

```bash
curl -X DELETE "https://yourstore.publica.la/api/v3/orders/CORP-EMP-123?id_type=external" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Employee offboarding"
  }'
```

---

## Best Practices

### 1. Store External References

Always use meaningful `external_id` values for easy lookup:

```json
{
  "external_id": "STRIPE-SUB-cus_ABC123"
}
```

### 2. Log Cancellation Reasons

Provide descriptive reasons for audit trails:

```json
{
  "reason": "Refund #12345 - customer complaint"
}
```

### 3. Use Scheduled Cancellations

For subscriptions, schedule cancellations at period end:

```json
{
  "reason": "User cancelled subscription",
  "expiration_date": "2025-12-31"
}
```

### 4. Verify After Update

Retrieve the order after update to confirm changes:

```bash
curl -X GET "https://yourstore.publica.la/api/v3/orders/275ca6c4...?include=products" \
  -H "X-User-Token: your-api-token"
```

---

## See Also

- [Get Order](./orders-v3-get.md) - Retrieve order details
- [List Orders](./orders-v3-list.md) - Query orders
- [Permission Orders](./create-order/orders-v3-permission.md) - Create permission orders
- [Report Orders](./create-order/orders-v3-report.md) - Create report orders