> This page is for Cash App Pay Partner API.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.cash.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.cash.app/_mcp/server.

# Upsert brand

PUT https://api.cash.app/network/v1/brands
Content-Type: application/json

Creates or updates a brand based on the brand's `reference_id`.

If a brand with a matching `reference_id` is found,
it will be updated. Ensure proper mapping; if no matching brand is found,
a new one will be created.

The HTTP response code (`200 OK` or `201 Created`) indicates
whether the resource was updated or created, respectively.

`brand_id` is the primary unique identifier for all Brand APIs.
Be cautious when using `reference_id` as a unique identifier.

**This endpoint is not rate limited.**

Scopes: `BRANDS_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/upsert-brand

## Servers

- `https://api.cash.app/network/v1` (Production, default)
- `https://sandbox.api.cash.app/network/v1` (Sandbox)

## Request

### Body (application/json)

This endpoint expects an object.

- `brand` (UpsertBrandRequestBrand, required) — Details about the brand to create or update.

## Response

### 200

OK

- `brand` (Brand, optional) — A brand is the entity a customer perceives that they are transacting with.

## Errors

### 400 Upsert Brand Request Bad Request Error

Bad Request

- `errors` (list of Error, required) — A list of errors that occurred while processing the request. Min number of items: `1`

## Types

### UpsertBrandRequestBrand

Details about the brand to create or update.

- `name` (string, required) — Name of the brand to be shown in Cash App next to payments. Min length: `1` Max length: `1024`
- `reference_id` (string, required) — A user-defined identifier for this brand, typically used to associate the brand with a record in an external system. **Must be unique across all brands. Independent from the [merchant reference_id](https://developers.cash.app/docs/api/network-api/operations/create-a-merchant#request-body)** Min length: `1` Max length: `1024`
- `profile_image_url` (string, optional) — URL to the image that should be shown in Cash App next to payments made to this brand, typically the brand's logo. The image should be square and be at least 256x256. It must be less than 2MB in filesize. Acceptable image formats: - `png` - `jpg` - `jpeg` Min length: `8` Max length: `8000`
- `color` (string, optional) — Primary color associated with this brand and its logo, in 6-digit hex code format. Pattern: `^#[a-fA-F0-9]{6}$` Min length: `7` Max length: `7`
- `metadata` (map from string to string, optional) — Freeform key-value pairs of arbitrary data associated with this resource. Keys and values must be passed as strings and not contain any personally identifiable information (PII). Min keys: `0` Max keys: `50` > Note: Nested keys are not supported.

### Brand

A brand is the entity a customer perceives that they are transacting with.

- `id` (string, required) — A unique identifier for the brand issued by Cash App. Min length: `1` Max length: `128`
- `name` (string, required) — Name of the brand to be shown in Cash App next to payments. Min length: `1` Max length: `1024`
- `created_at` (datetime, required) — When this brand was created, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
- `updated_at` (datetime, required) — When this brand was last updated, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
- `reference_id` (string, required) — A user-defined identifier for this brand, typically used to associate the brand with a record in an external system. Independent from the [merchant reference_id](https://developers.cash.app/docs/api/network-api/operations/create-a-merchant#request-body). Min length: `1` Max length: `1024`
- `color` (string, optional) — Primary color associated with this brand and its logo, in 6-digit hex code format (`#f0f0f0`). Min length: `7` Max length: `7`
- `profile_image_url` (string, optional, default: https://example.com) — URL to the image that should be shown in Cash App next to payments made to this brand, typically the brand's logo. The image should be square and be at least 256x256. It must be less than 2MB in filesize. Acceptable file formats: - `.png` - `.jpg` - `.jpeg` Min length: `8` Max length: `8000`
- `metadata` (map from string to string, optional) — Freeform key-value pairs of arbitrary data associated with this resource. Keys and values must be passed as strings and not contain any personally identifiable information (PII). Min keys: `0` Max keys: `50` > Note: Nested keys are not supported.

### Error

Represents an error encountered during a request to the API.

- `category` (enum, required) — The high-level reason the error occurred.
  - Allowed values: `API_ERROR`, `AUTHENTICATION_ERROR`, `BRAND_ERROR`, `DISPUTE_ERROR`, `MERCHANT_ERROR`, `INVALID_REQUEST_ERROR`, `PAYMENT_PROCESSING_ERROR`, `RATE_LIMIT_ERROR`, `WEBHOOK_ERROR`, `API_KEY_ERROR`, `GRANT_ERROR`
- `code` (string, required) — A unique identifier for the specific type of error that occurred. For more information, see [Error Code Reference](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/errors/error-code-reference). Min length: `1`
- `detail` (string, optional) — Human-readable description of why the error occurred and how to resolve it. Min length: `1`
- `field` (string, optional) — The field in the request that caused the error, using array and object dot notation. Min length: `1`

## Examples

### Sample request with metadata

**Request**

```json
{
  "brand": {
    "name": "brand name",
    "reference_id": "reference ID",
    "profile_image_url": "https://example.com",
    "color": "#ffffff",
    "metadata": {
      "key": "value"
    }
  }
}
```

**Response**

```json
{
  "brand": {
    "id": "id",
    "name": "name",
    "created_at": "2021-01-01T00:00:00Z",
    "updated_at": "2021-01-01T00:00:00Z",
    "reference_id": "example-id",
    "color": "#ffffff",
    "profile_image_url": "https://example.com",
    "metadata": {
      "my-meta": "meta-value"
    }
  }
}
```

**SDK Code**

```python Sample request with metadata
import requests

url = "https://api.cash.app/network/v1/brands"

payload = { "brand": {
        "name": "brand name",
        "reference_id": "reference ID",
        "profile_image_url": "https://example.com",
        "color": "#ffffff",
        "metadata": { "key": "value" }
    } }
headers = {"Content-Type": "application/json"}

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

print(response.json())
```

```javascript Sample request with metadata
const url = 'https://api.cash.app/network/v1/brands';
const options = {
  method: 'PUT',
  headers: {'Content-Type': 'application/json'},
  body: '{"brand":{"name":"brand name","reference_id":"reference ID","profile_image_url":"https://example.com","color":"#ffffff","metadata":{"key":"value"}}}'
};

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

```go Sample request with metadata
package main

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

func main() {

	url := "https://api.cash.app/network/v1/brands"

	payload := strings.NewReader("{\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://example.com\",\n    \"color\": \"#ffffff\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}")

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

	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 Sample request with metadata
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/brands")

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

request = Net::HTTP::Put.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://example.com\",\n    \"color\": \"#ffffff\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}"

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

```java Sample request with metadata
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.put("https://api.cash.app/network/v1/brands")
  .header("Content-Type", "application/json")
  .body("{\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://example.com\",\n    \"color\": \"#ffffff\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}")
  .asString();
```

```php Sample request with metadata
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.cash.app/network/v1/brands', [
  'body' => '{
  "brand": {
    "name": "brand name",
    "reference_id": "reference ID",
    "profile_image_url": "https://example.com",
    "color": "#ffffff",
    "metadata": {
      "key": "value"
    }
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

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

```csharp Sample request with metadata
using RestSharp;

var client = new RestClient("https://api.cash.app/network/v1/brands");
var request = new RestRequest(Method.PUT);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://example.com\",\n    \"color\": \"#ffffff\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Sample request with metadata
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["brand": [
    "name": "brand name",
    "reference_id": "reference ID",
    "profile_image_url": "https://example.com",
    "color": "#ffffff",
    "metadata": ["key": "value"]
  ]] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/brands")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
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()
```

### Sample request without metadata

**Request**

```json
{
  "brand": {
    "name": "brand name",
    "reference_id": "reference ID",
    "profile_image_url": "https://example.com",
    "color": "#ffffff"
  }
}
```

**Response**

```json
{
  "brand": {
    "id": "id",
    "name": "name",
    "created_at": "2021-01-01T00:00:00Z",
    "updated_at": "2021-01-01T00:00:00Z",
    "reference_id": "example-id",
    "color": "#ffffff",
    "profile_image_url": "https://example.com",
    "metadata": {
      "my-meta": "meta-value"
    }
  }
}
```

**SDK Code**

```python Sample request without metadata
import requests

url = "https://api.cash.app/network/v1/brands"

payload = { "brand": {
        "name": "brand name",
        "reference_id": "reference ID",
        "profile_image_url": "https://example.com",
        "color": "#ffffff"
    } }
headers = {"Content-Type": "application/json"}

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

print(response.json())
```

```javascript Sample request without metadata
const url = 'https://api.cash.app/network/v1/brands';
const options = {
  method: 'PUT',
  headers: {'Content-Type': 'application/json'},
  body: '{"brand":{"name":"brand name","reference_id":"reference ID","profile_image_url":"https://example.com","color":"#ffffff"}}'
};

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

```go Sample request without metadata
package main

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

func main() {

	url := "https://api.cash.app/network/v1/brands"

	payload := strings.NewReader("{\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://example.com\",\n    \"color\": \"#ffffff\"\n  }\n}")

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

	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 Sample request without metadata
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/brands")

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

request = Net::HTTP::Put.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://example.com\",\n    \"color\": \"#ffffff\"\n  }\n}"

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

```java Sample request without metadata
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.put("https://api.cash.app/network/v1/brands")
  .header("Content-Type", "application/json")
  .body("{\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://example.com\",\n    \"color\": \"#ffffff\"\n  }\n}")
  .asString();
```

```php Sample request without metadata
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.cash.app/network/v1/brands', [
  'body' => '{
  "brand": {
    "name": "brand name",
    "reference_id": "reference ID",
    "profile_image_url": "https://example.com",
    "color": "#ffffff"
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

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

```csharp Sample request without metadata
using RestSharp;

var client = new RestClient("https://api.cash.app/network/v1/brands");
var request = new RestRequest(Method.PUT);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://example.com\",\n    \"color\": \"#ffffff\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Sample request without metadata
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["brand": [
    "name": "brand name",
    "reference_id": "reference ID",
    "profile_image_url": "https://example.com",
    "color": "#ffffff"
  ]] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/brands")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
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()
```