> This page is for Docs.

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

# API enhancements for Multi-Org

> This reference lists the API enhancements for Multi-Org, including the new fields and headers for account creation and data visibility management, when Multi-Org is enabled.

This reference lists the API enhancements for Multi-Org, including the new fields and headers for account creation and data visibility management, when Multi-Org is enabled.

An org unit represents a business unit that operates independently and can sell products to multiple customers. Each org unit has its own isolated environment in which the org users can perform business operations independent of the other org units.

## New field for account creation

`organizationLabel`: Specifies the name of the organization that the account belongs to.

## New headers for data visibility

The following headers are supported for all Zuora public APIs and apply only when Multi-Org is enabled:

* `Zuora-Org-Ids`
* `Zuora-Working-Org`

These headers limit the data visibility for query APIs. The dataset that is returned is specific to the orgs specified in the headers.

The following query returns account data that is filtered based on the user's org labels and the Zuora-Org-Ids header:

```
POST/query/jobs
{
"query" : "select accountnumber, balance from account"
  ...
}
```

Depending on the user's org labels, `Zuora-Org-Ids` header, a different dataset would be returned for different scenarios:

> **Note**
>
> The `Zuora-Org_Ids` values in the examples are sample UUIDs only.

| User's Org Label   | Zuora-Org_Ids                                                                               | Description                                                                      |
| ------------------ | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Asia, China, Japan | N/A                                                                                         | Returns all accounts for the specified orgs.                                     |
| Asia, China, Japan | `550e8400-e29b-41d4-a716-446655440000`(Asia)                                                | Returns only the accounts for the specified orgs.                                |
| Asia, China, Japan | `550e8400-e29b-41d4-a716-446655440000`(Asia), `788205ee-dba6-419b-b2f5-90674c3b962b`(China) | Returns only the accounts for the specified orgs.                                |
| Asia               | `788205ee-dba6-419b-b2f5-90674c3b962b`(China)                                               | Returns an invalid request error because the user does not have access to China. |

## Create and label product rate plans in Multi-Org

When you create a product rate plan in Multi-Org, its organization labels are based on the labels assigned to its parent product.

* If the parent product has one organization label, the product rate plan inherits that label.
* If the parent product has multiple organization labels, select one or more of those labels for the product rate plan.

For V1 and V2 creation API flows, the product rate plan inherits the organization labels assigned to the product. For the request fields and examples, see [Create a product rate plan](https://developer.zuora.com/v1-api-reference/api/commerce/createplan) and [Create a product with plans and charges](https://developer.zuora.com/v1-api-reference/api/commerce/createproduct).

> **Note**
>
> Do not use `Zuora-Org-Ids` or `Zuora-Working-Org` as a substitute for labeling product catalog data. These headers define the request or data-visibility context, whereas the Data Labeling API applies organization labels to the data.

## Behavior of Zuora-Working-Org for creation APIs

`Zuora-Working-Org` will be used as the default org label value if the org label is not explicitly specified or there is no inheritance rule in place.

For example, to create a standalone invoice `accountid` is required. In this case, the invoice simply inherits the account org.

If there are no inheritance rules defined, the create action is labeled with the org specified by the `Zuora-Working-Org` header.

For example, to create an Account object through the Create Action call `POST/v1/action/create` the product will be labeled with the org specified in the `Zuora-Working-Org` header.

To see how all operations are supported for Multi-Org hierarchy management through REST API, see [API Reference](https://developer.zuora.com/v1-api-reference/introduction/).