> 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/guides/accounts-payable/vendor-credits/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mercoa.com/_mcp/server.

## [API Reference](/api-reference/entity/counterparty/vendor-credit/get-all)

Mercoa also supports vendor credit tracking. Vendor credits are credits your users can receive from their vendors that represent the amount of money a vendor owes your user.

## Creating Vendor Credits

Vendor credits can be created through Mercoa's frontend via the [entity dashboard](https://mercoa.com/dashboard/entities) or Mercoa's vendor portal. You can also create vendor credits through the [create vendor credit](/api-reference/entity/counterparty/vendor-credit/create) API endpoint.

### Request

POST [https://api.mercoa.com/entity/\{entityId}/counterparty/\{counterpartyId}/vendor-credit](https://api.mercoa.com/entity/\{entityId}/counterparty/\{counterpartyId}/vendor-credit)

**`Default`**

```curl Default
curl -X POST https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/counterparty/ent_21661ac1-a2a8-4465-a6c0-64474ba8181d/vendor-credit \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "totalAmount": 100,
  "currency": "USD",
  "note": "This is a note"
}'
```

**`Default`**

```python Default
import requests

url = "https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/counterparty/ent_21661ac1-a2a8-4465-a6c0-64474ba8181d/vendor-credit"

payload = {
    "totalAmount": 100,
    "currency": "USD",
    "note": "This is a note"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

**`Default`**

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

const client = new MercoaClient({ token: "YOUR_TOKEN" });
await client.entity.counterparty.vendorCredit.create("ent_8545a84e-a45f-41bf-bdf1-33b42a55812c", "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d", {
    totalAmount: 100,
    currency: "USD",
    note: "This is a note"
});

```

**`Default`**

```go Default
package main

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

func main() {

	url := "https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/counterparty/ent_21661ac1-a2a8-4465-a6c0-64474ba8181d/vendor-credit"

	payload := strings.NewReader("{\n  \"totalAmount\": 100,\n  \"currency\": \"USD\",\n  \"note\": \"This is a note\"\n}")

	req, _ := http.NewRequest("POST", 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))

}
```

**`Default`**

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

url = URI("https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/counterparty/ent_21661ac1-a2a8-4465-a6c0-64474ba8181d/vendor-credit")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"totalAmount\": 100,\n  \"currency\": \"USD\",\n  \"note\": \"This is a note\"\n}"

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

**`Default`**

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

HttpResponse<String> response = Unirest.post("https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/counterparty/ent_21661ac1-a2a8-4465-a6c0-64474ba8181d/vendor-credit")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"totalAmount\": 100,\n  \"currency\": \"USD\",\n  \"note\": \"This is a note\"\n}")
  .asString();
```

**`Default`**

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/counterparty/ent_21661ac1-a2a8-4465-a6c0-64474ba8181d/vendor-credit', [
  'body' => '{
  "totalAmount": 100,
  "currency": "USD",
  "note": "This is a note"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

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

**`Default`**

```csharp Default
using RestSharp;

var client = new RestClient("https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/counterparty/ent_21661ac1-a2a8-4465-a6c0-64474ba8181d/vendor-credit");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"totalAmount\": 100,\n  \"currency\": \"USD\",\n  \"note\": \"This is a note\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Default`**

```swift Default
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "totalAmount": 100,
  "currency": "USD",
  "note": "This is a note"
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/counterparty/ent_21661ac1-a2a8-4465-a6c0-64474ba8181d/vendor-credit")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
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()
```

## Applying Vendor Credits

If a vendor credit between the payer and vendor of an invoice is available, Mercoa allows the payer to apply the credit to the invoice. This deducts the vendor credit amount from the invoice total, reducing the amount transferred through Mercoa.

Mercoa's frontend automatically applies available vendor credits to invoices created via the `<PayableDetails />` React component. You can also apply vendor credits using the `vendorCreditIds` parameter on the [update invoice](/api-reference/invoice/update) API endpoint.

### Request

POST [https://api.mercoa.com/invoice/\{invoiceId}](https://api.mercoa.com/invoice/\{invoiceId})

**`UpdateVendorCredit`**

```curl UpdateVendorCredit
curl -X POST https://api.mercoa.com/invoice/in_26e7b5d3-a739-4b23-9ad9-6aaa085f47a9 \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "vendorCreditIds": [
    "vcr_c3f4c87d-794d-4543-9562-575cdddfc0d7"
  ]
}'
```

**`UpdateVendorCredit`**

```python UpdateVendorCredit
import requests

url = "https://api.mercoa.com/invoice/in_26e7b5d3-a739-4b23-9ad9-6aaa085f47a9"

payload = { "vendorCreditIds": ["vcr_c3f4c87d-794d-4543-9562-575cdddfc0d7"] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

**`UpdateVendorCredit`**

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

const client = new MercoaClient({ token: "YOUR_TOKEN" });
await client.invoice.update("in_26e7b5d3-a739-4b23-9ad9-6aaa085f47a9", {
    vendorCreditIds: ["vcr_c3f4c87d-794d-4543-9562-575cdddfc0d7"]
});

```

**`UpdateVendorCredit`**

```go UpdateVendorCredit
package main

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

func main() {

	url := "https://api.mercoa.com/invoice/in_26e7b5d3-a739-4b23-9ad9-6aaa085f47a9"

	payload := strings.NewReader("{\n  \"vendorCreditIds\": [\n    \"vcr_c3f4c87d-794d-4543-9562-575cdddfc0d7\"\n  ]\n}")

	req, _ := http.NewRequest("POST", 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))

}
```

**`UpdateVendorCredit`**

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

url = URI("https://api.mercoa.com/invoice/in_26e7b5d3-a739-4b23-9ad9-6aaa085f47a9")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"vendorCreditIds\": [\n    \"vcr_c3f4c87d-794d-4543-9562-575cdddfc0d7\"\n  ]\n}"

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

**`UpdateVendorCredit`**

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

HttpResponse<String> response = Unirest.post("https://api.mercoa.com/invoice/in_26e7b5d3-a739-4b23-9ad9-6aaa085f47a9")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"vendorCreditIds\": [\n    \"vcr_c3f4c87d-794d-4543-9562-575cdddfc0d7\"\n  ]\n}")
  .asString();
```

**`UpdateVendorCredit`**

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.mercoa.com/invoice/in_26e7b5d3-a739-4b23-9ad9-6aaa085f47a9', [
  'body' => '{
  "vendorCreditIds": [
    "vcr_c3f4c87d-794d-4543-9562-575cdddfc0d7"
  ]
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

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

**`UpdateVendorCredit`**

```csharp UpdateVendorCredit
using RestSharp;

var client = new RestClient("https://api.mercoa.com/invoice/in_26e7b5d3-a739-4b23-9ad9-6aaa085f47a9");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"vendorCreditIds\": [\n    \"vcr_c3f4c87d-794d-4543-9562-575cdddfc0d7\"\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`UpdateVendorCredit`**

```swift UpdateVendorCredit
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["vendorCreditIds": ["vcr_c3f4c87d-794d-4543-9562-575cdddfc0d7"]] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.mercoa.com/invoice/in_26e7b5d3-a739-4b23-9ad9-6aaa085f47a9")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
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()
```

When paying an invoice with vendor credits through Mercoa's payment rails, there are two scenarios to consider:

### Vendor credits partially cover the invoice

If the applied vendor credits sum to less than the invoice total, Mercoa only transfers the remaining invoice amount to the vendor. In this case, the invoice enters the `PENDING` state and is processed normally.

### Vendor credits fully cover the invoice

If the applied vendor credits sum to the invoice total or more, Mercoa doesn't transfer any funds to the vendor. In this case, the invoice enters the `PENDING` state and then immediately enters the `PAID` state. Please note that all the same webhooks are still sent as if the invoice is paid normally.

## Estimating Vendor Credit Usage

You can estimate the usage of vendor credits on an invoice of a given amount using the [estimate usage](/api-reference/entity/counterparty/vendor-credit/estimate-usage) endpoint.

### Request

GET [https://api.mercoa.com/entity/\{entityId}/counterparty/\{counterpartyId}/vendor-credits/estimate-usage](https://api.mercoa.com/entity/\{entityId}/counterparty/\{counterpartyId}/vendor-credits/estimate-usage)

**`Default`**

```curl Default
curl -G https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/counterparty/ent_21661ac1-a2a8-4465-a6c0-64474ba8181d/vendor-credits/estimate-usage \
     -H "Authorization: Bearer <token>" \
     -d amount=150 \
     -d currency=USD
```

**`Default`**

```python Default
import requests

url = "https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/counterparty/ent_21661ac1-a2a8-4465-a6c0-64474ba8181d/vendor-credits/estimate-usage"

querystring = {"amount":"150","currency":"USD"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

**`Default`**

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

const client = new MercoaClient({ token: "YOUR_TOKEN" });
await client.entity.counterparty.vendorCredit.estimateUsage("ent_8545a84e-a45f-41bf-bdf1-33b42a55812c", "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d", {
    amount: 150,
    currency: "USD"
});

```

**`Default`**

```go Default
package main

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

func main() {

	url := "https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/counterparty/ent_21661ac1-a2a8-4465-a6c0-64474ba8181d/vendor-credits/estimate-usage?amount=150&currency=USD"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

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

}
```

**`Default`**

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

url = URI("https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/counterparty/ent_21661ac1-a2a8-4465-a6c0-64474ba8181d/vendor-credits/estimate-usage?amount=150&currency=USD")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

**`Default`**

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

HttpResponse<String> response = Unirest.get("https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/counterparty/ent_21661ac1-a2a8-4465-a6c0-64474ba8181d/vendor-credits/estimate-usage?amount=150&currency=USD")
  .header("Authorization", "Bearer <token>")
  .asString();
```

**`Default`**

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

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/counterparty/ent_21661ac1-a2a8-4465-a6c0-64474ba8181d/vendor-credits/estimate-usage?amount=150&currency=USD', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

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

**`Default`**

```csharp Default
using RestSharp;

var client = new RestClient("https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/counterparty/ent_21661ac1-a2a8-4465-a6c0-64474ba8181d/vendor-credits/estimate-usage?amount=150&currency=USD");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

**`Default`**

```swift Default
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/counterparty/ent_21661ac1-a2a8-4465-a6c0-64474ba8181d/vendor-credits/estimate-usage?amount=150&currency=USD")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
```