> ## 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 Tuco line request or recover its Stripe payment link. Doesn't create new requests. Bearer-token REST endpoint in the Tuco API.

> [!NOTE]
>
> This endpoint supports small request-management actions. It does not create a new line request.

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

**id** `string` *required*

The line request id returned by `POST /api/line-requests` — it is the `line._id` value in that response.

A line request is not a separate record: it is the line itself, created with `requestSource: "api"`. The request id and the line id are therefore the same value. Unlike [`GET /api/line-requests/{id}`](https://docs.tuco.ai/api-reference/endpoint/get-line-request), which reads any line in your workspace, these two actions run only against API-created requests — a line created in the dashboard returns `404 Line request not found`.

***

## Request body

**action** `string` *required*

Which action to run. One of `"payment_link"` or `"cancel"` — any other value returns `400 Unsupported action`, and so does an empty body.

***

## 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": "..." }` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.