API docs by Redocly

Fairglow Product LCA API (0.0.5)

Download OpenAPI specification:

API for creating, updating, and performing LCA calculations on products.

Create or update the product

Creates the product if no product exists with this id (201), and updates it otherwise (200). An unknown id therefore never returns 404. While a calculation for the latest version is queued or running, a PUT gets a 409; send it again once the job has finished.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string^(?!\.{1,2}$)[A-Za-z0-9._~-]{1,128}$

Unique product identifier provided by the API user: 1 to 128 characters, each a letter, a digit, or one of . _ ~ -, and not . or .. alone. Any other identifier gets a 400.

Request Body schema: application/json
required

This payload represents a finished consumer product.

Preferred values for certain fields

Fields tagged with ✳️ have preferred values that are optional but will help improve the speed and accuracy of the LCA calculation.

If not provided, the API will attempt to normalize values to a preferred value during LCA calculation.

Lists are full replacements

Every list in this payload replaces the product's existing list in full; items are never merged or matched between calls. For that reason packaging and manufacturing are always required, together with exactly one of ingredients or trade_names. Send an empty list ([]) to state that the product has none of an item. A missing list, or a list sent as null, is rejected.

Transport

The product, every trade name, every ingredient listed directly on the product, and every packaging element carry transport information. Ingredients and packaging use supply transport: from the supplier's location to your manufacturing facility. The product uses distribution transport: from your manufacturing facility to the market where the product is sold. Each must give at least one distance, or enough geography to calculate one. When any distance is given, only the distances given are used.

One of
product_name
required
string

Name of the product.

product_brand
string

Brand of the product.

product_line
string

Product line or series.

volume_ml
required
number

Size of the product in millilitres. Send either this or weight_g, not both. To give the product's mass, also send net_weight_g; otherwise we assume a density of 1.036 g/ml.

weight_g
number

Size of the product in grams; this is its mass. Send either this or volume_ml, not both.

net_weight_g
number

Net weight as printed on the pack, in grams: the product's mass. Only with volume_ml.

product_category
required
string

Main category of the product. For now it must match a Fairglow category exactly; a category that does not match gets a 400. Other free-text names that don't match a Fairglow record fall back to a generic record. ✳️

product_subcategory
string

Subcategory of the product. ✳️

object

Your own reference fields for this product, as key-value pairs of strings (e.g., an internal SKU or formula code). Stored with the product and shown in Fairglow.

required
object or object or object or object or object (DistributionTransport)

Transport of the finished product from your manufacturing facility to the market where it is sold. Give at least one distance, or both geographies. When any distance is given, only the distances given are used, and geographies are not used to fill in the rest.

packaging_reuse_count
number

If the product is reusable, the number of times the packaging can be reused.

Array of objects or objects (Ingredient)

List of ingredient objects, for products whose ingredients are not grouped into trade names. Provide exactly one of ingredients or trade_names. Replaces the product's full ingredient list on every call. Give amounts the same way across the product: all as concentrations or all as masses. Inside a trade name, ingredient concentrations are shares of the trade name and follow the trade name's basis.

Array of objects or objects (TradeName)

List of trade name objects. Provide exactly one of ingredients or trade_names. Replaces the product's full ingredient list on every call. Give amounts the same way across the product: all as concentrations or all as masses. Inside a trade name, ingredient concentrations are shares of the trade name and follow the trade name's basis.

required
Array of objects (PackagingElement)

List of packaging element objects. Required; replaces the product's full packaging list on every call. Send [] if the product has no packaging.

required
Array of objects or objects (ManufacturingActivity)

List of manufacturing activity objects. Required; replaces the product's full manufacturing list on every call. An empty list ([]) means Fairglow applies its default manufacturing assumptions; any activity category not provided is also filled with Fairglow defaults.

Responses

Request samples

Content type
application/json
{
  • "product_name": "Nourishing Shampoo 250 ml",
  • "product_brand": "Maison Verdure",
  • "product_line": "Botanical Care",
  • "volume_ml": 250,
  • "net_weight_g": 259,
  • "product_category": "Hair",
  • "product_subcategory": "Shampoo",
  • "custom_fields": {
    },
  • "transport_info": {
    },
  • "ingredients": [
    ],
  • "packaging": [
    ],
  • "manufacturing": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Product updated successfully.",
  • "product_id": "SKU-10245"
}

Start an LCA calculation job

Authorizations:
ApiKeyAuth
path Parameters
id
required
string^(?!\.{1,2}$)[A-Za-z0-9._~-]{1,128}$

Unique product identifier provided by the API user: 1 to 128 characters, each a letter, a digit, or one of . _ ~ -, and not . or .. alone. Any other identifier gets a 400.

Responses

Response samples

Content type
application/json
{}

Get the status and results of a job

Authorizations:
ApiKeyAuth
path Parameters
job_id
required
string <uuid>

Unique identifier for the job, a UUID. Any other identifier gets a 400.

Responses

Response samples

Content type
application/json
Example
{
  • "job_id": "7f3c2a9e-4b1d-4e8a-9c6f-2d5b8e1a0c34",
  • "status": "COMPLETED",
  • "tracking_url": "https://platform.fairglow.tech/lca/jobs/7f3c2a9e-4b1d-4e8a-9c6f-2d5b8e1a0c34",
  • "results": {
    }
}