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

# Manage Line Request

> Cancel a pending request or recover its payment link. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON request/response, full schema and.

<Note>
  This endpoint supports small request-management actions. It does not create a new line request.
</Note>

## When To Use This Endpoint

Use this endpoint when the request already exists and the user asks one of these questions:

* "I lost the payment link. Can I get it again?"
* "I changed my mind. Can I cancel this unpaid request?"

This endpoint is only for requests that are still pending payment.

## Authentication

Pass your workspace API key as a Bearer token, or use a Clerk session token.

```bash theme={null}
Authorization: Bearer tuco_xxxxxxxxxxxxx
```

***

## Path parameter

<ParamField path="id" type="string">
  Required. The line request id returned by `POST /api/line-requests`.
</ParamField>

***

## Supported actions

| Action         | What it does                                                                |
| -------------- | --------------------------------------------------------------------------- |
| `payment_link` | Returns the hosted invoice link again for an `awaiting_payment` request     |
| `cancel`       | Cancels an `awaiting_payment` request so it no longer blocks a new purchase |

Both actions only apply to pending-payment requests.

If the request is already in `provisioning`, `active`, `failed`, or `canceled`, these actions no longer apply.

***

## Recover payment link

```bash theme={null}
curl -X POST "https://app.tuco.ai/api/line-requests/6a092ebde4a7fbddc8a832da" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "action": "payment_link" }'
```

### Success (`200 OK`)

```json theme={null}
{
  "success": true,
  "status": "awaiting_payment",
  "paymentUrl": "https://invoice.stripe.com/...",
  "invoiceId": "in_123",
  "reused": true
}
```

If the workspace entitlement has already updated, the same action can promote the line and return a normal provisioning response instead.

That means `payment_link` can act like a safe recovery action:

* if payment is still needed, it gives you the invoice again
* if payment has already been reconciled, it can return the updated provisioning state instead

***

## Cancel pending request

```bash theme={null}
curl -X POST "https://app.tuco.ai/api/line-requests/6a092ebde4a7fbddc8a832da" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "action": "cancel" }'
```

### Success (`200 OK`)

```json theme={null}
{
  "success": true,
  "status": "canceled",
  "line": {
    "_id": "6a092ebde4a7fbddc8a832da",
    "provisioningStatus": "canceled",
    "paymentStatus": "failed"
  }
}
```

After canceling, the workspace can create a different line request without waiting on the old unpaid one.

***

## Error responses

| Status | When                                               | Body                                                                                                |
| ------ | -------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `400`  | Invalid line request id or unsupported action      | `{ "error": "Invalid line request id" }` or `{ "error": "Unsupported action" }`                     |
| `401`  | Missing or invalid API key / session               | `{ "error": "Unauthorized" }`                                                                       |
| `403`  | `payment_link` used without an active subscription | `{ "success": false, "status": "subscription_required", "message": "...", "redirect": "/billing" }` |
| `404`  | Request not found in your workspace                | `{ "error": "Line request not found" }`                                                             |
| `409`  | Action does not apply to the current request state | `{ "success": false, "status": "...", "message": "..." }`                                           |