components:
  schemas:
    retailerapi.CreateResoldProductRequest:
      properties:
        alcoholPercentage:
          type: number
        brandName:
          type: string
        categories:
          items:
            type: string
          type: array
          uniqueItems: false
        customId:
          maxLength: 255
          type: string
        description:
          type: string
        groupId:
          type: string
        gtin:
          maxLength: 14
          type: string
        imageUrl:
          type: string
        ingredients:
          type: string
        name:
          maxLength: 255
          minLength: 3
          type: string
        packagingMaterial:
          type: string
        packagingType:
          type: string
        packagingWeightUnit:
          type: string
        packagingWeightValue:
          type: number
        pickUpLocation:
          type: string
        productNetQuantityUnit:
          type: string
        productNetQuantityValue:
          type: number
        productionLocation:
          type: string
        shipToLocation:
          type: string
        yearlySalesVolumes:
          $ref: '#/components/schemas/retailerapi.SalesVolumes'
      required:
        - groupId
        - name
        - pickUpLocation
        - productionLocation
        - shipToLocation
      type: object
    retailerapi.CreateSupplierRequest:
      description: Request body for creating a new supplier
      properties:
        contacts:
          items:
            $ref: '#/components/schemas/retailerapi.SupplierContactInput'
          type: array
          uniqueItems: false
        customId:
          maxLength: 255
          type: string
        groupId:
          type: string
        name:
          maxLength: 255
          minLength: 3
          type: string
      required:
        - groupId
        - name
      type: object
    retailerapi.FlagBreakdown:
      properties:
        carbonRemovals:
          type: number
        landManagementCO2:
          $ref: '#/components/schemas/retailerapi.LandManagementCO2Breakdown'
        landManagementNonCO2:
          $ref: '#/components/schemas/retailerapi.LandManagementNonCO2Breakdown'
        landUseChange:
          $ref: '#/components/schemas/retailerapi.LandUseChangeBreakdown'
        total:
          $ref: '#/components/schemas/retailerapi.Total'
      type: object
    retailerapi.FlagFootprint:
      description: >-
        Climate footprint kg C02e per kg with forest, land and agriculture
        breakdown. Calculated according to `calculationMethod`.
      properties:
        calculationMethod:
          enum:
            - location
            - market
          type: string
        embeddedFossilCarbon:
          type: number
        flag:
          $ref: '#/components/schemas/retailerapi.FlagBreakdown'
        other:
          type: number
        packaging:
          type: number
        pds:
          $ref: '#/components/schemas/retailerapi.PdsFactors'
        processing:
          type: number
        storage:
          type: number
        total:
          type: number
        transportation:
          type: number
        updatedAt:
          format: date-time
          type: string
      required:
        - calculationMethod
        - embeddedFossilCarbon
        - flag
        - other
        - packaging
        - processing
        - storage
        - total
        - transportation
        - updatedAt
      type: object
    retailerapi.FootprintItem:
      properties:
        footprint:
          $ref: '#/components/schemas/retailerapi.FlagFootprint'
        productId:
          description: Resold product ID.
          type: string
      required:
        - productId
      type: object
    retailerapi.Group:
      properties:
        id:
          description: Group ID.
          format: uuid
          type: string
        name:
          description: Name of group.
          type: string
      required:
        - id
        - name
      type: object
    retailerapi.InviteProduct:
      properties:
        id:
          type: string
      type: object
    retailerapi.InviteRequest:
      description: Request body for inviting a supplier to provide data.
      properties:
        products:
          items:
            $ref: '#/components/schemas/retailerapi.InviteProduct'
          type: array
          uniqueItems: false
        supplierId:
          type: string
      required:
        - products
        - supplierId
      type: object
    retailerapi.InviteResponse:
      description: Response body for supplier invitation
      properties:
        status:
          type: string
      required:
        - status
      type: object
    retailerapi.LandManagementCO2Breakdown:
      properties:
        organicSoilsCO2:
          type: number
        total:
          $ref: '#/components/schemas/retailerapi.Total'
      type: object
    retailerapi.LandManagementNonCO2Breakdown:
      properties:
        directEmissionsN2O:
          type: number
        dryingCO2:
          type: number
        farmMachineryCO2:
          type: number
        fertilizerProductionCO2:
          type: number
        fertilizerProductionN2O:
          type: number
        indirectEmissionsN2O:
          type: number
        irrigationCO2:
          type: number
        limestoneAndUreaCO2:
          type: number
        organicSoilsN2O:
          type: number
        pesticideProductionCO2:
          type: number
        riceCultivationCH4:
          type: number
        total:
          $ref: '#/components/schemas/retailerapi.Total'
      type: object
    retailerapi.LandUseChangeBreakdown:
      properties:
        deforestationCO2:
          type: number
        total:
          $ref: '#/components/schemas/retailerapi.Total'
      type: object
    retailerapi.LinkedProductStatus:
      enum:
        - created
        - sent
        - declined
        - accepted
        - active
      type: string
      x-enum-varnames:
        - LinkedProductStatusCreated
        - LinkedProductStatusSent
        - LinkedProductStatusDeclined
        - LinkedProductStatusAccepted
        - LinkedProductStatusActive
    retailerapi.Pds:
      description: Represents the primary data share split.
      properties:
        primary:
          type: number
        secondary:
          type: number
      type: object
    retailerapi.PdsFactors:
      description: |-
        Primary data share.
        Only available in primary data PCF.
      properties:
        embeddedFossilCarbon:
          $ref: '#/components/schemas/retailerapi.Pds'
        flag:
          $ref: '#/components/schemas/retailerapi.Pds'
        other:
          $ref: '#/components/schemas/retailerapi.Pds'
        packaging:
          $ref: '#/components/schemas/retailerapi.Pds'
        processing:
          $ref: '#/components/schemas/retailerapi.Pds'
        total:
          $ref: '#/components/schemas/retailerapi.Pds'
        transportation:
          $ref: '#/components/schemas/retailerapi.Pds'
      type: object
    retailerapi.ProductSuppliersRequest:
      description: Request to set supplier periods for a product
      properties:
        suppliers:
          items:
            $ref: '#/components/schemas/retailerapi.SupplierPeriodInput'
          type: array
          uniqueItems: false
      required:
        - suppliers
      type: object
    retailerapi.ResoldProduct:
      properties:
        alcoholPercentage:
          type: number
        brandName:
          type: string
        categories:
          items:
            type: string
          type: array
          uniqueItems: false
        createdAt:
          format: date-time
          type: string
        customId:
          maxLength: 255
          type: string
        description:
          type: string
        groupId:
          type: string
        gtin:
          type: string
        id:
          type: string
        imageUrl:
          type: string
        ingredients:
          type: string
        name:
          maxLength: 255
          minLength: 3
          type: string
        packagingMaterial:
          type: string
        packagingType:
          type: string
        packagingWeightUnit:
          type: string
        packagingWeightValue:
          type: number
        pickUpLocation:
          type: string
        productNetQuantityUnit:
          type: string
        productNetQuantityValue:
          type: number
        productionLocation:
          type: string
        shipToLocation:
          type: string
        updatedAt:
          format: date-time
          type: string
        yearlySalesVolumes:
          $ref: '#/components/schemas/retailerapi.SalesVolumes'
      required:
        - groupId
        - id
        - name
        - pickUpLocation
        - productionLocation
        - shipToLocation
      type: object
    retailerapi.SalesVolumes:
      additionalProperties:
        type: number
      description: 'Sales volumes in tonnes/year. Object with fields like "2025": 123.0,'
      type: object
    retailerapi.Supplier:
      description: Represents a supplier organization
      properties:
        contacts:
          items:
            $ref: '#/components/schemas/retailerapi.SupplierContact'
          type: array
          uniqueItems: false
        createdAt:
          format: date-time
          type: string
        customId:
          type: string
        groupId:
          type: string
        id:
          type: string
        name:
          type: string
        status:
          enum:
            - created
            - invited
            - connected
          type: string
        updatedAt:
          format: date-time
          type: string
      required:
        - contacts
        - createdAt
        - groupId
        - id
        - name
        - status
        - updatedAt
      type: object
    retailerapi.SupplierContact:
      description: >-
        Represents a contact for a supplier (response only; id is set by the
        server)
      properties:
        email:
          type: string
        firstName:
          type: string
        id:
          type: string
        lastName:
          type: string
      required:
        - email
        - firstName
        - lastName
      type: object
    retailerapi.SupplierContactInput:
      properties:
        email:
          type: string
        firstName:
          type: string
        lastName:
          type: string
      required:
        - email
        - firstName
        - lastName
      type: object
    retailerapi.SupplierLinkedProduct:
      description: Product linked to a supplier with its current status.
      properties:
        id:
          type: string
        name:
          type: string
        status:
          $ref: '#/components/schemas/retailerapi.LinkedProductStatus'
      type: object
    retailerapi.SupplierPeriodInput:
      description: >-
        A supplier period input. To update an existing period, include its `id`
        (obtained from `GET /resold-products/{id}/suppliers`). Only the date
        fields (validFrom, validTo) can be changed on existing periods; the
        supplier cannot be changed after creation. Periods without an `id` are
        created as new. Existing periods whose `id` is not included in the
        request will be deleted.
      properties:
        id:
          example: 550e8400-e29b-41d4-a716-446655440000
          type: string
        supplierId:
          example: 550e8400-e29b-41d4-a716-446655440001
          type: string
        validFrom:
          example: '2024-01-15'
          format: date
          type: string
        validTo:
          example: '2024-06-30'
          format: date
          type: string
      required:
        - supplierId
      type: object
    retailerapi.SupplierPeriodResponse:
      description: Supplier period response
      properties:
        createdAt:
          format: date-time
          type: string
        id:
          type: string
        supplierId:
          type: string
        supplierName:
          type: string
        updatedAt:
          format: date-time
          type: string
        validFrom:
          example: '2024-01-15'
          format: date
          type: string
        validTo:
          example: '2024-06-30'
          format: date
          type: string
      type: object
    retailerapi.Total:
      properties:
        ch4:
          type: number
        co2:
          type: number
        n2o:
          type: number
        sum:
          type: number
      required:
        - sum
      type: object
    retailerapi.Update:
      properties:
        productId:
          description: Resold product ID.
          type: string
        updatedAt:
          format: date-time
          type: string
      required:
        - productId
        - updatedAt
      type: object
    retailerapi.UpdateResoldProductRequest:
      properties:
        alcoholPercentage:
          type: number
        brandName:
          type: string
        categories:
          items:
            type: string
          type: array
          uniqueItems: false
        customId:
          maxLength: 255
          type: string
        description:
          description: Fields exclusively used for classification.
          type: string
        gtin:
          maxLength: 14
          type: string
        imageUrl:
          type: string
        ingredients:
          type: string
        name:
          maxLength: 255
          minLength: 3
          type: string
        packagingMaterial:
          type: string
        packagingType:
          type: string
        packagingWeightUnit:
          type: string
        packagingWeightValue:
          type: number
        pickUpLocation:
          type: string
        productNetQuantityUnit:
          type: string
        productNetQuantityValue:
          type: number
        productionLocation:
          type: string
        shipToLocation:
          type: string
        yearlySalesVolumes:
          $ref: '#/components/schemas/retailerapi.SalesVolumes'
      required:
        - name
        - pickUpLocation
        - productionLocation
        - shipToLocation
      type: object
    retailerapi.UpdateSupplierRequest:
      description: Request body for updating an existing supplier
      properties:
        contacts:
          items:
            $ref: '#/components/schemas/retailerapi.SupplierContact'
          type: array
          uniqueItems: false
        customId:
          maxLength: 255
          type: string
        name:
          maxLength: 255
          minLength: 3
          type: string
      type: object
    retailerapi.errorResponse:
      description: A generic error response
      properties:
        detail:
          description: Optional detailed description of error at hand.
          type: string
        error:
          description: Text representation of the error status.
          type: string
      type: object
info:
  description: >-
    Retailer API for supplier management.


    This API uses Bearer token authentication.

    To retrieve an access token perform an OAuth2 password grant request to:

    `https://auth.carboncloud.com/realms/prod/protocol/openid-connect/token`


    With the following URL-encoded parameters in the body:

    - client_id: `carboncloud`

    - grant_type: `password`

    - username: `<your username>`

    - password: `<your password>`


    Pass in the access token to endpoint requests in a header like
    `Authorization: Bearer <access_token>`.


    Set the `x-request-id` header to a random value in each request. Include the
    header value from relevant requests in trouble reports to aid
    troubleshooting.
  title: Retailer API
  version: v1
externalDocs:
  description: ''
  url: ''
paths:
  /groups:
    get:
      description: |-
        Every product and supplier belongs to exactly one group.

        The response IDs can be used in other endpoints to scope requests.
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/retailerapi.Group'
                type: array
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Bad Request
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Internal Server Error
      summary: List available groups.
      tags:
        - Groups
  /invite:
    post:
      description: >-
        Invite a supplier to provide data on relevant products.


        The supplier will be requested to provide data on products.

        The supplier must be the active supplier (aka linked) to each given
        product.


        Sends a platform invite email to supplier contacts.

        Supplier contacts who have received such an email from previous calls to
        this endpoint will not be sent an additional email.

        Once the supplier has registered in the platform no further emails are
        sent.


        If a product data request has been declined then calling invite with
        that product sends a new data request.


        Status 425 indicates some product has not yet finished the necessary
        background processing.

        Try again after some time, ideally with increasing backoff.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/retailerapi.InviteRequest'
        description: Invite request
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.InviteResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Not Found
        '425':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Too Early
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Internal Server Error
      summary: Products and supplier invite
      tags:
        - Invites
  /resold-products:
    get:
      description: |-
        Paginate resold products. The response will be ordered by their ID.
        Use the optional query parameter to control the pagination.
      parameters:
        - description: Group UUID to list products of.
          in: query
          name: groupId
          required: true
          schema:
            type: string
        - description: Resold product UUID to start page from (non-inclusive).
          in: query
          name: from
          schema:
            type: string
        - description: >-
            Limit on the number of products listed. Defaults to 32. Must be in
            range [1, 128].
          in: query
          name: limit
          schema:
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/retailerapi.ResoldProduct'
                type: array
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Forbidden
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Internal Server Error
      summary: List resold products.
      tags:
        - Products
    post:
      description: Create a new product which is bought as it is sold.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/retailerapi.CreateResoldProductRequest'
        description: Request body for creating a new product
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.ResoldProduct'
          description: Created
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Forbidden
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Internal Server Error
      summary: Create a new resold product.
      tags:
        - Products
  /resold-products/flag:
    post:
      description: Get forest, land and agriculture emissions breakdown of many products.
      parameters:
        - description: Required groupId.
          in: query
          name: groupId
          required: true
          schema:
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              format: uuid
              items:
                type: string
              type: array
        description: Array of resold product (UUID) IDs. Zero to 256 elements allowed.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/retailerapi.FootprintItem'
                type: array
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Forbidden
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Internal Server Error
      summary: Get FLAG emissions breakdown of many products.
      tags:
        - Footprints
  /resold-products/flag-updates:
    get:
      description: >-
        List IDs of products that have updated footprint information.

        Fetch each product to see the relevant information.

        Use updated_at of the last item in the list to progress the pagination.

        The since parameter is inclusive, so pages may repeat the last item of
        the previous page.

        Avoid a since parameter too close to wall time, since then in flight
        updates may be missed.
      parameters:
        - description: Required groupId.
          in: query
          name: groupId
          required: true
          schema:
            format: uuid
            type: string
        - description: >-
            List updates since this RFC3339 timestamp (with sub-second
            resolution). Functions as pagination offset.
          example: '`2018-03-20T09:12:28.999999999Z`'
          in: query
          name: since
          schema:
            type: string
        - description: Pagination limit (1-256), default 100.
          in: query
          name: limit
          schema:
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/retailerapi.Update'
                type: array
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Forbidden
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Internal Server Error
      summary: List IDs of products that have updated footprint information.
      tags:
        - Footprints
  /resold-products/footprint-baseline-updates:
    get:
      description: >-
        List IDs of products that have updated footprint baseline information.

        Fetch each product to see the relevant information.

        Use updated_at of the last item in the list to progress the pagination.

        The since parameter is inclusive, so pages may repeat the last item of
        the previous page.

        Avoid a since parameter too close to wall time, since then in flight
        updates may be missed.
      parameters:
        - description: Required groupId.
          in: query
          name: groupId
          required: true
          schema:
            format: uuid
            type: string
        - description: >-
            List updates since this RFC3339 timestamp (with sub-second
            resolution). Functions as pagination offset.
          example: '`2018-03-20T09:12:28.999999999Z`'
          in: query
          name: since
          schema:
            type: string
        - description: Pagination limit (1-256), default 100.
          in: query
          name: limit
          schema:
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/retailerapi.Update'
                type: array
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Forbidden
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Internal Server Error
      summary: List IDs of products with updated footprint baseline information.
      tags:
        - Footprints
  /resold-products/footprint-baselines:
    post:
      description: Get forest, land and agriculture emissions baselines of many products.
      parameters:
        - description: Required groupId.
          in: query
          name: groupId
          required: true
          schema:
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              format: uuid
              items:
                type: string
              type: array
        description: Array of resold product (UUID) IDs. Zero to 256 elements allowed.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/retailerapi.FootprintItem'
                type: array
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Forbidden
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Internal Server Error
      summary: Get FLAG emissions baselines of many products.
      tags:
        - Footprints
  /resold-products/updates:
    get:
      description: >-
        List IDs of products that have updated information.

        Fetch each product to see the relevant information.

        Use updated_at of the last item in the list to progress the pagination.

        The since parameter is inclusive, so pages may repeat the last item of
        the previous page.

        Avoid a since parameter too close to wall time, since then in flight
        updates may be missed.
      parameters:
        - description: Required groupId.
          in: query
          name: groupId
          required: true
          schema:
            format: uuid
            type: string
        - description: >-
            List updates since this RFC3339 timestamp (with sub-second
            resolution). Functions as pagination offset.
          example: '`2018-03-20T09:12:28.999999999Z`'
          in: query
          name: since
          schema:
            type: string
        - description: Pagination limit (1-256), default 100.
          in: query
          name: limit
          schema:
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/retailerapi.Update'
                type: array
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Forbidden
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Internal Server Error
      summary: List IDs of products that have updated information.
      tags:
        - Products
  /resold-products/{id}:
    delete:
      description: >-
        Delete a resold product.


        This will delete the product and any not yet accepted links to
        suppliers.

        If a supplier has been connected they will keep their variant of the
        product

        but it will no longer be visible from this API.
      parameters:
        - description: Product (UUID) ID.
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '201':
          content:
            application/json:
              schema:
                type: object
          description: Created
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Internal Server Error
      summary: Delete a resold product.
      tags:
        - Products
    get:
      description: Get a resold product.
      parameters:
        - description: Product (UUID) ID.
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.ResoldProduct'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Internal Server Error
      summary: Get a resold product.
      tags:
        - Products
    put:
      description: Replace all fields on resold product.
      parameters:
        - description: Product (UUID) ID.
          in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/retailerapi.UpdateResoldProductRequest'
        description: Request body for updating a product
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.ResoldProduct'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Forbidden
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Internal Server Error
      summary: Update a resold product.
      tags:
        - Products
  /resold-products/{id}/flag:
    get:
      description: >-
        Get forest, land and agriculture emissions breakdown of a specific
        product.
      parameters:
        - description: Resold product ID.
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.FlagFootprint'
          description: OK
        '204':
          description: No Content
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Internal Server Error
      summary: Get FLAG emissions breakdown of a specific product.
      tags:
        - Footprints
  /resold-products/{id}/footprint-baseline:
    get:
      description: >-
        Get forest, land and agriculture emissions breakdown of a specific
        product.

        The returned footprint baseline is modeled using only secondary data.

        This is not a secondary contribution to the primary footprint.
      parameters:
        - description: Resold product ID.
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.FlagFootprint'
          description: OK
        '204':
          description: No Content
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Internal Server Error
      summary: Get footprint baseline of a specific product.
      tags:
        - Footprints
  /resold-products/{id}/supplier-engagement:
    get:
      description: >-
        The information about current supplier of the product.


        See `GET /suppliers/{id}/linked-products` for an explanation of the
        status.

        Responds status 204 if there is no current supplier of this product.
      parameters:
        - description: Product (UUID) ID.
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.SupplierLinkedProduct'
          description: OK
        '204':
          description: No Content
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Forbidden
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Internal Server Error
      summary: Get supplier engagement information
      tags:
        - Products
  /resold-products/{id}/suppliers:
    get:
      description: >-
        Retrieves all supplier periods for a product and their corresponding
        time ranges.

        The returned `id` on each period should be included in PUT requests

        to preserve existing periods and their internal linkage.
      parameters:
        - description: Resold product ID.
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/retailerapi.SupplierPeriodResponse'
                type: array
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Invalid request (e.g. bad UUID)
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Unauthorized access
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Product not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Internal server error
      summary: Get product suppliers.
      tags:
        - Product Suppliers
    put:
      description: >-
        Replace the supplier period history for this product.


        Each supplier entry may include an optional `id` field:

        - With `id`: updates the existing period's dates in place, preserving
        the supplier and internal linkage.

        - Without `id`: creates a new period.

        - Any existing period whose `id` is not present in the request will be
        removed.


        To avoid accidentally deleting periods, first fetch the current list

        via `GET /resold-products/{id}/suppliers` and include the returned `id`
        values

        for any periods you wish to keep.


        Validation rules:

        - All dates must be today or in the past.

        - `validFrom` must not be after `validTo` (same day is allowed).

        - Periods must not overlap in time, not even share a boundary day.


        This endpoint only creates data connections.

        It does not contact or expose any data to suppliers in itself.
      parameters:
        - description: Resold product ID.
          in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/retailerapi.ProductSuppliersRequest'
        description: Supplier periods to set
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/retailerapi.SupplierPeriodResponse'
                type: array
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: >-
            Invalid request (e.g. bad UUID, validation error, bad payload,
            overlapping periods)
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Unauthorized access
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Product not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Internal server error
      summary: Set supplier periods for a product.
      tags:
        - Product Suppliers
  /suppliers:
    get:
      description: List suppliers for one or more groups
      parameters:
        - description: Group ID (UUID) to list suppliers of.
          in: query
          name: groupId
          required: true
          schema:
            type: string
        - description: >-
            Optional filter on suppliers customId. Only relevant if non-empty
            string.
          in: query
          name: customId
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/retailerapi.Supplier'
                type: array
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Bad Request
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Internal Server Error
      summary: List suppliers
      tags:
        - Suppliers
    post:
      description: >-
        Create a new supplier within an organization. Contacts can optionally be
        included.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/retailerapi.CreateSupplierRequest'
        description: Request body for creating a new supplier
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.Supplier'
          description: Created
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Forbidden
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Internal Server Error
      summary: Create a new supplier
      tags:
        - Suppliers
  /suppliers/{supplier-id}:
    delete:
      description: >-
        Delete a supplier by its unique ID. Supplier must not be invited or
        connected.
      parameters:
        - description: Supplier (UUID) ID.
          in: path
          name: supplier-id
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No Content
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Internal Server Error
      summary: Delete a supplier
      tags:
        - Suppliers
    get:
      description: Get a supplier by its unique ID
      parameters:
        - description: Supplier (UUID) ID.
          in: path
          name: supplier-id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.Supplier'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Internal Server Error
      summary: Get a specific supplier
      tags:
        - Suppliers
    put:
      description: >-
        Update an existing supplier by its unique ID. Only provided fields will
        be updated.

        If contacts are provided, they completely replace all existing contacts.
      parameters:
        - description: Supplier (UUID) ID.
          in: path
          name: supplier-id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/retailerapi.UpdateSupplierRequest'
        description: Request body for updating a supplier
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.Supplier'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Internal Server Error
      summary: Update an existing supplier
      tags:
        - Suppliers
  /suppliers/{supplier-id}/linked-products:
    get:
      description: >-
        List active linked products for a supplier.

        Use optional `status` query filter to list only products with a specific
        status.


        Status values:

        - `created`: Product is linked to the supplier but no invite has been
        sent.

        - `sent`: An invite has been sent to the supplier and is awaiting a
        response.

        - `declined`: The supplier declined the invite.

        - `accepted`: The supplier accepted the invite and has ownership of the
        product, but has not yet submitted any data.

        - `active`: The supplier has accepted the invite and submitted
        (published) data at least once.
      parameters:
        - description: Supplier UUID.
          in: path
          name: supplier-id
          required: true
          schema:
            type: string
        - description: Filter by product status.
          in: query
          name: status
          schema:
            items:
              enum:
                - created
                - sent
                - declined
                - accepted
                - active
              type: string
            type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/retailerapi.SupplierLinkedProduct'
                type: array
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retailerapi.errorResponse'
          description: Internal Server Error
      summary: List linked products for supplier
      tags:
        - Suppliers
openapi: 3.1.0
servers:
  - url: https://api.carboncloud.com/v1/retailer
