Update a Record

When you need to update an existing record by using the contract-based REST API, you access the needed URL with the PUT HTTP method and pass the record representation in JSON format in the request body. See the following sections for details on the request and the response.

HTTP Method and URL

When you update a record in MYOB Acumatica, you use the PUT HTTP method and the following URL.

PUT http://<Base endpoint URL>/<Top-level entity>

The URL has the following components:

• <Base endpoint URL> is the URL of the contract-based endpoint through which you are going to work with MYOB Acumatica. This URL has the following format: http://<MYOB Acumatica instance URL>/entity/<Endpoint name>/<Endpoint version>/.
• <Top-level entity> is the name of the entity for which you are going to create or update a record.

For example, suppose that you want to update a stock item record in a local MYOB Acumatica instance with the name AcumaticaDB by using a system endpoint with the name Default and Version 24.200.001. You would use the following URL to update a record: http://localhost/AcumaticaDB/entity/Default/24.200.001/StockItem.

Parameters

You can use the following parameters when you are updating a record in MYOB Acumatica:

• $filter: To specify the filtering conditions that identify the record to be updated. For details about this parameter, see $filter Parameter.
• $expand: To specify the linked and detail entities to be expanded. For more information, see $expand Parameter.
  Attention:

  You must list in the $expand parameter every detail and related entity that you are going to have in the response body.
• $select: To specify the fields of the entity to be returned. For more information about the parameter, see $select Parameter.
• $custom: To specify the fields that are not defined in the contract to be returned. For details about the parameter, see $custom Parameter.

HTTP Headers

You can specify the following headers in the request.

HTTP Body

You pass a record in JSON format in the request body. You can find details on how to represent a record in JSON format in Representation of a Record in JSON Format.

To make it possible for the record to be found by MYOB Acumatica, you can specify any of the following:

• The values of the key fields in the record representation in JSON format.
• The value of the ID property in the record representation in JSON format.
• The filtering conditions that identify the record in the $filter parameter of the method. For details on the parameter, see the Parameters section in this topic.

If you want to delete a detail line during update, you should specify true as the value of the delete property of the corresponding detail entity: "delete" : true. To identify the detail line to be deleted, you can specify one of the following:

• The value of the ID property of the detail line
• The values of the key fields of the detail line

Response Status Codes

The following table lists the HTTP status codes that the system returns for a request that updates a record.

"CustomerID": {
 "value": "ABARTENDE1",
 "error": "'Customer' cannot be found in the system."
}

Example

The following request shows an example of the update of an existing customer record that has the demo@gmail.com email address.

PUT ?$filter=MainContact/Email%20eq%20'demo@gmail.com'&
   $select=CustomerID,CustomerClass,MainContact/Email&$expand=MainContact HTTP/1.1
Host: [<MYOB Acumatica instance URL>]/entity/Default/24.200.001/Customer
Accept: application/json
Content-Type: application/json

{
  "CustomerClass" : {"value" : "ECCUSTOMER"}
}

Usage Notes

Note the following about update of a record:

• You can specify a value for a drop-down list (or a multiselect drop-down list) only if that value has been defined for the control. If the value you attempt to set is not present in the control, an error message is returned in the error field of the response. For a multiselect drop-down list, only internal (namely, not external or displayed) values can be specified.

• By using the contract-based REST API, you can remove records from MYOB Acumatica. For details about how to remove a record, see Remove a Record by Key Fields and Remove a Record by ID.

• If you need to create or update documents with a large number of detail lines by using the contract-based REST API, note that the following approaches may have performance implications:

  • You make a single request that contains all information you need to pass. In this case, the operation could time out.
  • You make many requests, each of which contains a single detail line you need to add or alter. In this case, the whole task takes a lot of time.

  A more balanced approach is a compromise between these two: You make multiple requests, each of which contains a part of the detail lines you need to add or alter. You select the number of detail lines in a single request to optimize the performance of the whole task. For example, if you need to send a sales order containing 10,000 detail lines to the server, you can make requests, each of which contains 500 detail lines.