Guidelines to create orders with advance multi action template

Last updated
Save as PDF

This guide provides the step-by-step process for creating orders with Data Loader, with Advance Multi Action template.

Best practices for using advance multi action template

The IsMarker column in Data Loader templates show when a new object needs to be created. The IsNew marker columns in the CSV file are used to signal when new records should be created in the context of the file, not within Zuora Billing. See Guidelines for CSV file upload in Data Loader for more information.

CSV Format: Ensure your CSV file is in UTF-8 format and does not contain duplicate or empty headers.
Date Fields: Verify that all date fields are correctly formatted according to the supported date formats in the Data Dictionary.
File Size: The maximum allowed file size for Data Loader is 1GB.
Testing: Before importing data into the production environment, test your CSV file in a sandbox environment to ensure accuracy.
Download template from target tenant: To ensure accurate field mapping, especially for custom fields, it is essential to download the Data Loader template directly from the specific Zuora tenant where the data upload will occur. Zuora's Data Loader automatically maps CSV column headers to the corresponding fields in the tenant. By using a template from the target tenant, you ensure that all fields, including custom ones, align correctly, reducing the risk of mapping errors. Zuora tenant can have different custom fields. Templates downloaded from the specific tenant will include these fields, ensuring they are available for data import and reducing the chance of missing critical information.

The Zuora Data Loader Advance Multi Action Template template offers flexibility, allowing users to tailor the CSV file to their specific business requirements. This means you can retain only the necessary columns pertinent to your operation and remove any irrelevant ones. However, to ensure successful data imports, it's crucial to include all mandatory fields and correctly utilize the corresponding IsMarker columns.

Step 1: Preparing for Order Import Job

Customize your template:
- Retain Necessary Columns: Keep only the columns that are essential for your specific operation. This streamlines the import process and reduces potential errors.
- Remove Irrelevant Columns: Eliminate any columns that are not applicable to your current data import task.
Understand and utilize IsMarker columns:
- IsMarker columns indicate the beginning of a new object within your data hierarchy. For example, IsNewOrder signifies the start of a new order.
- When setting an IsMarker column to TRUE, ensure all mandatory fields for that object are populated in the same row.
- For subsequent rows related to the same object, set the IsMarker column to FALSE or leave it blank.
Include all mandatory fields:
- Mandatory fields are essential for the successful creation or update of records. See Data Dictionary for Advance Multi Action Orders to identify required fields for each object.
Example: Creating Multiple Charge Overrides:
- First Row (New Order and Subscription):
  - IsNewOrder: TRUE
  - Existing Account Number: [Provide account number]
  - Order Date: [Provide order date]
  - IsNewSubscription: TRUE
  - [Include all other mandatory fields]
- Subsequent Rows (Additional Charges):
  - IsNewOrder: FALSE or leave blank
  - IsNewSubscription: FALSE or leave blank
  - [Include fields specific to the charge override]This structure ensures that all charge overrides are associated with the same order and subscription.

Step 2: Executing the Job

Navigate to Data Loader, click +New icon on the landing screen
Select Import > Orders > Advance Multi Action Template
Download the Template
Select the required columns, the appropriate IsMarkerColumns and fill values
Upload the template

Refe to the sample templates attached below.

Step 3: Verification

Zuora's Data Loader automatically maps CSV column headers to the corresponding fields in the tenant.When on the Field Mapping Interface, select the Mapped checkbox, this will allow you to recheck the fields that are mapped by data loader. This will be particularly useful if the csv has many fields. However, when dealing with CSV files containing numerous fields, it's crucial to verify that all necessary fields, especially custom ones, are correctly mapped. To facilitate this, the Field Mapping interface in Data Loader provides a Mapped checkbox. Selecting this checkbox filters the view to display only the fields that have been successfully mapped.

Best Practices

Verify Required Fields: Ensure that all mandatory fields are included and correctly mapped. Data Loader displays a warning message to guide you, as unmapped required fields can cause errors.
Manual Mapping: If automatic mapping does not identify all fields, you can manually map the CSV columns by selecting the appropriate target fields from the dropdown menus in the Field Mapping interface.Similarly, you can map the unmapped fields by selecting the unmapped check box as well if required.

Step 4: Preview and Submit

Data Loader allows the user to validate any exceptions with the configurations in the tenant on this interface. This allows the user to check the data and make in-line modifications as the exceptions are highlighted in amber color for each cell.

Step 5: Completion

Submit the job. Data Loader displays the failed and successful records. The failed records can be validated,modified and re-submitted with the interface.

Sample Templates

The Zuora Data Loader Advance Multi Action Template template is designed for flexibility, allowing users to tailor the CSV file to their specific data migration needs. This means you can retain only the columns necessary for your operation and remove any that are not required. However, it's crucial to ensure that all mandatory fields—indicated by an asterisk (*) in the template—are included to prevent errors during the data import process.

By customizing the template to include only relevant fields, you can streamline the data preparation process and focus on the information pertinent to your business requirements. These customized templates can be reused for future data loads, provided there are no changes to the field configurations in your Zuora tenant.

If there have been modifications to the tenant's configuration—such as the addition of new custom fields or changes to existing ones—it's recommended to download a fresh template directly from the target tenant. This ensures that your template reflects the most up-to-date field configurations, maintaining alignment between your data and the tenant's current setup.

Add Product with Recurring Flat Fee Charge

The file provided is designed to add a product with a recurring flat fee override to an existing account using Zuora's Data Loader Advance Multi Action Template template. Here are the column headers and a brief description of the headers.

Column Name	Description
Trigger Dates Trigger Date	The specific date when the order action is triggered.
Trigger Dates Name	Defines when the order takes effect (e.g., ContractEffective).
Subscriptions Subscription Number	Specifies the existing subscription number if modifying. Required if not creating a new one.
Processing Options Run Billing	Boolean flag indicating if billing should be triggered. Optional.
Processing Options Collect Payment	Boolean flag indicating if payment should be collected. Optional.
Order Date*	The effective date for the order. Required.
Order Actions Change Reason	Optional explanation for the order action.
IsNewTriggerDate	Boolean value that specifies whether a new trigger condition is defined.
IsNewSubscription	Indicates whether a new subscription is being created. Should be True for the first row of a new subscription.
IsNewOrderAction	Boolean flag indicating if a new order action is being defined. Required for each distinct action.
IsNewOrder*	Indicates if a new order is being created. Required and should be True for the first line of each new order.
IsNewCharge	Indicates if a new charge override is being applied. Should be True for the first override line.
Existing Account Number*	The customer account number to which the order is being added. Required.
Description	Optional text describing the order.
Charge Type*	Defines the type of charge (e.g., recurringFlatFee). Required.
Charge Product Rate Plan Charge Id*	ID of the charge in the product rate plan. Required.
Charge List Price	Price override for the charge. Optional if using default pricing.
Category	Optional descriptive field to classify the order.
Action Type*	Defines the action type such as addProduct. Required.
Action Product Rate Plan Id	ID of the product rate plan being added. Required for product-related actions.

Only required columns (marked with an asterisk *) must be included to process the job successfully.
This file is a minimal and effective template for adding a product to an existing account and customizing the charge price using charge overrides.
Columns unrelated to this specific use case (e.g., order line items, discounts, usage charges) are intentionally removed for clarity and ease of use.

Renew Subscription and Remove Product

This file appears to handle a use case involving subscription renewal and product removal within a single order using multiple order actions.

Column Name	Description
IsNewOrder*	Required. Indicates whether a new order is being created (True for the first row of the order).
Existing Account Number*	Required. Specifies the Zuora account number to which the order will be applied.
Order Date*	Required. The effective date of the order.
Category, Description	Optional metadata fields for order classification and notes.
Processing Options Collect Payment, Processing Options Run Billing	Flags to control billing and payment during processing.
IsNewSubscription	Indicates whether a new subscription is being created (True) or not. In this case, it's a renewal, so it references an existing subscription.
Subscriptions Subscription Number	Required for actions on existing subscriptions, such as renewals or product removals.
IsNewOrderAction	Required. Indicates the beginning of a new order action. Multiple True entries imply multiple actions in the same order.
Order Actions Change Reason	Optional. Use this field to document the reason for the order action (e.g., business justification).
IsNewTriggerDate, Trigger Dates Name, Trigger Dates Trigger Date	These columns control when the order action is triggered. Typically ContractEffective for renewals.
Action Type*	Required. Type of action such as renewSubscription, removeProduct.
Action Product Rate Plan Id	Required for actions involving product manipulation (e.g., add/remove).
IsNewCharge, Charge Product Rate Plan Charge Id, Charge Type, Charge List Price	Optional. Relevant if you are overriding pricing for a product being added, not used here.

The file uses multiple rows to define distinct order actions (renew and remove product) in a single order, which is efficient for complex order workflows.
Only necessary columns are retained, making the file clean and focused.
Charge override fields are unused, as this file is not adding or customizing charges.
Use this template when you want to renew an existing subscription and remove a product within the same order.
Make sure IsNewOrder is marked True only on the first row.
For each action (renew, removeProduct), set IsNewOrderAction to True and provide appropriate fields.
If custom fields or new rate plans are added to the tenant, download a fresh template to capture updated configurations.

Create Subscription with Multiple Rate Plans

This file is used to create a subscription with multiple rate plans and charge configurations.

Column Name	Description
IsNewOrder	Indicates the start of a new order. Only marked True for the first row of the order.
Existing Account Number*	Identifies the customer account in Zuora Billing. Required.
Order Date*	Date on which the order is placed. Required.
IsNewSubscription	Marks whether a new subscription is being created.
Action Type*	Specifies the action to be performed (e.g., createSubscription). Required.
IsNewOrderAction, Order Actions Change Reason	Indicates if a new order action is being defined in the current row.
IsNewRatePlanSubscribeToRatePlans	Marks the addition of a new rate plan under the subscription.
Action Subscribe To Rate Plans Product Rate Plan Id*	Identifies the product rate plan being added. Required when subscribing to rate plans
IsNewCharge	Indicates the start of a new charge being configured.
Charge Product Rate Plan Charge Id*	Identifies the specific charge within the product rate plan. Required.
Charge Type*	Specifies the charge type (e.g., recurringTiered, oneTimeFlatFee).
Charge Tier Number*	Used for tiered charges to specify the tier index.
Charge Tier Price*	The price for that tier
Charge Tier Starting Unit*, Charge Tier Ending Unit	Used in tiered pricing to define unit ranges.
Charge List Price	Price for flat fee or one-time charges

This template is designed to:

Create a new order and subscription.
Add multiple rate plans under the subscription.
Configure both tiered and flat fee charges within the same subscription.

Each row continues a specific part of the order structure. By marking IsNewOrderAction, IsNewCharge, and other flags appropriately, this structure supports complex product setups

Data Dictionary for Advance Multi Action Orders

See Advance Multi Action Order Data Dictionary and the following sample CSV files with Data:

Known Facts

Data Loader is considering the support for the following fields:

OrderAction	ArrayofObject	Fields
AddProduct	ChargeOverrides	ratingPropertiesOverride isProrateParticlaMonth prorationunit daysInMonth accountReceivableAccCode
AddProduct	ChargeOverrides>Pricing> recurringdeliverybased	recurringdeliverybased pricechangeoption priceincreaseoption deliveryschedule listprice priceIntervals
Create Subscription, Owner Transfer, Terms and Conditions		PaymentProfile Payment GatewayID PaymentMethodID
Create Subscription		newSubOwnerAccount billtocontact taxInfo soldtocontact

Data Loader does not support credit card fields
Scheduling orders fields are not supported.