Update Particular Fields of a Record

When you need to update particular fields of an existing record by using the contract-based REST API, you access the needed URL with the PATCH HTTP method and pass the fields that should be updated 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 particular fields of an existing record in MYOB Acumatica, you use the PATCH HTTP method and the following URL.

PATCH 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 update a record.

For example, suppose that you want to update particular fields of 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 particular fields of a record in MYOB Acumatica:

• $filter: To specify the filtering conditions that identify the record to be updated. For details, 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, see $select Parameter.
• $custom: To specify the fields that are not defined in the contract to be returned. For details, 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 the 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

Suppose that you need to update the order quantity and discount amount in a detail line of the 000029 sales order. You can use the following request.

PATCH /entity/Default/24.200.001/SalesOrder?
  $expand=Details&
  $select=Details/DiscountAmount,Details/OrderQty,OrderNbr,OrderType HTTP/1.1
Host: [<MYOB Acumatica instance URL>]
Accept: application/json
Content-Type: application/json

{
    "OrderType": {"value": "SO"},
    "OrderNbr": { "value": "000029" },
    "Details": [
        {
             "id": "a1d07920-a402-e911-b818-00155d408001",
              "OrderQty": { "value": 2 },
              "DiscountAmount": { "value": 5 }  
        }
    ]
}

Usage Notes: PATCH and PUT Methods

The PATCH method updates exactly the fields specified in the request body, regardless of the values for these fields that are stored in the system. However, the PATCH method does not override the graph logic. For example, if because of the graph logic, the value cannot be changed as the request body specifies, this value will not be changed.

You may consider using the PATCH method during the synchronization of records from an external system when you know exactly which fields have been changed in the external system. You may also use this method in situations when particular fields of a record cannot be updated with a PUT request. For details about updating records with the PUT method, see Update a Record.

Usage Notes: Values for a Drop-Down List

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 (that is, not external or displayed) values can be specified.