5. Endpoints: Shipment Volumes
These endpoints allow you to upload "Put-on-Market" (POM) data.
⚠️ Important: Overwrite vs. Append Logic
- With
shipmentForeignKey: If you provide this key, the operation will OVERWRITE any existing shipment data associated with that specific key. This allows for idempotent updates (e.g., correcting a previous upload). - Without
shipmentForeignKey: The system will APPEND the new volumes to existing data.
Import Shipment Volumes (Single Project)
Endpoint: POST <https://api-prod.recyda.com/v1/import-shipment-volumes>
Request Body Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
projectForeignKey |
String | ✅ | Must match the foreignKey of an imported Packaging Project. |
shipmentForeignKey |
String | ✅ | Unique ID for this shipment batch (enables overwrite behavior). |
shipmentVolumePeriodInputs |
Array | ✅ | List of periods and volumes. |
Structure of shipmentVolumePeriodInputs Object:
| Parameter | Type | Description |
|---|---|---|
startDate |
String | ISO 8601 Date (e.g., 2023-01-01T00:00:00+00:00). |
endDate |
String | ISO 8601 Date (e.g., 2023-12-31T23:59:59+00:00). |
shipmentVolumeItems |
Array | List of volume items (see below). |
Structure of shipmentVolumeItems Object:
| Parameter | Type | Description |
|---|---|---|
regions |
Array | List of ISO 3166-1 alpha-3 country codes (e.g., ["DEU"]). |
quantity |
Number | The number of units sold. |
Request Body Example:
{ "projectForeignKey": "SKU-1001", "shipmentForeignKey": "SHIP-2025-Jan-DE", "shipmentVolumePeriodInputs": [ { "startDate": "2025-01-01T00:00:00+00:00", "endDate": "2025-01-31T23:59:59+00:00", "shipmentVolumeItems": [ { "regions": ["DEU"], "quantity": 25000 }, { "regions": ["NLD"], "quantity": 12000 } ] } ]}
Response Body Example:
{ "shipmentVolumePeriods": [ { "dateCreated": "2026-04-07T16:46:39.424Z", "endDate": "2025-01-31T23:59:59.000Z", "id": "sales_volume_periods/b3d011e5-4d77-4f61-b50a-512f500d68e0", "key": "b3d011e5-4d77-4f61-b50a-512f500d68e0", "shipmentVolumeItems": [ { "id": "16c14723-c3a2-48c2-8432-c69a54d5b287", "quantity": 25000, "regions": [ "DEU" ] }, { "id": "c4217699-712a-49d2-9e7c-d92e03abb0fe", "quantity": 1200, "regions": [ "NLD" ] } ], "startDate": "2025-01-01T00:00:00.000Z" } ]}
Import Shipment Volumes (Multiple Projects)
Endpoint: POST <https://api-prod.recyda.com/v1/import-many-projects-shipment-volumes>
Bulk import shipment volumes for multiple projects simultaneously.
Request Body: An array of shipment volume objects (same structure as 5.1).
[ { "projectForeignKey": "SKU-1001", "shipmentForeignKey": "SHIP-2025-Jan-SKU1001", "shipmentVolumePeriodInputs": [...] }, { "projectForeignKey": "SKU-1002", "shipmentForeignKey": "SHIP-2025-Jan-SKU1002", "shipmentVolumePeriodInputs": [...] }]
ℹ️ This endpoint is limited to 2000 projects per request.