> This is Payabli documentation. For a complete page index, fetch https://docs.payabli.com/llms.txt — append .md to any page URL for lightweight markdown. For section-level indexes, query parameters, and other AI-optimized access methods, see https://docs.payabli.com/ai-agents.md

# Update a business

PATCH https://api-sandbox.payabli.com/api/v2/businesses/{businessReference}
Content-Type: application/json

Applies a partial update to a business. Send only the fields you want to change.

Reference: https://docs.payabli.com/developers/api-reference/businesses/update-a-business

## Authentication

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

## Servers

- `https://api-sandbox.payabli.com/api` (Sandbox, default)
- `https://api.payabli.com/api` (Production)

## Request

### Path parameters

- `businessReference` (string, required) — The business reference (`businessUuid`).

### Body (application/json)

This endpoint expects an UpdateBusinessRequest.

- `externalId` (string, optional) — Your own identifier for the business.
- `legalName` (string, optional) — The registered legal name of the business.
- `description` (string, optional) — A free-text description of the business.
- `legalStructure` (enum, optional) — The business's legal structure. Accepts the same values as create, and normalizes to a canonical value on read.
  - Allowed values: `limited-liability-company`, `llc`, `corporation`, `partnership`, `sole-proprietorship`, `non-profit`, `nonprofit`, `government`, `s-corp`, `s-corporation`
- `stockSymbol` (string, optional) — The stock ticker symbol, if the business is publicly traded.
- `incorporationState` (string, optional) — The state where the business is incorporated.
- `taxIdCountry` (string, optional) — The country that issued the business's tax identifier.
- `establishedDate` (datetime, optional) — The date the business was established.
- `numberOfEmployees` (integer, optional) — The number of employees.
- `annualRevenue` (double, optional) — The business's annual revenue.
- `website` (string, optional) — The business's website URL.
- `merchantCatCode` (string, optional) — The merchant category code (MCC) that classifies the business.
- `timezone` (string, optional) — The business's time zone.
- `phone` (list of string, optional) — Phone numbers for the business.
- `emails` (list of string, optional) — Email addresses for the business.
- `operatingSeasons` (list of enum, optional) — The seasons the business operates in. Values are case-insensitive on input and returned capitalized.
  - Allowed values: `Spring`, `Summer`, `Fall`, `Winter`
- `addressDetails` (list of BusinessAddress, optional) — A non-empty `addressDetails` is rejected on update. Manage a business's addresses through the `/v2/businesses/{businessReference}/addresses` endpoints instead. An omitted field or an empty array is accepted as "no address change requested."
- `paymentMethods` (list of BusinessPaymentMethod, optional) — The bank accounts and cards attached to the business.
- `customData` (map from string to any, optional) — Key-value data to merge into the business's stored `customData`. Payabli stores the applicant's answers to a boarding template's custom questions under the `templateAnswers` key. When you update a business, Payabli merges `customData` into the stored value, following JSON Merge Patch (RFC 7396). Keys you don't send are kept at every depth, and nested objects merge key by key. Strings, numbers, Boolean values, and arrays replace the stored value, and arrays aren't merged. Send a key as `null` to delete it, such as `{"crmId": null}`. A `customData` that isn't an object, such as an array, replaces the stored value whole. Leave out `customData` to keep it as is. The `customData` you send can be up to 65,536 bytes serialized. The limit applies to the request, not to the merged result.
- `isForeignOwned` (boolean, optional) — Whether the business is foreign-owned.
- `isTaxExempt` (boolean, optional) — Whether the business is tax-exempt.
- `taxExemptClassification` (string, optional) — The business's tax-exempt classification, such as `501(c)(3)`.
- `processingMetrics` (ProcessingMetrics, optional) — Expected Pay In processing profile for the business.
- `payoutMetrics` (PayoutMetrics, optional) — Expected Pay Out profile for the business.
- `license` (string, optional) — The business's license number.
- `licenseState` (string, optional) — The state that issued the business's license.

## Response

### 200

Business updated.

- `success` (boolean, required) — Whether the request succeeded.
- `message` (string, required, nullable) — A human-readable result message.
- `traceId` (string, required, nullable) — The trace identifier for the request, useful for support.
- `data` (BusinessUpdatedResponse, required, nullable) — The updated business.
- `warnings` (list of BoardingWarning, required, nullable) — Non-blocking warnings.

## Errors

### 400 Bad Request Error

Bad request / invalid data.

- `isSuccess` (boolean, required) — Always `false` for error responses.
- `responseText` (string, required) — Error text describing what went wrong.
- `responseCode` (integer, optional) — Code for the response. Learn more in [API Response Codes](/developers/api-reference/api-responses).
- `responseData` (PayabliErrorBodyResponseData, optional) — Object with detailed error context.

### 401 Unauthorized Error

Unauthorized request.

- `isSuccess` (boolean, required) — Always `false` for error responses.
- `responseText` (string, required) — Error text describing what went wrong.
- `responseCode` (integer, optional) — Code for the response. Learn more in [API Response Codes](/developers/api-reference/api-responses).
- `responseData` (PayabliErrorBodyResponseData, optional) — Object with detailed error context.

### 404 Not Found Error

The requested resource wasn't found.

- `isSuccess` (boolean, required) — Always `false` for error responses.
- `responseText` (string, required) — Error text describing what went wrong.
- `responseCode` (integer, optional) — Code for the response. Learn more in [API Response Codes](/developers/api-reference/api-responses).
- `responseData` (PayabliErrorBodyResponseData, optional) — Object with detailed error context.

### 500 Internal Server Error

Internal server error.

- `isSuccess` (boolean, required) — Always `false` for error responses.
- `responseText` (string, required) — Error text describing what went wrong.
- `responseCode` (integer, optional) — Code for the response. Learn more in [API Response Codes](/developers/api-reference/api-responses).
- `responseData` (PayabliErrorBodyResponseData, optional) — Object with detailed error context.

## Types

### BusinessAddress

An address associated with a business.

- `type` (enum, optional) — The address role.
  - Allowed values: `legal`, `billing`, `shipping`, `remittance`, `physical`, `mailing`
- `location` (enum, optional) — The physical use of the address. Defaults to `other`.
  - Allowed values: `office`, `warehouse`, `retail`, `home`, `other`
- `addressLine1` (string, optional) — The first line of the street address.
- `addressLine2` (string, optional) — The second line of the street address.
- `cityLocality` (string, optional) — The city or locality.
- `stateProvince` (string, optional) — The state or province.
- `postalCode` (string, optional) — The postal or ZIP code.
- `country` (string, optional) — The two-character ISO country code.
- `floor` (string, optional) — The floor, if applicable.
- `suiteApartNumber` (string, optional) — The suite or apartment number, if applicable.

### BusinessPaymentMethod

A bank account or card attached to a business.

- `type` (string, optional) — The payment method type, for example a bank account or card.
- `accountOwner` (string, optional) — The name of the account owner.
- `name` (string, optional) — An optional label for the payment method.
- `financialInstitution` (string, optional) — The bank or financial institution that holds the account.
- `ownerType` (string, optional) — Whether the owner is a business or an individual.
- `accountType` (string, optional) — The account type, for example checking or savings.
- `accountNumber` (string, optional) — The bank account number.
- `routingNumber` (string, optional) — The bank routing number.
- `cardNumber` (string, optional) — The card number, for card payment methods.
- `expirationDate` (string, optional) — The card expiration date, for card payment methods.
- `cvv` (string, optional) — The card verification value, for card payment methods.
- `cardType` (string, optional) — The card type, for card payment methods.
- `usage` (list of string, optional) — What the payment method is used for.
- `isDefault` (boolean, optional) — Whether this is the owner's default payment method. At most one payment method per owner can set `isDefault` to `true`; sending two `true` values in one request fails validation.

### ProcessingMetrics

Expected Pay In processing profile for the business.

- `monthlyReceivablesVolume` (double, optional) — Expected monthly Pay In volume.
- `averageReceivableSize` (double, optional) — Expected average transaction amount.
- `largestReceivableSize` (double, optional) — Expected largest transaction amount.
- `inboundPresentPercent` (integer, optional) — Percent of volume from card-present transactions.
- `inboundOnlinePercent` (integer, optional) — Percent of volume from online transactions.
- `inboundMotoPercent` (integer, optional) — Percent of volume from mail-order/telephone-order transactions.
- `refundPolicy` (string, optional) — The business's refund policy.
- `advancedDelivery` (boolean, optional) — Whether the business delivers goods or services before it's paid.
- `percentAdvancedDelivery` (integer, optional) — Percent of sales delivered before payment.
- `advancedDeliveryDays` (double, optional) — Average number of days between payment and delivery.
- `numberOfTransactions` (integer, optional) — Expected number of transactions per month.

### PayoutMetrics

Expected Pay Out profile for the business.

- `monthlyPayablesVolume` (double, optional) — Expected monthly Pay Out volume.
- `averagePayablesSize` (double, optional) — Expected average payout amount.
- `largestPayablesSize` (double, optional) — Expected largest payout amount.
- `numberOfTransactions` (integer, optional) — Expected number of payouts per month.

### BusinessUpdatedResponse

The reference and updated timestamp after a business update.

- `businessUuid` (string, required) — The business reference.
- `lastUpdated` (datetime, required) — When the business was last updated.
- `_links` (BusinessLinks, required) — Hypermedia links for the business resource.

### BoardingWarning

A non-blocking warning returned alongside a successful response.

- `code` (string, optional) — A machine-readable warning code.
- `message` (string, optional) — A human-readable description of the warning.

### PayabliErrorBodyResponseData

Object with detailed error context.

- `explanation` (string, optional) — Human-readable explanation of what happened.
- `todoAction` (string, optional) — Suggested resolution.

### BusinessLinks

Hypermedia links for a business resource.

- `self` (string, optional) — Relative path to the business resource.

## Examples

**Request**

```json
{
  "website": "https://example.org"
}
```

**Response**

```json
{
  "success": true,
  "message": "Business updated successfully",
  "traceId": "0HNNKQIN7BJO1:00000016",
  "data": {
    "businessUuid": "019fed1a-3d6e-75d3-a81e-cba3874b0a55",
    "lastUpdated": "2026-08-10T19:15:47.9553337Z",
    "_links": {
      "self": "/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55"
    }
  }
}
```

**SDK Code**

```python
import requests

url = "https://api-sandbox.payabli.com/api/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55"

payload = { "website": "https://example.org" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

```javascript
const url = 'https://api-sandbox.payabli.com/api/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"website":"https://example.org"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

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

func main() {

	url := "https://api-sandbox.payabli.com/api/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55"

	payload := strings.NewReader("{\n  \"website\": \"https://example.org\"\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
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.payabli.com/api/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55")

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  \"website\": \"https://example.org\"\n}"

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

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

HttpResponse<String> response = Unirest.patch("https://api-sandbox.payabli.com/api/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"website\": \"https://example.org\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api-sandbox.payabli.com/api/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55', [
  'body' => '{
  "website": "https://example.org"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api-sandbox.payabli.com/api/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"website\": \"https://example.org\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["website": "https://example.org"] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55")! 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()
```