> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mercoa.com/embedded-ap-ar/api-reference/invoice/collection/update-next-action/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mercoa.com/_mcp/server.

# Update Next Action

PATCH https://api.mercoa.com/invoice/{invoiceId}/collection/next-action
Content-Type: application/json

Update the collection agent's next action on this invoice with natural language. Note that updating any APPROVED action will reset the action to SUGGESTED.  This endpoint will throw an error if there is no action to update.

Reference: https://docs.mercoa.com/embedded-ap-ar/api-reference/invoice/collection/update-next-action

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `invoiceId` (string, required) — Invoice ID or Invoice ForeignID

### Body (application/json)

This endpoint expects an object.

- `feedback` (string, required) — Natural language feedback to update the collection agent's next action

## Response

### 200

- `object`
  - `type`: `email`
    - `body` (string, required) — The body of the email in plaintext
    - `id` (string, required)
    - `scheduledExecutionTime` (datetime, required) — The UTC timestamp for when this action is scheduled for execution. Actual execution may be delayed by a few minutes due to processing time.
    - `status` (enum, required) — The current lifecycle state of the action. SUGGESTED actions are pending approval, APPROVED actions will be executed, and COMPLETED actions have been executed.
      - Allowed values: `SUGGESTED`, `APPROVED`, `COMPLETED`
    - `subject` (string, required) — The subject of the email

## Errors

### 400 Bad Request

- `errorName` ("BadRequest", required)
- `content` (string, required)

### 401 Unauthorized

- `errorName` ("Unauthorized", required)
- `content` (string, required)

### 403 Forbidden

- `errorName` ("Forbidden", required)
- `content` (string, required)

### 404 Not Found

- `errorName` ("NotFound", required)
- `content` (string, required)

### 409 Conflict

- `errorName` ("Conflict", required)
- `content` (string, required)

### 500 Internal Server Error

- `errorName` ("InternalServerError", required)
- `content` (string, required)

### 501 Unimplemented

- `errorName` ("Unimplemented", required)
- `content` (string, required)

## Examples

**Request**

```json
{
  "feedback": "Use a more stern tone"
}
```

**Response**

```json
{
  "type": "email",
  "body": "Your invoice is now 3 days overdue. Please arrange payment as soon as possible to avoid further follow-ups.",
  "id": "act_c3881909-c2f8-4a1e-878a-80a9b594483c",
  "scheduledExecutionTime": "2024-01-04T13:00:00Z",
  "status": "SUGGESTED",
  "subject": "Invoice Past Due - Please Review"
}
```

**SDK Code**

```python Default
import requests

url = "https://api.mercoa.com/invoice/in_3d61faa9-1754-4b7b-9fcb-88ff97f368ff/collection/next-action"

payload = { "feedback": "Use a more stern tone" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```typescript Default
import { MercoaClient } from "@mercoa/javascript";

const client = new MercoaClient({ token: "YOUR_TOKEN" });
await client.invoice.collection.updateNextAction("in_3d61faa9-1754-4b7b-9fcb-88ff97f368ff", {
    feedback: "Use a more stern tone"
});

```

```go Default
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mercoa.com/invoice/in_3d61faa9-1754-4b7b-9fcb-88ff97f368ff/collection/next-action"

	payload := strings.NewReader("{\n  \"feedback\": \"Use a more stern tone\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Default
require 'uri'
require 'net/http'

url = URI("https://api.mercoa.com/invoice/in_3d61faa9-1754-4b7b-9fcb-88ff97f368ff/collection/next-action")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"feedback\": \"Use a more stern tone\"\n}"

response = http.request(request)
puts response.read_body
```

```java Default
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.patch("https://api.mercoa.com/invoice/in_3d61faa9-1754-4b7b-9fcb-88ff97f368ff/collection/next-action")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"feedback\": \"Use a more stern tone\"\n}")
  .asString();
```

```php Default
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.mercoa.com/invoice/in_3d61faa9-1754-4b7b-9fcb-88ff97f368ff/collection/next-action', [
  'body' => '{
  "feedback": "Use a more stern tone"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Default
using RestSharp;

var client = new RestClient("https://api.mercoa.com/invoice/in_3d61faa9-1754-4b7b-9fcb-88ff97f368ff/collection/next-action");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"feedback\": \"Use a more stern tone\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Default
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["feedback": "Use a more stern tone"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.mercoa.com/invoice/in_3d61faa9-1754-4b7b-9fcb-88ff97f368ff/collection/next-action")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```