4. Endpoints: Packaging Projects

These endpoints manage the lifecycle of your packaging data (SKUs). Attributes required for the consumerSalesUnitInput object are defined in Section 6.

🔄 Upsert Behavior via foreignKey:
All endpoints under this section function as Upserts. The foreignKey acts as your unique identifier.

• If a project with the given foreignKey does not exist, the API will create a new project.
• If a project with the given foreignKey already exists, the API will update and overwrite the existing project data with the newly provided payload.

🔗 Important Note on IDs & Deep Linking:

The inner id field provided inside the consumerSalesUnitInput object is of no use for upsert identification, the root foreignKey is the actual determinator. Upon successful creation or update, Recyda generates a unique internal identifier for the project, which is returned in the API response as key (not to be confused with your foreignKey). You can use this key to construct direct deep links to the specific project in the Recyda Web App: https://app.recyda.com/projects/{key}.

⏱️ Synchronous Processing:

Please note that all packaging evaluate operations are fully synchronous. The API processes your data in real-time.

• /import endpoints: Return immediately after the upsert operation is completed with the internal metadata (ID) and foreignKey of the created/updated objects.
• /evaluate endpoints: Perform the upsert operation and synchronously run calculations. The fully calculated evaluation results (recyclability scores, EPR fees) are returned directly within the HTTP response body of your request.

Import Single Project

Endpoint: POST <https://api-prod.recyda.com/v2/import>

Create or update a single packaging project without triggering an evaluation.

Request Body Example:

{
  "foreignKey": "SKU-1001",
  "consumerSalesUnitInput": {
    "id": "SKU-1001",
    "name": "Coffee Packaging 1kg",
    "description": "Standard coffee pouch for retail",
    "metaData": {
      "brand": "CoffeeCo",
      "market": "DE"
    },
    "packagingUnits": [
      {
        "quantity": 1,
        "packagingUnit": {
          "id": "PU-001",
          "name": "Primary Pouch",
          "description": "Flexible pouch",
          "packagingType": "PO",
          "mainPackagingBodyComponentId": "COMP-BODY-001",
          "attributes": {
             "function": ["PROTECTED", "FLEXIBLE"],
             "dimensions": {
                 "height": { "value": 250, "unitOfMeasurement": "MMT" },
                 "width": { "value": 150, "unitOfMeasurement": "MMT" },
                 "depth": { "value": 80, "unitOfMeasurement": "MMT" }
             },
             "volume": { "value": 1000, "unitOfMeasurement": "MLT" }
          },
          "components": [
            {
              "id": "COMP-BODY-001",
              "name": "Pouch Body",
              "componentType": "PACKAGING_BODY",
              "attributes": {
                  "rigidity": "FLEXIBLE",
                  "opacity": "OPAQUE",
                  "separability": ["NOT_SEPARABLE"]
              },
              "layers": [
                {
                  "id": "LAYER-001",
                  "name": "Outer PE",
                  "packagingMaterialTypeCode": "POLYMER_PE",
                  "attributes": {
                    "weight": { "value": 12.5, "unitOfMeasurement": "GRM" },
                    "layerThickness": { "value": 40, "unitOfMeasurement": "4H" },
                    "density": { "value": 0.92, "unitOfMeasurement": "23" }
                  }
                },
                 {
                  "id": "LAYER-002",
                  "name": "Barrier EVOH",
                  "packagingMaterialTypeCode": "POLYMER_EVOH",
                  "attributes": {
                    "weight": { "value": 2.1, "unitOfMeasurement": "GRM" },
                     "layerThickness": { "value": 5, "unitOfMeasurement": "4H" }
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Response Body Example:
The API returns the internal key generated for the created or updated project alongside a summary of the mapped project definition fields.

{
    "project": {
        "foreignKey": "SKU-1001",
        "key": "7e61fc19-c90c-43f2-9417-d239ba2b2b63",
        "projectDefinition": {
            "fields": [
                {
                    "key": "name",
                    "valueRaw": "\"Coffee Packaging 1kg\""
                },
                {
                    "key": "description",
                    "valueRaw": "\"Standard coffee pouch for retail\""
                },
                {
                    "key": "brand",
                    "valueRaw": "\"CoffeeCo\""
                },
                {
                    "key": "market",
                    "valueRaw": "\"DE\""
                },
                {
                    "key": "product_group",
                    "valueRaw": "\"Coffee\""
                },
                {
                    "key": "article_number",
                    "valueRaw": null
                }
            ]
        }
    }
}

Import Multiple Projects (Group)

Endpoint: POST <https://api-prod.recyda.com/v2/import-many>

Import multiple projects at once, optionally linking them under a group key.

Request Body Parameters:

Request Body Example:

Evaluate Single Project

Endpoint: POST <https://api-prod.recyda.com/v2/evaluate>

Upsert and immediately assess a single project. Because this is a synchronous endpoint, the calculated evaluation results are returned directly in the response payload.

Request Body Parameters:

Request Body Example:

Evaluate Multiple Projects