Mass Convert Inventory Records

Purpose

To mass convert inventory records. The following are the conversions you can perform:

Quotes to Sales Orders or Invoices
Sales Orders to Invoices

You can convert up to 50 records in a single API call. Note that you can perform the conversion on records from only one of these inventory modules in a single API call. It operates asynchronously, meaning you won't receive an immediate response to your request. Instead, you'll be provided with a job ID, with which you can check the status of your conversion request using Mass Inventory Records Convert Status API.

Endpoints

POST /Quotes/actions/mass_convert
POST /Sales_Orders/actions/mass_convert

Request Details

Request URLs

To convert Quotes module records to Sales_Orders or Invoices:

{api-domain}/crm/{version}/Quotes/actions/mass_convert

To convert Sales Orders records to Invoices:

{api-domain}/crm/{version}/Sales_Orders/actions/mass_convert

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

scope= ZohoCRM.mass_convert.{module_api_name}.CREATE
Note:Specify the API name of the parent module from which you are trying to convert.

Possible modules names

Quotes, and Sales Orders

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v7/Quotes/actions/mass_convert"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@input.json"
-X POST

Input JSON

convert_toJSON array, mandatory
It represents the details of the module to which you want to convert the record. In the sample request, you can see the conversion of Quotes to Sales Orders.
- moduleJSON object, mandatory
  It represents the module details of the child record.
  - idstring, mandatory
    It represents the unqiue ID of the child module.
  - api_namestring, mandatory
    It represents the api_name of the child module.
carry_over_tagsboolean, mandatory
Specify whether to carry over the tags from the parent record to the child records. Possible values are : true and false.
assign_toJSON object, optional
Specify the owner details for the child record. By default, the owner of the parent record will be assigned as the owner of the converted record too. Use the Get Users API to get the IDs of the users.
related_modulesJSON array, optional
It represents the API name and ID of the related modules such as Tasks, Meetings, and Calls. Use this key if you want to convert the related records associated with the requested records.
Use the Modules API to get the IDs of the modules.
idsJSON array, mandatory
Specify the unique ID of the records that you want to convert. Use the Get Records API to get the record IDs. You can specify upto 50 record IDs. Use the Get Records API to get the record IDs.

Note

The record being converted is considered the parent record, and the converted record is considered as the child record.

Sample Input

Copied{
    "convert_to": [
        {
            "module": {
                "id": "2423488000000000171",
                "api_name": "Sales_Orders"
            },
            "carry_over_tags": true
        }
    ],
    "assign_to": {
        "id": "2423488000000483001"
    },
    "related_modules": [
        {
            "api_name": "Calls",
            "id": "2423488000000017015"
        },
        {
            "api_name": "Tasks",
            "id": "2423488000000000143"
        }
    ],
    "ids": [
        "2423488000000625004",
        "2423488000000625032"
    ]
}

Possible Errors

MANDATORY_NOT_FOUNDHTTP 400
- One of the mandatory fields, 'ids', is missing
- One of the mandatory fields, 'convert_to', is missing
- One of the mandatory fields, 'carry_over_tags', is missing
- One of the mandatory fields, 'module' is missing in the input body
Resolution:
Specify all the mandatory fields in the input body. Refer to the input JSON keys above.
INVALID_DATAHTTP 400
- One or more of the given IDs seems to be invalid.
- IDs in the input body other than long or string data type
- The 'convert_to' data type seems to be invalid
- The given 'module' data type seems to be invalid
- The provided parent or child module name is invalid
- Multiple modules have been used for conversion in the request body
- The parent module records have the ID of the deleted record
Resolutions:
- Specify the valid record IDs.
- The expected data types for the ID are long or string.
- The 'convert_to' must be a JSON array. Please specify the valid data type.
- The 'module' must be a JSON object. Please specify the valid data type.
- Specify the valid parent or child module name.
- One module for conversion per action is allowed.
- Specify the non-deleted record ID in the parent module
NO_PERMISSIONHTTP 403
- Permission is denied for the parent module or child module
- The parent or child module is disabled in Organize Modules
Resolutions:
- Enable permission for the parent or child module.
- Enable permission for the parent or child module in the Organize Modules section.
AMBIGUITY_DURING_PROCESSINGHTTP 400
The ID given in the request body does not belong to the respective module which you are tyring to convert
Resolutions: The 'convert_to' field is missing in your input body. Please specify the required field.
LIMIT_EXCEEDEDHTTP 400
Limit has been exceed
Resolutions: You can convert only upto 50 records in a single API call. Limit the number of records to 50 and try again.
EXPECTED_FIELD_MISSINGHTTP 400
The 'convert_to' JSON array is missing or empty
Resolutions: One of the mandatory fields or the 'convert_to' key should not be empty or missed.
INVALID_REQUEST_METHODHTTP 400
The http request method type is not a valid one
Resolution: You have specified an invalid HTTP method to access the API URL.
Specify a valid request method. Refer to the endpoints section above.
INVALID_MODULEHTTP 400
The module name given seems to be invalid
Resolution: You have specified an invalid module name.
Specify a valid module name.
OAUTH_SCOPE_MISMATCHHTTP 401
Unauthorized
Resolution: Client does not have ZohoCRM.mass_convert.Quotes.CREATE (or) ZohoCRM.mass_convert.SalesOrders.CREATE scope.
Create a new token with the required scopes. Refer to scope section above.
AUTHENTICATION_FAILUREHTTP 401
Authentication failed
Resolution: Pass the access token in the request header of the API call.
INVALID_URL_PATTERNHTTP 404
Please check if the URL trying to access is a correct one
Resolution: The request URL specified is incorrect. Specify a valid request URL. Refer to the request URL section above.
INTERNAL_ERRORHTTP 500
Internal Server Error
Resolution: Unexpected and unhandled exception in the server. Contact support team.

Notes

To perform inventory record conversions, it is necessary to enable inventory module permission in both the Organize modules and Security Control. If these permissions are not enabled, the system will give a NO_PERMISSION error. Please note that only users with admin access has access to these settings.
- To enable the Organize Modules permission, go to Setup > Customization > Modules and Fields > Organize Modules tab. Choose the module you want to enable and grant permission.
- To enable Security Control permissions, go to to Setup > Security Control > Profiles. Select the desired profiles (only custom profiles, for the system-defined profiles, it is already enabled) that require access to the modules, choose the modules (Quotes and Sales Orders) you want to enable from Convert and Mass Convert options in Import/Export Permissions section, and grant permission.

Sample Response

Copied{
    "code": "SCHEDULED",
    "details": {
        "job_id": "2423488000000626117"
    },
    "message": "Mass Convert scheduled successfully",
    "status": "success"
}