OpenAPI - Transfer orders (part 2/4) - Update order line's properties and form properties

Knowledge base
,
1

This article is part of a series - click to read part 1, part 3 and part 4.

1. Update an order line’s properties.

API overview
Endpoint POST /v1/orders-lines/properties
Description Update an order line’s properties.
Usage Make requests to this endpoint to update the order line’s properties.
Only matched properties are updated; the rest is ignored. The rule is described in field PropertyInfo fields table.
The order line’s properties come from the product’s properties or manually created by users on Onix Work. This endpoint does not support creating new properties.
Note: Attempting to call this request for an order line when the workflow status on either itself or its order is marked as “Closed” will result in an error.
Return Returns a boolean value indicating the success of the updating process.

Request parameters and body

The corresponding request body type can be found at the Swagger page (see OpenAPI overview), model OrderLinePropertiesInfo for the main request body and OrderLineItemSerialInfo for the properties model.

There are two ID pairs:

  • orderId and orderImportId.
  • orderLineId and orderLineImportId.

Despite those fields being nullable, the system requires the request body must contains at least one field for each pair.

Field precedence for ID pairs:

  • orderId has higher priority than orderImportId.
  • orderLineId has higher priority than orderLineImportId.

When a higher priority field is present, the lower priority field will be ignored.

When a field value is null, it follows the rules explained in section API requests and responses, if no specific rules are mentioned.

Field Type Required Description
orderId int No* The Onix Work system’s order ID.
Either orderId or orderImportId must be provided.
See field precendence above.
orderImportId string No* Constraint: length ≤ 50.
Your system’s order ID.
Either orderId or orderImportId must be provided.
See field precendence above.
orderLineId int No* The Onix Work system’s order line ID.
Either orderLineId or orderLineImportId must be provided.
See field precendence above.
orderLineImportId string No* Constraint: length ≤ 50.
Your system’s order line ID.
Either orderLineId or orderLineImportId must be provided.
See field precendence above.
properties PropertyInfo[] Yes Constraint: length > 0.
The list of the order line’s properties.
Only matched properties are updated; the rest are ignored.
See the table below for more information and the properties update rule.

Response

Status code Response body Description
200 A boolean. Indicate if the update process was successful or not.
400 The system’s standard error response object. See an examples of error responses in section API requests and responses.

Examples

Let’s use the orderId and orderLineId to update properties for the order line that’s just created in part 1:

  • orderId: 546804.
  • orderLineId: 3998608.

You can also use orderImportId and orderLineImportId instead.
First, let’s examine the properties of the product that the order line has been using for better visualization:

image
image975×325 42.3 KB

Currently, there are two properties “Color” and “Actual diameter (mm)”, and the “Color” property has “White” as the default value. That means our order line also has two properties with the same values.

image
image975×327 31 KB

To update the order line’s properties, make a request with the request body below, with languageCode is English (see OpenAPI terminology):

{
  "orderId": 546804,
  "orderLineId": 3998608,
  "properties": [
    {
      "languageCode": 1,
      "description": "Color",
      "value": "Red"
    },
    {
      "languageCode": 1,
      "description": "Actual diameter (mm)",
      "value": "0.5"
    }
  ]
}

The system responsed with status code of 200, the response body indicates where the request was successful or not:

true

The properties have been updated successfully. Let’s check the results in Onix Work by navigating to the order we have just been created in part 1 and click on the tab “Order lines” then “Properties” of the order line.

image
image975×278 47.3 KB

The properties have updated according to the request. Let’s go to the next step: update the order line’s form properties.

2. Update an order line’s form properties

API overview

A B
Endpoint POST /v1/orders-lines/form-properties
Description Update an order line’s form properties.
Usage Make requests to this endpoint to update the order line’s form properties.
Only matched properties are updated; the rest is ignored. The rule is described in field FormPropertyKeyValueInfo fields table.
The order line’s form properties come from the product’s form properties or manually created by users on Onix Work. Make a request to this endpoint: GET /v1/company/form-properties to get a full list of available and editable form properties.
Note: Attempting to call this request for an order line when the workflow status on either itself or its order is marked as “Closed” will result in an error.
Return Returns a boolean value indicating the success of the updating process.

Request parameters and body

The corresponding request body type can be found at the Swagger page (see OpenAPI overview), model OrderLineFormPropertiesInfo for the main request body and FormPropertyKeyValueInfo for the properties model.

There are two ID pairs:

  • orderId and orderImportId.
  • orderLineId and orderLineImportId.

Despite those fields being nullable, the system requires the request body must contains at least one field for each pair.

Field precedence for ID pairs:

  • orderId has higher priority than orderImportId.
  • orderLineId has higher priority than orderLineImportId.

When a higher priority field is present, the lower priority field will be ignored.

When a field value is null, it follows the rules explained in section API requests and responses, if no specific rules are mentioned.

Field Type Required Description
orderId int No* The Onix Work system’s order ID.
Either orderId or orderImportId must be provided.
See field precendence above.
orderImportId string No* Constraint : length ≤ 50.
Your system’s order ID.
Either orderId or orderImportId must be provided.
See field precendence above.
orderLineId int No* The Onix Work system’s order line ID.
Either orderLineId or orderLineImportId must be provided.
See field precendence above.
orderLineImportId string No* Constraint : length ≤ 50.
Your system’s order line ID.
Either orderLineId or orderLineImportId must be provided.
See field precendence above.
properties FormPropertyKeyValueInfo[] Yes Constraint: length > 0.
The list of the order line’s form properties.
See the table below for more information.

Model FormPropertyKeyValueInfo fields table:

Field Type Required Description
key string Yes Constraint : length ≤ 50.
The form property’s key – corresponding with the key field in endpoint:
GET /v1/company/form-properties
value string No Constraint : length ≤ 100.
The form property’s value.

Response

Status code Response body Description
200 A boolean. Indicate if the update process was successful or not.
400 The system’s standard error response object. See an examples of error responses in section API requests and responses.

Examples

Let’s use the orderId and orderLineId to update properties for the order line that’s just created in part 1:

  • orderId: 546804.
  • orderLineId: 3998608.

You can also use orderImportId and orderLineImportId instead.
First, let’s examine the form of the product that the order line has been using for better visualization:

image
image975×257 42.8 KB

There are one form and four properties, and only “Proofload” and “Date of test” can be updated. Typically, developers should check all available form properties using the endpoint:

GET /v1/company/form-properties

The results of this endpoint allow developers to find the suitable keys which can be used to update the form properties. The key for those two properties above is:

  • ApiKey_Proofload: “Proofload” property.
  • ApiKey_DateOfTest: “Date of test” property.

Use them and make a request with the request body below:

{
  "orderId": 546804,
  "orderLineId": 3998608,
  "properties": [
    {
      "key": "ApiKey_Proofload",
      "value": "Test value"
    },
    {
      "key": "ApiKey_DateOfTest",
      "value": "2024.31.01"
    }
  ]
}

The system responsed with status code of 200, the response body indicates where the request was successful or not:

true

The properties have been updated successfully. Let’s check the results in Onix Work by navigating to the order we have just been created and click on the tab “Order lines” then “Forms” of the order line.

image
image975×225 43.9 KB

Notice that the value of “Proofload” and “Date of test” updated accordingly to the request.

That completes the entire process of creating or updating an order. If you are currently using the Web API (deprecated), consider migrating to OpenAPI. Please refer to part 3 for more information.

Related articles

  • OpenAPI - Get started
  • Part 1: create and update an order, an order line and numbering an order line.
  • Part 2: update an order line’s properties and form properties.
  • Part 3: how to migrate from Web API to OpenAPI.
  • Part 4: create and update grouped order lines.

If you encounter any issues or have questions, kindly describe your concern and:

  • Send an email to support@onix.com; OR
  • Create a topic in Q&A to receive assistance from all Community members.
1 Like