> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fynn.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a product group

> Create a new product group for up- and downgrades.

<sup>Required permissions: `product-group:write`</sup>

Create a new product group for up- and downgrades.

## Memberships

Each membership represents a tier in the product group. The `position` field determines the upgrade/downgrade direction:

* Higher position = upgrade target
* Lower position = downgrade target

## Change Timing

* `immediately`: Change takes effect right away, credit is issued based on `creditType`
* `end_of_period`: Change takes effect at end of current billing period, no credit issued

## Credit Types

Only applicable when `changeTiming` is `immediately`:

| Type            | Description                    |
| --------------- | ------------------------------ |
| `pro_rata`      | Credit based on remaining days |
| `full`          | Full period credit             |
| `last_invoiced` | Credit of last invoice amount  |
| `none`          | No credit                      |


## OpenAPI

````yaml post /catalogue/product-groups
openapi: 3.1.0
info:
  title: Fynn API
  description: ''
  termsOfService: https://www.fynn.eu/tos
  contact:
    name: Fynn UG (haftungsbeschränkt)
    url: https://www.fynn.eu
    email: hi@fynn.eu
  license:
    name: Proprietary
    url: https://www.fynn.eu/license
  version: 0.0.0
servers:
  - url: https://coreapi.io
    description: Production
  - url: https://preview.coreapi.io
    description: Sandbox
security:
  - JWT: []
tags: []
paths:
  /catalogue/product-groups:
    parameters: []
    post:
      tags:
        - ProductGroup
      summary: Create a product group
      description: |-
        Create a new product group for up- and downgrades.

        <sup>Required permissions: `product-group:write`</sup>
      operationId: createProductGroup
      requestBody:
        description: The new ProductGroup resource
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductGroup-ProductGroupWrite'
        required: true
      responses:
        '201':
          description: ProductGroup resource created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductGroup-ProductGroupRead'
        '400':
          description: Invalid input
        '422':
          description: Unprocessable entity
      security:
        - JWT:
            - product-group:write
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl -X POST \
             /catalogue/product-groups \
             --header "Content-Type: application/json" \
             --header "Authorization: Bearer <token>" \
             --data '{"name": "SaaS Packages", "enabled": true}'
components:
  schemas:
    ProductGroup-ProductGroupWrite:
      type: object
      description: Create or update a product group
      properties:
        name:
          type: string
          example: SaaS Packages
        enabled:
          example: true
          type: boolean
        forceSameBillingInterval:
          type: boolean
          example: false
        memberships:
          type: array
          items:
            $ref: '#/components/schemas/ProductGroupMembership-ProductGroupWrite'
      required:
        - name
        - enabled
    ProductGroup-ProductGroupRead:
      type: object
      description: A product group for up- and downgrades
      properties:
        id:
          readOnly: true
          example: ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b
          type: string
        name:
          type: string
          example: SaaS Packages
        enabled:
          example: true
          type: boolean
        forceSameBillingInterval:
          type: boolean
          description: >-
            If true, customers can only switch between plans with the same
            billing interval
          example: false
        memberships:
          type: array
          items:
            $ref: '#/components/schemas/ProductGroupMembership-ProductGroupRead'
        createdAt:
          readOnly: true
          type: string
          format: date-time
        updatedAt:
          readOnly: true
          type: string
          format: date-time
    ProductGroupMembership-ProductGroupWrite:
      type: object
      properties:
        product:
          type: string
          description: IRI reference to the product
          example: /api/products/uuid
        pricePlans:
          type: array
          items:
            type: string
          description: IRI references to price plans
          example:
            - /api/plans/uuid
        position:
          type: integer
        label:
          type: string
        upgradeable:
          type: boolean
        downgradeable:
          type: boolean
        changeTiming:
          type: string
          enum:
            - immediately
            - end_of_period
        creditType:
          type: string
          enum:
            - full
            - pro_rata
            - last_invoiced
            - none
      required:
        - product
        - pricePlans
        - position
        - upgradeable
        - downgradeable
        - changeTiming
    ProductGroupMembership-ProductGroupRead:
      type: object
      description: A membership tier within a product group
      properties:
        id:
          readOnly: true
          example: ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b
          type: string
        product: 5eeb70e3-9b5d-43cb-9c01-59bf77dbebc4
        pricePlans:
          type: array
          items: 3ed7b86b-6c57-4f2a-86e1-464fe58b0d0d
        position:
          type: integer
          description: >-
            Position in the group. Lower = cheaper tier, higher = more expensive
            tier
        label:
          type: string
          description: Display label for this membership
          example: Pro
        upgradeable:
          type: boolean
          description: Whether upgrade to higher positions is allowed
        downgradeable:
          type: boolean
          description: Whether downgrade to lower positions is allowed
        changeTiming:
          type: string
          enum:
            - immediately
            - end_of_period
          description: When the change takes effect
        creditType:
          type: string
          enum:
            - full
            - pro_rata
            - last_invoiced
            - none
          description: How unused time is credited (only for immediate changes)
  securitySchemes:
    JWT:
      type: http
      scheme: bearer

````