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

# Event: merchant.status.updated

POST 

**When is this event triggered?**

This event is created whenever a merchant's status is changed. The status change can be due to do many different things:
  - An API client-initiated action to disable / enable the merchant
  - An asynchronous merchant registration process completing, moving the merchant from pending to active
  - A compliance ban on the merchant, moving them to disabled

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/merchant-status-updated

## Request

### Payload

- `type` (string, required) — The type of event that occurred. `merchant.status.updated` for this event.
- `event_id` (string, required) — A unique identifier provided by Cash App for the event.
- `created_at` (datetime, required) — When this event occured in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC). The time that the event is delivered may be significantly later than this timestamp due to webhooks being retried for up to 72 hours.
- `data` (MerchantStatusUpdatedPayloadData, required) — Data about the merchant that had a status change.

## Types

### MerchantStatusUpdatedPayloadData

Data about the merchant that had a status change.

- `id` (string, required) — A unique identifier provided by Cash App for the merchant.
- `object` (MerchantStatusUpdatedPayloadDataObject, required) — A snapshot of the merchant data immediately after the merchant's status changed.
- `type` (string, required) — The resource type contained in the `object` field. For this event, it is `merchant`.

### MerchantStatusUpdatedPayloadDataObject

A snapshot of the merchant data immediately after the merchant's status changed.

- `merchant` (Merchant, required) — A merchant represents a depository account when processing payments from Cash App customers. Merchants do not have direct access to Cash App, so processed payments are stored in this account until they are ready for settlement.

### Merchant

A merchant represents a depository account when processing payments from Cash App customers. Merchants do not have direct access to Cash App, so processed payments are stored in this account until they are ready for settlement.

- `id` (string, required) — A unique identifier for the merchant issued by Cash App. Min length: `1` Max length: `128`
- `brand_id` (string, required) — ID of the brand associated with this merchant. Min length: `1` Max length: `128`
- `name` (string, required) — The name of the individual or business entity associated with the merchant. Min length: `1` Max length: `1024`
- `country` (enum, required) — Indicates the country associated with an entity. Values are from the [ISO-3166 Alpha-2](https://www.iso.org/iso-3166-country-codes.html) specification. Current values: - `US`: United States of America
  - Allowed values: `US`
- `currency` (enum, required) — Indicates the country associated with an entity. Values are from the [ISO-4217 Alpha-3](https://www.iso.org/iso-4217-currency-codes.html) specification. Current values: - `USD`: United States Dollar
  - Allowed values: `USD`
- `category` (string, required) — The merchant category code associated with the entity. Values are from the [ISO-18245 specification](https://www.iso.org/standard/33365.html).
- `reference_id` (string, required) — A user-defined identifier for this merchant, typically used to associate the merchant with a record in an external system. Independent from the [brand reference_id](https://developers.cash.app/docs/api/network-api/operations/create-a-brand#request-body). Min length: `1` Max length: `1024`
- `status` (enum, required) — Whether or not this merchant can be used to accept payments or issue refunds. * `ACTIVE`: The merchant can accept payments or issue refunds. * `RISK_DISABLED`: Cash App Pay blocked this merchant due to them being high risk. There is no way to re-enable them programmaticaly. * `COMPLIANCE_DISABLED`: Cash App Pay blocked this merchant due to them not following the terms of service, Program Rules, or local laws. There is no way to re-enable them programmaticaly. * `CLIENT_DISABLED`: The client called the [UpdateMerchant](Network-API.v1.yaml/paths/~1merchants~1\{merchant_id}/patch) endpoint and disabled this merchant, preventing it from being able to handle payments or refunds. To reverse this, call the endpoint again with the status field set to `ACTIVE`. * `PENDING`: The merchant is not ready to accept payments or refunds yet; the registration process is still running.
  - Allowed values: `ACTIVE`, `RISK_DISABLED`, `COMPLIANCE_DISABLED`, `CLIENT_DISABLED`, `PENDING`
- `created_at` (datetime, required) — When this merchant was created, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
- `updated_at` (datetime, required) — When this merchant was last updated, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
- `address` (Address, required) — Where this entity is located
- `site_url` (string, optional) — The URL of the website, if this merchant is for an eCommerce site. 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.
- `default_fee_plans` (MerchantFeePlans, optional) — Merchant fee plans contains the IDs of the different fee plans for a merchant. These IDs represent the processing fees that merchants will be charged for processing payments for each channel. You can use the Fee Plans API to get all the fee information for each fee plan.

### Address

Where this entity is located

- `country` (enum, required) — Indicates the country associated with an entity. Values are from the [ISO-3166 Alpha-2](https://www.iso.org/iso-3166-country-codes.html) specification. Current values: - `US`: United States of America
  - Allowed values: `US`
- `address_line_1` (string, optional) — First line of the street address, typically including street number, street name, and / or building name. Min length: `1` Max length: `1024`
- `address_line_2` (string, optional) — Second line of the address, if any. Min length: `1` Max length: `1024`
- `locality` (string, optional) — City or township where the entity is located. Min length: `1` Max length: `1024`
- `postal_code` (string, optional) — ZIP or postal code. Min length: `1` Max length: `128`
- `administrative_district_level_1` (string, optional) — State or province. Min length: `1` Max length: `1024`

### MerchantFeePlans

Merchant fee plans contains the IDs of the different fee plans for a merchant. These IDs represent the processing fees that merchants will be charged for processing payments for each channel. You can use the Fee Plans API to get all the fee information for each fee plan.

- `in_app_fee_plan_id` (string, optional) — The fee plan ID identifying the fee plan that will be used for all in-app payments.
- `in_person_fee_plan_id` (string, optional) — The fee plan ID identifying the fee plan that will be used for all in-person payments.
- `online_fee_plan_id` (string, optional) — The fee plan ID identifying the fee plan that will be used for all online payments.