For some special procedures CAS needs to know how your products are produced. A formula describes the main processed product, the raw materials that are consumed to produce it, and the secondary products — with or without economical value (waste) — that come out of the same production process. Formulas can be ingested as master data, or transactionally for each individual product or batch.

Create or update a formula

Use the Create or update formula endpoint to ingest a formula:

POST https://api-<env>.customs4trade.com/v1/formulas

The request body follows the Formula model. Refer to the API specification or the Formula XSD for the full schema. Both JSON and XML are accepted.

Like other ingestion endpoints, this operates asynchronously. The response is 202 Accepted with a reference ID:

{
    "referenceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Scope: create:messages

The same endpoint creates and updates: each message creates a formula version. If no formula exists yet for the item, CAS creates the formula together with its first version. If a formula already exists, CAS adds a new version to it, so you do not need a separate call to update one.

The activeFromDate determines from when the new version applies, and documentReference lets you record the document in your own system that triggered it. Only provide the activeUntilDate if you want to explicitly end the last version of the formula — leave it empty if you just want to create a new version.

Formula model

Formula

The formula header describes the main processed product.

FormulaLine

Each formula line describes one raw material or semi-finished product that is consumed to produce the quantity in the formula header.

SecondaryProduct

Secondary products and waste

Next to the main product described by the formula header, the same process can yield secondary products, some of which have economical value while others are waste. Provide these in the secondaryProducts array, using isWaste to distinguish between them:

The array is optional: omit it when the production process yields only the main processed product.

In the example below, 100 KGM of broken rice is processed into 65.79 KGM of rice starch. The same process yields rice protein as a secondary product with economical value, and fibres and rice polishings as waste:

{
    "version": "1.0",
    "itemId": "RiceStarch",
    "documentReference": "RiceStarch from BrokenRice",
    "activeFromDate": "2026-07-01T00:00:00Z",
    "quantity": 65.79,
    "uom": "KGM",
    "processingType": "1",
    "formulaLines": [
        {
            "itemId": "BrokenRice",
            "quantity": 100,
            "uom": "KGM"
        }
    ],
    "secondaryProducts": [
        {
            "itemId": "Fibres",
            "quantity": 14,
            "uom": "KGM",
            "isWaste": true
        },
        {
            "itemId": "RicePolishings",
            "quantity": 1.21,
            "uom": "KGM",
            "isWaste": true
        },
        {
            "itemId": "RiceProtein",
            "quantity": 7,
            "uom": "KGM",
            "isWaste": false
        }
    ]
}

The same formula in XML:

<formula>
    <version>1.0</version>
    <itemId>RiceStarch</itemId>
    <documentReference>RiceStarch from BrokenRice</documentReference>
    <activeFromDate>2026-07-01T00:00:00Z</activeFromDate>
    <quantity>65.79</quantity>
    <uom>KGM</uom>
    <processingType>1</processingType>
    <formulaLines>
        <formulaLine>
            <itemId>BrokenRice</itemId>
            <quantity>100</quantity>
            <uom>KGM</uom>
        </formulaLine>
    </formulaLines>
    <secondaryProducts>
        <secondaryProduct>
            <itemId>Fibres</itemId>
            <quantity>14</quantity>
            <uom>KGM</uom>
            <isWaste>true</isWaste>
        </secondaryProduct>
        <secondaryProduct>
            <itemId>RicePolishings</itemId>
            <quantity>1.21</quantity>
            <uom>KGM</uom>
            <isWaste>true</isWaste>
        </secondaryProduct>
        <secondaryProduct>
            <itemId>RiceProtein</itemId>
            <quantity>7</quantity>
            <uom>KGM</uom>
            <isWaste>false</isWaste>
        </secondaryProduct>
    </secondaryProducts>
</formula>

Processing types

Error handling

For HTTP status codes and error response formats, see Error handling.