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.

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:

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 and Create a product with plans and charges.

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.