Create purchased item

Request

Creating a purchased item is mandatory when doing traceability with Fairly Made, for each item you want Fairly Made to analyse. This endpoint creates a record representing an item purchased between buyers and sellers, with optional transport and quantity details.

Required references: send exactly one of buyerId or buyerUniqueIdentifier (buyer is required), exactly one of sellerId or sellerUniqueIdentifier (seller is required), and exactly one of itemId or itemUniqueIdentifier (purchased entity is required). buyerUniqueIdentifier requires buyerKind = SUPPLIER.

purchaseOrder is required. If you run traceability collection with Fairly Made, you must provide at least a purchaseOrder for each purchased item: without that link, Fairly Made cannot launch supplier data collection. If your chosen analysis granularity is not at purchase-order level, provide a representative PO for the panel covered by that granularity. If you are unable to provide a PO at all, you can set the value to NOT_SPECIFIED. Links made only through used items (usedMaterials, usedComponents, usedProducts, etc.) instead of purchasedItems are not taken into account for the analysis.

If you send certifications with at least one entry, each entry must include certificationName.

Bodyapplication/jsonrequired

uniqueIdentifierstringrequired

This identifier will make each purchased item unique in our systems.

buyerKindstringrequired

The type of buyer (customer -yourself- or supplier) for this item.

Enum:"CUSTOMER""SUPPLIER"

buyerIdstring, (uuid)

System UUID of the buyer. Required as exactly one of buyerId or buyerUniqueIdentifier (not both, not neither).

buyerUniqueIdentifierstring

Client uniqueIdentifier of the buyer supplier. Required as exactly one of buyerId or buyerUniqueIdentifier. Requires buyerKind = SUPPLIER. Mutually exclusive with buyerId.

sellerIdstring, (uuid)

System UUID of the supplier that sold the item. Required as exactly one of sellerId or sellerUniqueIdentifier (not both, not neither).

sellerUniqueIdentifierstring

Client uniqueIdentifier of the seller supplier. Required as exactly one of sellerId or sellerUniqueIdentifier. Mutually exclusive with sellerId.

purchaseOrderstringrequired

Purchase order number for this transaction. Required. If you run traceability collection with Fairly Made, this link is needed so Fairly Made can launch supplier data collection. If your analysis granularity is not at purchase-order level, use a representative PO for the panel covered by that granularity. If you are unable to provide a PO at all, you can set the value to NOT_SPECIFIED.

purchaseOrderDatestring, (date)

The date of the transaction. Calendar date only, format YYYY-MM-DD (RFC 3339 full-date / ISO 8601), e.g. 2026-04-29.

transportsArray of objects(Transport)

The transportation mode used for this transaction.

purchasedQuantityobject(Quantity)

The purchased quantity for this transaction. If itemId references a product, the only allowed unit is PIECES.

certificationsArray of objects

Optional. If the array is present and contains at least one object, each object must include certificationName.

itemIdstring, (uuid)

System UUID of the purchased entity (manufactured product, component, or material). Required as exactly one of itemId or itemUniqueIdentifier (not both, not neither).

itemUniqueIdentifierstring

Client uniqueIdentifier of the purchased entity (manufactured product, component, or material). Required as exactly one of itemId or itemUniqueIdentifier. Mutually exclusive with itemId.

curl -i -X POST \
  https://doc.api.fairlymade.com/_mock/swagger-fairlymadeapi-v3/purchased-items \
  -H 'Content-Type: application/json' \
  -d '{
    "uniqueIdentifier": "FM-PURCHASED-ITEM-MAT-0001",
    "buyerKind": "CUSTOMER",
    "buyerId": "f0b5fb65-f065-432e-9e96-c52692931626",
    "sellerId": "a5765369-b42c-4e6f-849b-0c3873e8deb5",
    "purchaseOrder": "PO-2026-01",
    "itemId": "364c5ece-7f42-418b-baa7-9a272dd044ef"
  }'

Responses

Purchased item created

Bodyapplication/json

purchasedItemIdstring, (uuid)

Identifier of the created purchased item. UUID v4 format.

Response

{
  "purchasedItemId": "c71367fd-41b4-4f55-a878-880751ae6d3a"
}