# Article

An article represents a physical article in the warehouse. Articles can be referenced in different objects, e.g. in an order. With this API you can create, get and update articles.

# The article resource

# JSON object

{
  "id": 71035893,
  "customerId": 1000050,
  "status": "active",
  "number": "A1000-BLUE",
  "barcodes": [
    "03125454541515"
  ],
  "description": "Glasses case (blue).",
  "unit": "ST",
  "isStockManaged": true,
  "isBulky": false,
  "isAgeRequired": false,
  "unNumber": null,
  "batchNumberRequirement": "none",
  "serialNumberRequirement": "none",
  "bestBeforeDateRequirement": "none",
  "length": 100,
  "width": 50,
  "height": 50,
  "weight": 250,
  "price": 9.99,
  "packageUnits": [
    {
      "quantity": 10,
      "length": 100,
      "width": 100,
      "height": 250,
      "weight": 2500
    }
  ],
  "customs": {
    "tariff": "42023900",
    "content": "Glasses case",
    "countryOfOrigin": "DE"
  },
  "note": null,
  "createdAt": "2024-05-13T12:11:09Z",
  "updatedAt": "2024-05-13T12:11:09Z"
}

# Properties

id int32 - read-only
The id of the article to identify the article in the API.
customerId int32 - required
The id of the customer the article belongs to.
status string - read-only
The status of the article. Valid values: active, inactive
number string (length <= 50) - required
The unique article number to identify from the shop or third party.
barcodes string[] (each length <= 50)
Barcodes of the article which can be scanned. A barcode must contain letters and digits only.

Currently only one barcode is supported at the moment.

description string (length <= 255)
A description to the article.
unit string (length <= 15) - required
Defines the unit of the article.
isStockManaged bool (default: false)
Defines whether the article is managed by the stock or not.
isBulky bool (default: false)
Defines whether the article is a bulky good or not. This is important information for shipping.
isAgeRequired bool (default: false)
Determines whether proof of age is required for the article when shipping. This is important information for shipping.
unNumber string (must be a four-digit code)
A four-digit number that identifies hazardous materials, and articles (such as explosives, flammable liquids, oxidizers, toxic liquids, etc.).
batchNumberRequirement string
Determines in which processes the batch number must be taken into account. Valid values: none, inbound and outbound
serialNumberRequirement string
Determines in which processes the serial number must be taken into account. Valid values: none, inbound and outbound
bestBeforeDateRequirement string
Determines in which processes the best before date must be taken into account. Valid values: none, inbound and outbound
length int32
Sets the length of the article in millimeter.
width int32
Sets the width of the article in millimeter.
height int32
Sets the height of the article in millimeter.

Please ensure to set all dimensions (length, width, height) if you wish to specify any of them.

weight int32
Sets the weight of the article in grams.
price decimal
Sets the price of the article in EUR.
packageUnits object[]
The package unit object.
- quantity int32 required
  Sets the quantity of the article in the package unit.
- length int32 required
  Sets the length of the package unit in millimeter.
- width int32 required
  Sets the width of the package unit in millimeter.
- height int32 required
  Sets the height of the package unit in millimeter.
- weight int32 required
  Sets the weight of the package unit in grams.

Currently only one package unit is allowed at the moment.

customs object
Sets the customs properties for the article. If defined all properties must be set.
- tariff string (6, 8 or 10 digit number) - required
  Sets the tariff of the article.
- content string (length <= 50) - required
  Sets the content description of the article for the customs.
- countryOfOrigin string (ISO3166-2) - required
  Sets the country of origin of the article for the customs. E.g.: CH, DE, FR, ...
note string (length <= 250)
An additional field to save notes and other information.
createdAt date (ISO 8601) - read-only
The date the article was created in logistic.cloud.
updatedAt date (ISO 8601) - read-only
The date some data has changed.

# POST - Create an article

Requires scope Article.Write

Use this operation to create an article. Make sure to specify all required parameters.

curl -X POST \
  'https://{domain}.logistic.cloud/api/{version}/articles' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
        "customerId": 1000050,
        "number": "A1000-BLUE",
        "barcodes": [
          "03125454541515"
        ],
        "description": "Glasses case (blue).",
        "unit": "ST",
        "isStockManaged": true,
        "isBulky": false,
        "isAgeRequired": false,
        "unNumber": null,
        "serialNumberRequirement": "none",
        "batchNumberRequirement": "none",
        "bestBeforeDateRequirement": "none",
        "length": 100,
        "width": 50,
        "height": 50,
        "weight": 250,
        "price": 9.99,
        "packageUnits": [
          {
            "quantity": 10,
            "length": 100,
            "width": 100,
            "height": 250,
            "weight": 2500
          }
        ],
        "customs": {
          "tariff": "42023900",
          "content": "Glasses case",
          "countryOfOrigin": "DE"
        },
        "note": null
      }'

Responses

201 - Created The article was created successfully. Returns the created article resource.
400 - Bad Request
Returns a problem details JSON object. More info can be found here.

# Examples

Create an article with the minimum required information. Please note that some processes may not work properly if article information is missing. See the Properties section for more details.

curl -X POST \
  'https://{domain}.logistic.cloud/api/{version}/articles' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
        "customerId": 1000050,
        "number": "A1000-BLUE",
        "isStockManaged": true,
        "description": "Glasses case (blue).",
        "unit": "ST"
      }'

International shipping requires more information about the article such as dimensions, value, country of origin, etc. At the moment the international shipping is more restrictive than the domestic shipping and can reject the shipment creation if some information is missing. This may change in the future.

curl -X POST \
  'https://{domain}.logistic.cloud/api/{version}/articles' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
        "customerId": 1000050,
        "number": "A1000-BLUE",
        "description": "Glasses case (blue).",
        "unit": "ST",
        "isStockManaged": true,
        "isBulky": false,
        "isAgeRequired": false,
        "unNumber": null,
        "length": 100,
        "width": 50,
        "height": 50,
        "weight": 250,
        "price": 9.99,
        "customs": {
          "tariff": "42023900",
          "content": "Glasses case",
          "countryOfOrigin": "DE"
        }
      }'

Package units are a number pre-packaged items that can be shipped without repackaging. We typically use them in our vendor or FBA processes.

curl -X POST \
  'https://{domain}.logistic.cloud/api/{version}/articles' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
        "customerId": 1000050,
        "number": "A1000-BLUE",
        "description": "Glasses case (blue).",
        "unit": "ST",
        "isStockManaged": true,
        "isBulky": false,
        "isAgeRequired": false,
        "unNumber": null,
        "packageUnits": [
          {
            "quantity": 10,
            "length": 100,
            "width": 100,
            "height": 250,
            "weight": 2500
          }
        ]
      }'

# GET - Retrieve a list of articles

Requires scope Article.Read or Article.Write

Use this operation to retrieve a list of articles that meet the specified criteria. This endpoint implements pagination. Click here to learn more.

curl -X GET \
  'https://{domain}.logistic.cloud/api/{version}/articles' \
  -H 'X-API-KEY: YOUR_API_KEY'

Parameters

ids string
Retrieve only articles specified by a comma-separated list of article ids.
status string
Filter articles by their status. Allowed values are: active, inactive
number string
Filter articles by their exact number.
barcode string
Filter articles by their exact barcode number.
createdAtMin date (ISO 8601)
Show articles last created after a specific date.
createdAtMax date (ISO 8601)
Show articles last created before a specific date.
updatedAtMin date (ISO 8601)
Show articles last updated after a specific date.
updatedAtMax date (ISO 8601)
Show articles last updated before a specific date.
page int32 (default: 0)
The page number that contains the results. If not specified the first page will be returned.
pageSize int32 (default: 50)
The maximum number of results returned per page. Value must be between 1 and 250.

Responses

200 - OK
Returns a list of article resources.

# Examples

List all articles with the status active.

curl -X GET \
  'https://{domain}.logistic.cloud/api/{version}/articles?status=active' \
  -H 'X-API-KEY: YOUR_API_KEY'

List articles that have the ids 71035893, 71035894 and 71035895.

curl -X GET \
  'https://{domain}.logistic.cloud/api/{version}/articles?ids=71035893,71035894,71035895' \
  -H 'X-API-KEY: YOUR_API_KEY'

All dates are handled in UTC. To get the articles created after 01/01/2024 CEST, we need to pass 2024-01-01T00:00:00+02:00 which includes the timezone. The value must be url encoded. Please be aware that all dates in the results will be returned in UTC.

curl -X GET \
  'https://{domain}.logistic.cloud/api/{version}/articles?createdAtMin=2024-01-01T00:00:00%2B02:00' \
  -H 'X-API-KEY: YOUR_API_KEY'

You can combine all filters to get a more specific result. For example, you can list only articles with the status active and the ids 71035893, 71035894 and 71035895.

curl -X GET \
  'https://{domain}.logistic.cloud/api/{version}/articles?status=active&ids=71035893,71035894,71035895' \
  -H 'X-API-KEY: YOUR_API_KEY'

# GET - Retrieve a specific article

Requires scope Article.Read or Article.Write

Use this operation to retrieve an article by specifying the id.

curl -X GET \
  'https://{domain}.logistic.cloud/api/{version}/articles/{id}' \
  -H 'X-API-KEY: YOUR_API_KEY'

Parameters

id int32 - required
The article id.

Responses

200 - OK
Returns the specific article resource.
404 - Not Found
The requested article id hasn't been found.

# PUT - Update an article

Requires scope Article.Write

Use this operation to replace properties of an article.

curl -X PUT \
  'https://{domain}.logistic.cloud/api/{version}/articles/{id}' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
        "customerId": 1000050,
        "number": "A1000-BLUE",
        "barcodes": [
          "03125454541516"
        ],
        "description": "Glasses case (blue).",
        "unit": "ST",
        "isStockManaged": true,
        "isBulky": false,
        "isAgeRequired": false,
        "unNumber": null,
        "serialNumberRequirement": "none",
        "batchNumberRequirement": "none",
        "bestBeforeDateRequirement": "none",
        "length": 100,
        "width": 50,
        "height": 50,
        "weight": 250,
        "price": 9.99,
        "packageUnits": [
          {
            "quantity": 10,
            "length": 100,
            "width": 100,
            "height": 250,
            "weight": 2500
          }
        ],
        "customs": {
          "tariff": "42023900",
          "content": "Glasses case",
          "countryOfOrigin": "DE"
        },
        "note": null
      }'

Parameters

id int32 - required
The article id.

Responses

200 - OK
The article was updated successfully. Returns the updated article.
400 - Bad Request
Returns a problem details JSON object. More info can be found here.
404 - Not Found
The given article id to update hasn't been found.

# Examples

Make sure to specify any other properties that should not be removed, as the resource will be replaced by your data. See how we recommend updating a resource here.

curl -X PUT \
  'https://{domain}.logistic.cloud/api/{version}/articles/{id}' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
 -d '{
        "customerId": 1000050,
        "number": "A1000-BLUE",
        "isStockManaged": true,
        "description": "Your new article description.",
        "unit": "ST"
      }'

To remove the package unit information from the article, you must pass an empty array as the packageUnits property.

Make sure to specify any other properties that should not be removed, as the resource will be replaced by your data. See how we recommend updating a resource here.

curl -X PUT \
  'https://{domain}.logistic.cloud/api/{version}/articles/{id}' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
        "customerId": 1000050,
        "number": "A1000-BLUE",
        "description": "Glasses case (blue).",
        "unit": "ST",
        "isStockManaged": true,
        "isBulky": false,
        "isAgeRequired": false,
        "unNumber": null,
        "packageUnits": []
      }'