API docs by Redocly

Sustained Product Footprint API (2.0.0)

Download OpenAPI specification:

URL: https://sustained.com License: Proprietary

Ingest product data and retrieve environmental impact reports.

The Sustained Product Footprint API accepts third-party product data and returns environmental impact reports.

It is offered at two resolutions:

Low-res High-res
Purpose Fast screening across a wide catalogue Detailed, decision-grade modelling
Ingredients Yes Yes
Packaging Rejected Yes
Distribution paths Rejected Yes
Product groups Rejected Yes
Ingredient loss Rejected Yes
Facility emissions & waste Rejected Yes
Report Impact points + categories Categories, contributor tree, transport, consumer label

A request that sends a high-res-only field to a low-res endpoint is rejected with 400 Bad Request — it is not silently ignored.

How ingestion works

Every scalar in a product document is a small envelope rather than a bare value:

{ "category": { "source": "Dairy alternatives", "target": "dairy-alternatives" } }
  • source — your value, in your own vocabulary, exactly as you hold it
  • target — the Sustained-resolved value
  • tag — an optional qualifier steering how the mapping is made

You normally send only source. Sustained's mapping layer resolves target during ingestion and returns the completed document when you read the product back. You do not need to adopt Sustained's vocabulary to integrate.

Ingestion is asynchronous

A successful POST returns 201 with a job envelope, not a finished report. Poll the corresponding GET until status is finished or failed.

Rate limits

Requests are throttled. On 429 Too Many Requests, retry with exponential back-off.

Support correlation

Every response carries an X-Sustained-Request-Sid header. Log it, and quote it when raising anything with Sustained support.

Low-res

Screening-resolution ingestion and reporting. Accepts ingredients, materials and production facilities; rejects packaging, distribution paths, product groups, ingredient loss, and facility emissions and waste.

Ingest a low-res product

Submits a new product for screening-resolution assessment.

Returns immediately with a job envelope. Poll GET /v1/ingest/lowres/{skuId} until status is finished or failed.

The SKU identifier is taken from skuId.source in the body. If that SKU already exists for this customer, use POST /v1/ingest/lowres/{skuId} instead.

Authorizations:
ApiKeyAuth
header Parameters
X-Integration-Customer-Alias
string
Example: 123456

Selects the target customer within your integration. Globally unique.

If the alias does not exist, the customer is provisioned automatically. If omitted, the integration's default customer is used.

X-Integration-Customer-Name
string
Example: ACME, Ltd.

Display name applied when a customer is provisioned for the first time. Ignored if the customer already exists. If omitted, the integration name plus customer ID is used.

X-Integration-Workspace-Alias
string

Selects the target workspace within the customer. Unique per customer.

If the alias does not exist, the workspace is provisioned automatically. If omitted, the default workspace is used.

Applies to ingestion endpoints only — reporting and deletion resolve the workspace from the SKU.

Request Body schema: application/json
required
object

Your SKU identifier. Unique per customer across all its workspaces.

object

Like TaggedString, but source is required — these identify the record and cannot be resolved from anything else.

object

Net content of one sellable unit, in unit.

object

g or ml.

object

Like TaggedString, but source is required — these identify the record and cannot be resolved from anything else.

object
object
object

An optional value in envelope form. Send source with your own value; Sustained resolves target.

object

An optional value in envelope form. Send source with your own value; Sustained resolves target.

object

An optional value in envelope form. Send source with your own value; Sustained resolves target.

object

An optional numeric value in envelope form.

object

An optional value in envelope form. Send source with your own value; Sustained resolves target.

object

An optional value in envelope form. Send source with your own value; Sustained resolves target.

object

An optional value in envelope form. Send source with your own value; Sustained resolves target.

object

An optional value in envelope form. Send source with your own value; Sustained resolves target.

object

An optional integer value in envelope form.

bomFileName
string
Array of objects (LowResIngredient)
Array of objects (TaggedMaterial)
Array of objects (LowResProductionFacility)
object

Where the product is filed in the workspace.

folderSid wins over space/subSpace when it resolves. If it does not, the import falls back to space/subSpace and then to the product type's default location — an unresolvable folder never fails the import.

Responses

Request samples

Content type
application/json
{
  • "skuId": {
    },
  • "name": {
    },
  • "amount": {
    },
  • "unit": {
    },
  • "category": {
    },
  • "type": {
    },
  • "stage": {
    },
  • "class": {
    },
  • "conservation": {
    },
  • "form": {
    },
  • "economicValue": {
    },
  • "currency": {
    },
  • "packagingType": {
    },
  • "externalId": {
    },
  • "gtin": {
    },
  • "servings": {
    },
  • "bomFileName": "string",
  • "ingredients": [
    ],
  • "materials": [
    ],
  • "productionFacilities": [
    ],
  • "folderPath": {
    }
}

Response samples

Content type
application/json
{
  • "id": "PW1002",
  • "status": "queued",
  • "customerId": "customerid.f238625e01f845fabd1100585225af06",
  • "workspaceId": "workspace.33163c24ac1241fa8649e811d57b8a9f",
  • "createdAt": "2026-08-07T09:04:11Z",
  • "updatedAt": "2026-08-07T09:04:11Z"
}

Replace a low-res product

Overwrites a previously ingested product and recalculates it.

skuId.source in the body must equal the {skuId} path segment, otherwise the request is rejected with 400.

Authorizations:
ApiKeyAuth
path Parameters
skuId
required
string
Example: PW1002

Your own SKU identifier, as supplied in skuId.source at ingestion. Unique per customer, across all of that customer's workspaces.

header Parameters
X-Integration-Customer-Alias
string
Example: 123456

Selects the target customer within your integration. Globally unique.

If the alias does not exist, the customer is provisioned automatically. If omitted, the integration's default customer is used.

X-Integration-Customer-Name
string
Example: ACME, Ltd.

Display name applied when a customer is provisioned for the first time. Ignored if the customer already exists. If omitted, the integration name plus customer ID is used.

X-Integration-Workspace-Alias
string

Selects the target workspace within the customer. Unique per customer.

If the alias does not exist, the workspace is provisioned automatically. If omitted, the default workspace is used.

Applies to ingestion endpoints only — reporting and deletion resolve the workspace from the SKU.

Request Body schema: application/json
required
object

Your SKU identifier. Unique per customer across all its workspaces.

object

Like TaggedString, but source is required — these identify the record and cannot be resolved from anything else.

object

Net content of one sellable unit, in unit.

object

g or ml.

object

Like TaggedString, but source is required — these identify the record and cannot be resolved from anything else.

object
object
object

An optional value in envelope form. Send source with your own value; Sustained resolves target.

object

An optional value in envelope form. Send source with your own value; Sustained resolves target.

object

An optional value in envelope form. Send source with your own value; Sustained resolves target.

object

An optional numeric value in envelope form.

object

An optional value in envelope form. Send source with your own value; Sustained resolves target.

object

An optional value in envelope form. Send source with your own value; Sustained resolves target.

object

An optional value in envelope form. Send source with your own value; Sustained resolves target.

object

An optional value in envelope form. Send source with your own value; Sustained resolves target.

object

An optional integer value in envelope form.

bomFileName
string
Array of objects (LowResIngredient)
Array of objects (TaggedMaterial)
Array of objects (LowResProductionFacility)
object

Where the product is filed in the workspace.

folderSid wins over space/subSpace when it resolves. If it does not, the import falls back to space/subSpace and then to the product type's default location — an unresolvable folder never fails the import.

Responses

Request samples

Content type
application/json
{
  • "skuId": {
    },
  • "name": {
    },
  • "amount": {
    },
  • "unit": {
    },
  • "category": {
    },
  • "type": {
    },
  • "stage": {
    },
  • "class": {
    },
  • "conservation": {
    },
  • "form": {
    },
  • "economicValue": {
    },
  • "currency": {
    },
  • "packagingType": {
    },
  • "externalId": {
    },
  • "gtin": {
    },
  • "servings": {
    },
  • "bomFileName": "string",
  • "ingredients": [
    ],
  • "materials": [
    ],
  • "productionFacilities": [
    ],
  • "folderPath": {
    }
}

Response samples

Content type
application/json
{
  • "id": "PW1002",
  • "status": "queued",
  • "customerId": "customerid.f238625e01f845fabd1100585225af06",
  • "workspaceId": "workspace.33163c24ac1241fa8649e811d57b8a9f",
  • "createdAt": "2026-08-07T09:04:11Z",
  • "updatedAt": "2026-08-07T09:04:11Z"
}

Get a low-res product and its report

Returns the job status, the resolved product document, and — once status is finished — the impact report including the per-category breakdown.

For the headline score alone, use /impact-score, which omits categories.

Authorizations:
ApiKeyAuth
path Parameters
skuId
required
string
Example: PW1002

Your own SKU identifier, as supplied in skuId.source at ingestion. Unique per customer, across all of that customer's workspaces.

header Parameters
X-Integration-Customer-Alias
string
Example: 123456

Selects the target customer within your integration. Globally unique.

If the alias does not exist, the customer is provisioned automatically. If omitted, the integration's default customer is used.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "queued",
  • "productState": "draft",
  • "error": "string",
  • "customerId": "string",
  • "workspaceId": "string",
  • "productId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "product": {
    },
  • "report": {
    }
}

Delete a low-res product

Authorizations:
ApiKeyAuth
path Parameters
skuId
required
string
Example: PW1002

Your own SKU identifier, as supplied in skuId.source at ingestion. Unique per customer, across all of that customer's workspaces.

header Parameters
X-Integration-Customer-Alias
string
Example: 123456

Selects the target customer within your integration. Globally unique.

If the alias does not exist, the customer is provisioned automatically. If omitted, the integration's default customer is used.

Responses

Response samples

Content type
application/json
Example
{
  • "message": "packaging is not supported in low resolution use-case",
  • "response_code": 400
}

Get the headline impact score only

Identical to GET /v1/ingest/lowres/{skuId}, except report.categories is omitted.

Use this for list views and dashboards where only the overall score is needed.

Authorizations:
ApiKeyAuth
path Parameters
skuId
required
string
Example: PW1002

Your own SKU identifier, as supplied in skuId.source at ingestion. Unique per customer, across all of that customer's workspaces.

header Parameters
X-Integration-Customer-Alias
string
Example: 123456

Selects the target customer within your integration. Globally unique.

If the alias does not exist, the customer is provisioned automatically. If omitted, the integration's default customer is used.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "queued",
  • "productState": "draft",
  • "error": "string",
  • "customerId": "string",
  • "workspaceId": "string",
  • "productId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "product": {
    },
  • "report": {
    }
}

High-res

Full-resolution ingestion and reporting, including packaging, distribution paths and the contributor tree.

Ingest a high-res product

Submits a new product for full-resolution assessment, including packaging, distribution and production detail.

Returns immediately with a job envelope. Poll GET /v1/ingest/highres/{skuId} until status is finished or failed.

Authorizations:
ApiKeyAuth
header Parameters
X-Integration-Customer-Alias
string
Example: 123456

Selects the target customer within your integration. Globally unique.

If the alias does not exist, the customer is provisioned automatically. If omitted, the integration's default customer is used.

X-Integration-Customer-Name
string
Example: ACME, Ltd.

Display name applied when a customer is provisioned for the first time. Ignored if the customer already exists. If omitted, the integration name plus customer ID is used.

X-Integration-Workspace-Alias
string

Selects the target workspace within the customer. Unique per customer.

If the alias does not exist, the workspace is provisioned automatically. If omitted, the default workspace is used.

Applies to ingestion endpoints only — reporting and deletion resolve the workspace from the SKU.

Request Body schema: application/json
required
object

Your SKU identifier. Unique per customer across all its workspaces.

object

Product name.

object

Net content of one sellable unit, in unit.

object

g or ml.

object

Product category. Values from /v1/ingest/categories.

object

Product type. source accepts the values of ProductType; defaults to final_product.

object

Lifecycle stage. Defaults to production.

object

Optional product classification.

object

Groups product variants that share a model. High-res only.

object

Display name for the group. High-res only.

object

Storage temperature regime.

object

liquid or solid.

object

Unit economic value, used to allocate impact across co-products.

object

An optional value in envelope form. Send source with your own value; Sustained resolves target.

object

An optional value in envelope form. Send source with your own value; Sustained resolves target.

object

Packaging-system dimensions of the highest populated packaging level, in cm. Optional — defaults are applied when absent.

object

Your own identifier, carried through untouched.

object

An optional value in envelope form. Send source with your own value; Sustained resolves target.

object

An optional integer value in envelope form.

bomFileName
string

Source bill-of-materials filename, for traceability.

Array of objects (HighResIngredient)
Array of objects (TaggedPackaging)

High-res only.

Array of objects (TaggedMaterial)
Array of objects (HighResProductionFacility)
Array of objects (TaggedDistributionPath)

High-res only.

object

Where the product is filed in the workspace. Only valid for final_product and intermediate_product; anything else is rejected with 400.

Responses

Request samples

Content type
application/json
{
  • "skuId": {
    },
  • "name": {
    },
  • "type": {
    },
  • "amount": {
    },
  • "unit": {
    },
  • "category": {
    },
  • "ingredients": [
    ],
  • "packaging": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "PW1002",
  • "status": "queued",
  • "customerId": "customerid.f238625e01f845fabd1100585225af06",
  • "workspaceId": "workspace.33163c24ac1241fa8649e811d57b8a9f",
  • "createdAt": "2026-08-07T09:04:11Z",
  • "updatedAt": "2026-08-07T09:04:11Z"
}

Replace a high-res product

Overwrites a previously ingested product and recalculates it.

skuId.source in the body must equal the {skuId} path segment, otherwise the request is rejected with 400.

Authorizations:
ApiKeyAuth
path Parameters
skuId
required
string
Example: PW1002

Your own SKU identifier, as supplied in skuId.source at ingestion. Unique per customer, across all of that customer's workspaces.

header Parameters
X-Integration-Customer-Alias
string
Example: 123456

Selects the target customer within your integration. Globally unique.

If the alias does not exist, the customer is provisioned automatically. If omitted, the integration's default customer is used.

X-Integration-Customer-Name
string
Example: ACME, Ltd.

Display name applied when a customer is provisioned for the first time. Ignored if the customer already exists. If omitted, the integration name plus customer ID is used.

X-Integration-Workspace-Alias
string

Selects the target workspace within the customer. Unique per customer.

If the alias does not exist, the workspace is provisioned automatically. If omitted, the default workspace is used.

Applies to ingestion endpoints only — reporting and deletion resolve the workspace from the SKU.

Request Body schema: application/json
required
object

Your SKU identifier. Unique per customer across all its workspaces.

object

Product name.

object

Net content of one sellable unit, in unit.

object

g or ml.

object

Product category. Values from /v1/ingest/categories.

object

Product type. source accepts the values of ProductType; defaults to final_product.

object

Lifecycle stage. Defaults to production.

object

Optional product classification.

object

Groups product variants that share a model. High-res only.

object

Display name for the group. High-res only.

object

Storage temperature regime.

object

liquid or solid.

object

Unit economic value, used to allocate impact across co-products.

object

An optional value in envelope form. Send source with your own value; Sustained resolves target.

object

An optional value in envelope form. Send source with your own value; Sustained resolves target.

object

Packaging-system dimensions of the highest populated packaging level, in cm. Optional — defaults are applied when absent.

object

Your own identifier, carried through untouched.

object

An optional value in envelope form. Send source with your own value; Sustained resolves target.

object

An optional integer value in envelope form.

bomFileName
string

Source bill-of-materials filename, for traceability.

Array of objects (HighResIngredient)
Array of objects (TaggedPackaging)

High-res only.

Array of objects (TaggedMaterial)
Array of objects (HighResProductionFacility)
Array of objects (TaggedDistributionPath)

High-res only.

object

Where the product is filed in the workspace. Only valid for final_product and intermediate_product; anything else is rejected with 400.

Responses

Request samples

Content type
application/json
{
  • "skuId": {
    },
  • "name": {
    },
  • "amount": {
    },
  • "unit": {
    },
  • "category": {
    },
  • "type": {
    },
  • "stage": {
    },
  • "class": {
    },
  • "groupId": {
    },
  • "groupName": {
    },
  • "conservation": {
    },
  • "form": {
    },
  • "economicValue": {
    },
  • "currency": {
    },
  • "packagingType": {
    },
  • "finalLevelDimensions": {
    },
  • "externalId": {
    },
  • "gtin": {
    },
  • "servings": {
    },
  • "bomFileName": "string",
  • "ingredients": [
    ],
  • "packaging": [
    ],
  • "materials": [
    ],
  • "productionFacilities": [
    ],
  • "distributionPaths": [
    ],
  • "folderPath": {
    }
}

Response samples

Content type
application/json
{
  • "id": "PW1002",
  • "status": "queued",
  • "customerId": "customerid.f238625e01f845fabd1100585225af06",
  • "workspaceId": "workspace.33163c24ac1241fa8649e811d57b8a9f",
  • "createdAt": "2026-08-07T09:04:11Z",
  • "updatedAt": "2026-08-07T09:04:11Z"
}

Get a high-res product and its report

Returns the job status, the resolved product document, and — once status is finished — the full report: per-category impacts, the contributor tree, transport legs and the consumer label.

Authorizations:
ApiKeyAuth
path Parameters
skuId
required
string
Example: PW1002

Your own SKU identifier, as supplied in skuId.source at ingestion. Unique per customer, across all of that customer's workspaces.

header Parameters
X-Integration-Customer-Alias
string
Example: 123456

Selects the target customer within your integration. Globally unique.

If the alias does not exist, the customer is provisioned automatically. If omitted, the integration's default customer is used.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "queued",
  • "productState": "draft",
  • "error": "string",
  • "customerId": "string",
  • "workspaceId": "string",
  • "productId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "product": {
    },
  • "report": {},
  • "categories": []
}

Delete a high-res product

Authorizations:
ApiKeyAuth
path Parameters
skuId
required
string
Example: PW1002

Your own SKU identifier, as supplied in skuId.source at ingestion. Unique per customer, across all of that customer's workspaces.

header Parameters
X-Integration-Customer-Alias
string
Example: 123456

Selects the target customer within your integration. Globally unique.

If the alias does not exist, the customer is provisioned automatically. If omitted, the integration's default customer is used.

Responses

Response samples

Content type
application/json
Example
{
  • "message": "packaging is not supported in low resolution use-case",
  • "response_code": 400
}

Get the contributor tree for one impact category

Returns the nested contributor breakdown for a single impact category — which ingredients, packaging and processes drive the result, and by how much.

category is required. An unknown value is rejected with 400.

Authorizations:
ApiKeyAuth
path Parameters
skuId
required
string
Example: PW1002

Your own SKU identifier, as supplied in skuId.source at ingestion. Unique per customer, across all of that customer's workspaces.

query Parameters
category
required
string (ImpactCategoryId)
Enum: "pef_human_health" "pef_resource_use" "pef_wildlife_damage" "pef_climate_change" "pef_land_use" "pef_water_scarcity" "pef_acidification" "pef_ecotoxicity_freshwater" "pef_eutrophication_freshwater" "pef_eutrophication_marine" "pef_eutrophication_terrestrial" "pef_human_toxicity_cancer" "pef_human_toxicity_non_cancer" "pef_ionising_radiation" "pef_ozone_depletion" "pef_particulate_matter" "pef_ozone_formation" "pef_resource_use_fossils" "pef_resource_use_minerals"
Example: category=pef_climate_change

The impact category to break down.

includeOnlyMajor
boolean
Default: false

When true, prunes the tree to major contributors only. Defaults to false.

header Parameters
X-Integration-Customer-Alias
string
Example: 123456

Selects the target customer within your integration. Globally unique.

If the alias does not exist, the customer is provisioned automatically. If omitted, the integration's default customer is used.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "queued",
  • "productState": "draft",
  • "error": "string",
  • "customerId": "string",
  • "workspaceId": "string",
  • "productId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "product": {
    },
  • "report": {},
  • "categories": []
}

Taxonomy

Read-only vocabulary listings. Use these rather than hard-coding enum values — they are the authoritative set and change without an API version bump.

List product categories

The product categories a product can be assigned to. Supply the name or ID as category.source on a product document.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "list": [
    ]
}

List packaging types and materials

Packaging types, each with its material categories and the material types within them. Mirrors the three-level shape of a packaging document: type → material category → material type.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "list": [
    ]
}

List food production processes

Processes available for food production steps. Supply the ID as processId.source on a production facility step.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "list": [
    ]
}

List packaging production processes

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "list": [
    ]
}

List food packing processes

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "list": [
    ]
}
Guide API reference