> This page is for Developers. > 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. # Create product charge definitions POST https://rest.test.zuora.com/v1/product-charge-definitions/bulk Content-Type: application/json Bulk creates product charge definitions for a charge. You can create up to 1000 product charge definitions at a given time for a specific charge. In the request, you must specify the unique ID or number of the charge for which this charge definition is to be created. The ID or number of a product rate plan is optional. **Note**: This operation requires the [Attribute-based Pricing](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Attribute_based_pricing/AA_Overview_of_Attribute-based_Pricing) feature to be enabled, which is in the **Early Adopter** phase. Reference: https://zuora.ferndocs.com/developers/api-reference/zuora-api/legacy-v1-products/product-charge-definitions/post-create-product-charge-definition-bulk ## Authentication - `Authorization` header (bearer token, required) — Use `Bearer {{token}}` in the `Authorization` header for authentication. ## Servers - `https://rest.test.zuora.com` (US Developer & Central Sandbox (incl. Test Drive), default) - `https://rest.sandbox.na.zuora.com` (US API Sandbox Cloud 1) - `https://rest.apisandbox.zuora.com` (US API Sandbox Cloud 2) - `https://rest.na.zuora.com` (US Production Cloud 1) - `https://rest.zuora.com` (US Production Cloud 2) - `https://rest.test.eu.zuora.com` (EU Developer & Central Sandbox) - `https://rest.sandbox.eu.zuora.com` (EU API Sandbox) - `https://rest.eu.zuora.com` (EU Production) - `https://rest.test.ap.zuora.com` (APAC Developer & Central Sandbox) - `https://rest.ap.zuora.com` (APAC Production) ## Request ### Headers - `Idempotency-Key` (string, optional) — Specify a unique idempotency key if you want to perform an idempotent POST or PATCH request. Do not use this header in other request types. With this header specified, the Zuora server can identify subsequent retries of the same request using this value, which prevents the same operation from being performed multiple times by accident. - `Accept-Encoding` (string, optional) — Include the `Accept-Encoding: gzip` header to compress responses as a gzipped file. It can significantly reduce the bandwidth required for a response. If specified, Zuora automatically compresses responses that contain over 1000 bytes of data, and the response contains a `Content-Encoding` header with the compression algorithm so that your client can decompress it. - `Content-Encoding` (string, optional) — Include the `Content-Encoding: gzip` header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload. - `Zuora-Track-Id` (string, optional) — A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue. The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (`:`), semicolon (`;`), double quote (`"`), and quote (`'`). - `Zuora-Entity-Ids` (string, optional) — An entity ID. If you have [Zuora Multi-entity](https://knowledgecenter.zuora.com/BB_Introducing_Z_Business/Multi-entity) enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you should not set this header. - `Zuora-Version` (string, optional) — The minor API version. For a list of available minor versions, see [API upgrades](https://developer.zuora.com/v1-api-reference/api-upgrades/). ### Body (application/json) This endpoint expects a POSTChargeDefinitionRequestBulk. - `productChargeDefinitions` (list of POSTChargeDefinitionRequest, optional) — Container for the array of product charge definition. ## Response ### 200 OK - `summary` (PostChargeDefinitionBulkResponseSummary, optional) — Summary of the results of the bulk operation. - `results` (list of PostChargeDefinitionBulkResponseResultsItems, optional) — The list of newly created product charge definitions or errors. - `success` (boolean, optional) — Indicates whether the request succeeded. ## Errors ### 500 Internal Server Error Internal Server Error - `reasons` (list of ErrorResponseReasonsItems, optional) ### 400 Client Request Error Request Errors - `processId` (string, optional) — The ID of the process that handles the operation. - `reasons` (list of CommonResponseReasonsItems, optional) — The container of the error code and message. This field is available only if the `success` field is `false`. - `requestId` (string, optional) — Unique identifier of the request. - `success` (boolean, optional) — Indicates whether the call succeeded. ## Types ### POSTChargeDefinitionRequest - `billingPeriod` (string, optional) — The billing period for the product charge definition. - `billingTiming` (enum, optional) — The billing timing setting for the product charge definition. - Allowed values: `IN_ADVANCE`, `IN_ARREARS` - `chargeModel` (enum, optional) — Determines how to calculate charges. Charge models must be individually activated in Zuora Billing administration. - Allowed values: `DiscountFixedAmount`, `DiscountPercentage`, `FlatFee`, `PerUnit`, `Tiered`, `Volume`, `Delivery` - `defaultQuantity` (double, optional, nullable) — The default quantity. This field is applicable only for one-time and recurring charges. - `effectiveEndDate` (datetime, optional) — The effective end date of the product charge definition. - `effectiveStartDate` (datetime, optional) — The effective start date of the product charge definition. - `listPriceBase` (enum, optional) — The list price base. This field is applicable only for recurring charges. **Note**: The `Per_Year` enum value is available only if you have the Annual List Price feature enabled. - Allowed values: `Per_Billing_Period`, `Per_Month`, `Per_Week`, `Per_Year` - `prices` (list of POSTProductChargeDefinitionPricing, optional) — Container for the prices of the product charge definition. - `productRatePlanChargeId` (string, optional) — The unique ID of the charge of the charge definition. - `productRatePlanChargeNumber` (string, optional) — The unique number (natural key) of the charge of the charge definition. - `productRatePlanId` (string, optional) — The unique ID of the product rate plan that uses this charge definition. - `productRatePlanNumber` (string, optional) — The unique number (natural key) of the product rate plan that uses this charge definition. - `specificBillingPeriod` (double, optional, nullable) — The specific number of billing periods for the product charge definition. - `specificListPriceBase` (integer, optional, nullable) — The number of months for the list price base of the charge definition. This field is `null` if the `listPriceBase` field is not set to `Per_Specific_Months`. - `taxCode` (string, optional) — Specifies the tax code for taxation rules. This field is required when the `Taxable` field is set to `True`. **Note**: This value affects the tax calculation of the charge. - `taxMode` (enum, optional, nullable) — Determines how to define taxation for the charge. This field is required when the `Taxable` field is set to `True`. **Note**: This value affects the tax calculation of the charge. - Allowed values: `TaxExclusive`, `TaxInclusive` - `taxable` (boolean, optional) — Determines whether the charge definition is taxable. When this field is set to `True`, the `TaxMode` and `TaxCode` fields are required. **Character limit**: 5 **Values**: `True`, `False` **Note**: This value affects the tax calculation of the charge. - `term` (double, optional, nullable) — The number of periods of a termed subscription that is eligible for this charge definition. This field is applicable when the `termType` field is set to `TERMED`, and is to be used together with the `termPeriodType` field. - `termPeriodType` (enum, optional, nullable) — Specifies the period type for the subscription term that is eligible for this charge definition. - Allowed values: `Month`, `Year`, `Day`, `Week` - `termType` (enum, optional, nullable) — The type of the subscription that is eligible for this charge definition. - Allowed values: `TERMED`, `EVERGREEN` - `uom` (string, optional, nullable) — Describes the unit of measure (UOM) configured in **Settings > Billing** for the charge. ### PostChargeDefinitionBulkResponseSummary Summary of the results of the bulk operation. - `successCount` (integer, optional) — The number of product charge definitions successfully created. - `failureCount` (integer, optional) — The number of product charge definitions that are not created. - `failures` (list of integer, optional) — An array containing the index of each failed charge definition. Each index is zero-based, and refers to the position of the invalid product charge definition in the bulk payload. ### PostChargeDefinitionBulkResponseResultsItems - `success` (boolean, optional) — Indicates whether the charge definition is successfully created. - `chargeDefinitionId` (string, optional) — The unique ID of the product charge definition. This value is available only if this product charge definition is successfully created. - `chargeDefinitionNumber` (string, optional) — The unique number (natural key) of the product charge definition. This value is available only if this product charge definition is successfully created. - `processId` (string, optional) — The ID of the process that handles the operation. This value is available only if this product charge definition is not created. - `reasons` (list of PostChargeDefinitionBulkResponseResultsItemsReasonsItems, optional) — Array of data containing the error code and reasons for failure. This value is available only if this product charge definition is not created. ### ErrorResponseReasonsItems - `code` (string, optional) — The error code of response. - `message` (string, optional) — The detail information of the error response ### CommonResponseReasonsItems - `code` (string, optional) — The error code of response. - `message` (string, optional) — The detail information of the error response ### POSTProductChargeDefinitionPricing - `currency` (string, optional) — The currency for the price. - `discountAmount` (double, optional) — The specific amount for a fixed discount. The field is applicable only for charges based on the Discount-Fixed Amount charge model. - `discountPercentage` (double, optional) — The percentage of discount for a percentage discount. The field is applicable only for charges based on the Discount-Percentage charge model. - `price` (double, optional) — The price of this item. This field is only applicable for charges based on the following charge models: - Flat Fee - Per Unit - Delivery Pricing - `tiers` (list of list of PostChargeDefinitionPricingTierItems, optional) — Container for the tiers of the price item. This field is only applicable for charges based on the following charge models: * Tiered Pricing * Volume Pricing You must specify all relevant fields of all tiers, including pricing information for each currency. For each currency, ensure that the tiers appear in ascending order of `StartingUnit`. For example: ``` [ { "startingUnit": "1", "endingUnit": "150", "currency": "USD", "price": 1.95, "priceFormat": "Per Unit" }, { "startingUnit": "151", "endingUnit": "300", "currency": "USD", "price": 1.45, "priceFormat": "Per Unit" }, { "startingUnit": "1", "endingUnit": "150", "currency": "EUR", "price": 1.75, "priceFormat": "Per Unit" }, { "startingUnit": "151", "endingUnit": "300", "currency": "EUR", "price": 1.30, "priceFormat": "Per Unit" } ] ``` ### PostChargeDefinitionBulkResponseResultsItemsReasonsItems - `message` (string, optional) — Message explaining the reason for the error. - `code` (string, optional) — Specifies the error code associated with the error. ### PostChargeDefinitionPricingTierItems - `currency` (string, optional) — The code corresponding to the currency for the tier's price. - `endingUnit` (double, optional) — The end number of a range of units for the tier. This field is required for charges based on the Tiered Pricing or Tiered with Overage Pricing charge model. - `price` (double, optional) — The price of the tier if the price format is flat fee, or the price of each unit in the tier if the price format is per unit. - `priceFormat` (enum, optional) — The price format of the tier. - Allowed values: `Flat Fee`, `Per Unit` - `startingUnit` (double, optional) — The starting number of a range of units for the tier. This field is required for charges based on the Tiered Pricing or Tiered with Overage Pricing charge model. ## Examples **Request** ```json { "productChargeDefinitions": [ { "effectiveEndDate": "2025-01-01 00:00:00", "effectiveStartDate": "2024-01-01 00:00:00", "listPriceBase": "Per_Billing_Period", "prices": [ { "currency": "USD", "price": 18 } ], "productRatePlanChargeId": "edcab92612893256dce329d0b377000e" } ] } ``` **Response** ```json { "summary": { "successCount": 1, "failureCount": 0, "failures": [] }, "results": [ { "success": true, "chargeDefinitionId": "8a9084f99325571d01932a15d64a3a1b", "chargeDefinitionNumber": "CD-00052014" } ], "success": true } ``` **SDK Code** ```python response import requests url = "https://rest.test.zuora.com/v1/product-charge-definitions/bulk" payload = { "productChargeDefinitions": [ { "effectiveEndDate": "2025-01-01 00:00:00", "effectiveStartDate": "2024-01-01 00:00:00", "listPriceBase": "Per_Billing_Period", "prices": [ { "currency": "USD", "price": 18 } ], "productRatePlanChargeId": "edcab92612893256dce329d0b377000e" } ] } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript response const url = 'https://rest.test.zuora.com/v1/product-charge-definitions/bulk'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"productChargeDefinitions":[{"effectiveEndDate":"2025-01-01 00:00:00","effectiveStartDate":"2024-01-01 00:00:00","listPriceBase":"Per_Billing_Period","prices":[{"currency":"USD","price":18}],"productRatePlanChargeId":"edcab92612893256dce329d0b377000e"}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go response package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://rest.test.zuora.com/v1/product-charge-definitions/bulk" payload := strings.NewReader("{\n \"productChargeDefinitions\": [\n {\n \"effectiveEndDate\": \"2025-01-01 00:00:00\",\n \"effectiveStartDate\": \"2024-01-01 00:00:00\",\n \"listPriceBase\": \"Per_Billing_Period\",\n \"prices\": [\n {\n \"currency\": \"USD\",\n \"price\": 18\n }\n ],\n \"productRatePlanChargeId\": \"edcab92612893256dce329d0b377000e\"\n }\n ]\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") 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 response require 'uri' require 'net/http' url = URI("https://rest.test.zuora.com/v1/product-charge-definitions/bulk") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"productChargeDefinitions\": [\n {\n \"effectiveEndDate\": \"2025-01-01 00:00:00\",\n \"effectiveStartDate\": \"2024-01-01 00:00:00\",\n \"listPriceBase\": \"Per_Billing_Period\",\n \"prices\": [\n {\n \"currency\": \"USD\",\n \"price\": 18\n }\n ],\n \"productRatePlanChargeId\": \"edcab92612893256dce329d0b377000e\"\n }\n ]\n}" response = http.request(request) puts response.read_body ``` ```java response import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://rest.test.zuora.com/v1/product-charge-definitions/bulk") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"productChargeDefinitions\": [\n {\n \"effectiveEndDate\": \"2025-01-01 00:00:00\",\n \"effectiveStartDate\": \"2024-01-01 00:00:00\",\n \"listPriceBase\": \"Per_Billing_Period\",\n \"prices\": [\n {\n \"currency\": \"USD\",\n \"price\": 18\n }\n ],\n \"productRatePlanChargeId\": \"edcab92612893256dce329d0b377000e\"\n }\n ]\n}") .asString(); ``` ```php response request('POST', 'https://rest.test.zuora.com/v1/product-charge-definitions/bulk', [ 'body' => '{ "productChargeDefinitions": [ { "effectiveEndDate": "2025-01-01 00:00:00", "effectiveStartDate": "2024-01-01 00:00:00", "listPriceBase": "Per_Billing_Period", "prices": [ { "currency": "USD", "price": 18 } ], "productRatePlanChargeId": "edcab92612893256dce329d0b377000e" } ] }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp response using RestSharp; var client = new RestClient("https://rest.test.zuora.com/v1/product-charge-definitions/bulk"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"productChargeDefinitions\": [\n {\n \"effectiveEndDate\": \"2025-01-01 00:00:00\",\n \"effectiveStartDate\": \"2024-01-01 00:00:00\",\n \"listPriceBase\": \"Per_Billing_Period\",\n \"prices\": [\n {\n \"currency\": \"USD\",\n \"price\": 18\n }\n ],\n \"productRatePlanChargeId\": \"edcab92612893256dce329d0b377000e\"\n }\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift response import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["productChargeDefinitions": [ [ "effectiveEndDate": "2025-01-01 00:00:00", "effectiveStartDate": "2024-01-01 00:00:00", "listPriceBase": "Per_Billing_Period", "prices": [ [ "currency": "USD", "price": 18 ] ], "productRatePlanChargeId": "edcab92612893256dce329d0b377000e" ] ]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://rest.test.zuora.com/v1/product-charge-definitions/bulk")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" 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() ```