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

# Create Product

> ### POST /product/

<Note>
  This endpoint requires authentication. Include your Bearer token in the Authorization header.
</Note>

## Description

This endpoint allows the creation of a new product.

**Important Notes:**

* All products are created as production-ready (no draft mode)
* UPC codes are automatically generated if not provided and auto-UPC is enabled
* Artist associations and revenue splits are automatically created
* Assets can be provided or auto-matched based on title and artist

**Deprecated Fields:**

* `catalog`: Use `catalogNumber` instead
* Legacy fields will trigger deprecation warnings in response headers

**Method:**
`POST`

**Request Payload:**

| Field                      | Type             | Description                             |
| -------------------------- | ---------------- | --------------------------------------- |
| upc                        | string           | The UPC of the product                  |
| catalog (or catalogNumber) | string           | The catalog of the product              |
| title                      | string           | The title of the product                |
| displayArtist              | string           | The display artist of the product       |
| type                       | string           | The type of the product                 |
| externalId                 | string           | The external ID of the product          |
| releaseDate                | string           | The release date of the product         |
| takedownDate               | string           | The takedown date of the product        |
| mainGenre                  | array of strings | The main genre of the product           |
| subGenre                   | array of strings | The sub-genre of the product            |
| status                     | string           | The status of the product               |
| distribution               | string           | The distribution of the product         |
| contributors               | string           | The contributors of the product         |
| metadata                   | object           | Additional metadata for the product     |
| version                    | string           | The version of the product              |
| explicit                   | boolean          | The explicit content of the product     |
| id                         | string           | The unique identifier of the product    |
| artists                    | array of strings | The artists associated with the product |
| assets                     | array of objects | The assets associated with the product  |

## Code Examples

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch('https://api.royalti.io/product/', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      "ref": "#/components/schemas/CreateProductRequest"
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
    'https://api.royalti.io/product/',
    headers={
      'Authorization': f'Bearer {token}'
    },
    json={"ref":"#/components/schemas/CreateProductRequest"}
  )

  data = response.json()
  print(data)
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.royalti.io/product/ \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"ref":"#/components/schemas/CreateProductRequest"}'

  ```
</CodeGroup>


## OpenAPI

````yaml post /product/
openapi: 3.0.0
info:
  title: Royalti.io API
  description: "# Royalti API\r\n\r\nThis is the Royalti music royalty management platform API server.\r\n\r\n## Overview\r\n\r\nThe Royalti API provides comprehensive music royalty management services including:\r\n- Music publishing and writer management\r\n- Royalty processing and analytics\r\n- DDEX integration for music industry standards\r\n- File processing and pattern recognition\r\n- Payment processing and distribution\r\n\r\n## Authentication\r\n\r\nThe API uses JWT-based authentication with multiple protection levels:\r\n- Public endpoints for basic operations\r\n- Protected endpoints requiring valid JWT tokens\r\n- Admin endpoints for administrative functions\r\n\r\n## Features\r\n\r\n- Multi-dimensional royalty analytics\r\n- CWR (Collective Works Registration) support\r\n- DDEX integration for music metadata\r\n- Advanced file processing with pattern recognition\r\n- Real-time data processing with queue system"
  version: 2.6.0
  contact:
    name: Royalti.io Support
    email: support@royalti.io
    url: https://royalti.io
  license:
    name: Proprietary
    url: https://royalti.io/terms
servers:
  - url: https://api.royalti.io
    description: Production server
  - url: https://api-dev.royalti.io
    description: Development server
  - url: http://localhost:8084
    description: Local development
security:
  - bearerAuth: []
tags:
  - name: Accounting
    description: Accounting and financial transaction operations
  - name: DDEX
    description: DDEX operations (ERN/MEAD, messages, delivery, providers)
  - name: Label
    description: Label management operations
  - name: Internal Webhooks
    description: Internal system webhooks for royalty processing and downloads
  - name: Payment Webhooks
    description: Payment processor webhook endpoints
  - name: Billing Webhooks
    description: Stripe billing and subscription webhooks
  - name: Infrastructure Webhooks
    description: Cloudflare domain and SSL webhooks
  - name: Distribution Webhooks
    description: Digital distribution platform webhooks (FUGA)
paths:
  /product/:
    post:
      tags:
        - Product
      summary: Create Product
      description: >-
        ### POST /product/


        This endpoint allows the creation of a new product.


        **Important Notes:**

        - All products are created as production-ready (no draft mode)

        - UPC codes are automatically generated if not provided and auto-UPC is
        enabled

        - Artist associations and revenue splits are automatically created

        - Assets can be provided or auto-matched based on title and artist


        **Deprecated Fields:**

        - `catalog`: Use `catalogNumber` instead

        - Legacy fields will trigger deprecation warnings in response headers


        **Method:**

        `POST`


        **Request Payload:**


        | Field | Type | Description |

        | --- | --- | --- |

        | upc | string | The UPC of the product |

        | catalog (or catalogNumber) | string | The catalog of the product |

        | title | string | The title of the product |

        | displayArtist | string | The display artist of the product |

        | type | string | The type of the product |

        | externalId | string | The external ID of the product |

        | releaseDate | string | The release date of the product |

        | takedownDate | string | The takedown date of the product |

        | mainGenre | array of strings | The main genre of the product |

        | subGenre | array of strings | The sub-genre of the product |

        | status | string | The status of the product |

        | distribution | string | The distribution of the product |

        | contributors | string | The contributors of the product |

        | metadata | object | Additional metadata for the product |

        | version | string | The version of the product |

        | explicit | boolean | The explicit content of the product |

        | id | string | The unique identifier of the product |

        | artists | array of strings | The artists associated with the product |

        | assets | array of objects | The assets associated with the product |
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateProductRequest'
            encoding:
              assets:
                contentType: application/json
                explode: false
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProductRequest'
      responses:
        '201':
          description: Product created successfully
          headers:
            X-Deprecation-Warning:
              description: List of deprecated fields used in the request
              schema:
                type: string
              example: >-
                The following fields are deprecated: catalog. Please use their
                new equivalents.
            X-Catalog-Deprecation:
              description: Specific deprecation warning for catalog field
              schema:
                type: string
              example: >-
                The "catalog" field is deprecated. Please use "catalogNumber"
                instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductResponse'
        '400':
          description: Bad request - validation errors or malformed data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_title:
                  summary: Missing required title field
                  value:
                    error: Title is required
                    code: BAD_REQUEST
                invalid_assets:
                  summary: Invalid asset data format
                  value:
                    error: Invalid asset data format
                    code: BAD_REQUEST
        '401':
          description: Unauthorized - invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - insufficient permissions for tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    CreateProductRequest:
      type: object
      required:
        - title
      properties:
        title:
          type: string
          description: Product title
          minLength: 1
          maxLength: 255
          example: Summer Vibes
        id:
          type: string
          description: Custom product identifier
          maxLength: 100
          example: PROD-001
        upc:
          type: string
          description: Universal Product Code (auto-generated if not provided)
          pattern: ^[0-9]{12}$
          example: '123456789012'
        catalogNumber:
          type: string
          description: Catalog number for the product
          maxLength: 100
          example: CAT-2024-001
        catalog:
          type: string
          description: '**DEPRECATED** Use catalogNumber instead'
          deprecated: true
          maxLength: 100
        externalId:
          type: string
          description: External system identifier
          maxLength: 100
          example: EXT-12345
        displayArtist:
          type: string
          description: Display name for the artist(s)
          maxLength: 255
          example: John Doe feat. Jane Smith
        type:
          type: string
          enum:
            - Audio
            - Video
            - Ringtone
          default: Audio
          description: Product type
          example: Audio
        version:
          type: string
          description: Product version or variant
          maxLength: 100
          example: Deluxe Edition
        explicit:
          type: string
          enum:
            - explicit
            - clean
          description: Whether the product contains explicit content
          example: clean
        releaseDate:
          type: string
          format: date
          description: Product release date
          example: '2024-06-15'
        takedownDate:
          type: string
          format: date
          description: Date when product should be taken down
          example: '2024-12-31'
        mainGenre:
          type: string
          description: Primary genre
          maxLength: 100
          example: Pop
        subGenre:
          type: string
          description: Secondary genre
          maxLength: 100
          example: Dance Pop
        status:
          type: string
          enum:
            - Live
            - Taken Down
            - Scheduled
            - Pending
            - Error
          description: Product status
          default: Pending
        distribution:
          type: object
          description: Distribution settings and preferences
          additionalProperties: true
        contributors:
          type: array
          description: List of contributors and their roles
          items:
            type: object
            properties:
              name:
                type: string
                maxLength: 255
              role:
                type: string
                maxLength: 100
              share:
                type: number
                minimum: 0
                maximum: 100
            required:
              - name
              - role
        metadata:
          type: object
          description: Additional product metadata
          additionalProperties: true
        chartHistory:
          type: array
          items:
            type: object
            properties:
              chart:
                type: string
                description: Chart name (e.g., Billboard Hot 100)
              position:
                type: integer
                description: Chart position
              date:
                type: string
                format: date
                description: Date of chart position
          description: Historical chart positions for the product
          example:
            - chart: Billboard Hot 100
              position: 10
              date: '2024-01-15'
        totalTracks:
          type: integer
          minimum: 1
          description: Total number of tracks on the product
          example: 12
        totalDiscs:
          type: integer
          minimum: 1
          description: Total number of discs in the product
          example: 1
        packageType:
          type: string
          description: Physical/digital package type
          example: Digital Album
        edition:
          type: string
          description: Edition designation (e.g., Deluxe, Remastered, Anniversary)
          example: Deluxe Edition
        reissue:
          type: boolean
          description: Whether this product is a reissue of a previous release
          default: false
          example: false
        originalReleaseDate:
          type: string
          format: date
          description: Original release date (for reissues)
          example: '2020-06-15'
        recordingLocation:
          type: string
          maxLength: 255
          description: Recording studio/location
          example: Abbey Road Studios, London
        masteringLocation:
          type: string
          maxLength: 255
          description: Mastering studio/location
          example: Sterling Sound, New York
        producer:
          type: array
          items:
            type: string
          description: Producer name(s)
          example:
            - Max Martin
            - Shellback
        engineer:
          type: array
          items:
            type: string
          description: Engineer name(s)
          example:
            - John Smith
            - Jane Doe
        sequenceNumber:
          type: integer
          description: Sequence number in a series or discography
          example: 5
        parentReleaseId:
          type: string
          format: uuid
          description: Parent release ID for variants or deluxe editions
          example: 550e8400-e29b-41d4-a716-446655440000
        language:
          type: string
          maxLength: 10
          description: Primary language code (ISO 639-1)
          example: en
        c_line_year:
          type: integer
          minimum: 1900
          maximum: 2100
          description: Copyright line year (©)
          example: 2024
        p_line_year:
          type: integer
          minimum: 1900
          maximum: 2100
          description: Phonogram line year (℗)
          example: 2024
        artists:
          type: array
          description: Associated artists with their roles
          items:
            oneOf:
              - type: string
                description: Artist ID (defaults to primary)
              - type: object
                properties:
                  id:
                    type: string
                    description: Artist identifier
                  type:
                    type: string
                    enum:
                      - primary
                      - featuring
                    default: primary
                    description: Artist role type
                required:
                  - id
          example:
            - id: artist-123
              type: primary
            - id: artist-456
              type: featuring
        assets:
          type: array
          description: Associated media assets (tracks, videos)
          items:
            oneOf:
              - type: string
                description: JSON string representation of asset
              - type: object
                properties:
                  asset:
                    type: string
                    description: Asset identifier
                  number:
                    type: integer
                    minimum: 1
                    description: Track/asset number
                required:
                  - asset
          example:
            - asset: asset-789
              number: 1
            - asset: asset-790
              number: 2
    ProductResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique product identifier
          example: prod_123456
        title:
          type: string
          description: Product title
          example: Summer Vibes
        displayArtist:
          type: string
          description: Display artist name
          example: John Doe feat. Jane Smith
        upc:
          type: string
          description: Universal Product Code
          example: '123456789012'
        catalogNumber:
          type: string
          description: Catalog number
          example: CAT-2024-001
        type:
          type: string
          enum:
            - Audio
            - Video
            - Ringtone
          example: Audio
        format:
          type: string
          enum:
            - Single
            - EP
            - Album
            - LP
          description: Product format (auto-determined by asset count)
          example: Single
        explicit:
          type: string
          enum:
            - explicit
            - clean
          example: clean
        releaseDate:
          type: string
          format: date
          example: '2024-06-15'
        takedownDate:
          type: string
          format: date
          nullable: true
          example: null
        mainGenre:
          type: string
          example: Pop
        subGenre:
          type: string
          example: Dance Pop
        status:
          type: string
          example: active
        version:
          type: string
          example: Deluxe Edition
        label:
          type: string
          description: Record label (from artist defaults)
          example: Indie Records
        copyright:
          type: string
          description: Copyright information (from artist defaults)
          example: 2024 John Doe
        publisher:
          type: string
          description: Publisher information (from artist defaults)
          example: Music Publishing Co.
        media:
          type: array
          description: Associated media files (artwork, etc.)
          items:
            type: object
            properties:
              id:
                type: string
              url:
                type: string
                format: uri
              type:
                type: string
              mimetype:
                type: string
        artists:
          type: array
          description: Associated artists
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              type:
                type: string
                enum:
                  - primary
                  - featuring
        assets:
          type: array
          description: Associated media assets
          items:
            type: object
            properties:
              id:
                type: string
              title:
                type: string
              isrc:
                type: string
              number:
                type: integer
        distribution:
          type: object
          description: Distribution settings
          additionalProperties: true
        contributors:
          type: array
          description: Contributors list
          items:
            type: object
        metadata:
          type: object
          description: Additional metadata
          additionalProperties: true
        chartHistory:
          type: array
          items:
            type: object
            properties:
              chart:
                type: string
              position:
                type: integer
              date:
                type: string
                format: date
          description: Historical chart positions
        totalTracks:
          type: integer
          description: Total number of tracks on the product
          example: 12
        totalDiscs:
          type: integer
          description: Total number of discs in the product
          example: 1
        packageType:
          type: string
          description: Physical/digital package type
          example: Digital Album
        edition:
          type: string
          description: Edition designation
          example: Deluxe Edition
        reissue:
          type: boolean
          description: Whether this product is a reissue
        originalReleaseDate:
          type: string
          format: date
          description: Original release date (for reissues)
        recordingLocation:
          type: string
          description: Recording studio/location
        masteringLocation:
          type: string
          description: Mastering studio/location
        producer:
          type: array
          items:
            type: string
          description: Producer name(s)
        engineer:
          type: array
          items:
            type: string
          description: Engineer name(s)
        sequenceNumber:
          type: integer
          description: Sequence number in a series
        parentReleaseId:
          type: string
          format: uuid
          description: Parent release ID for variants
        language:
          type: string
          description: Primary language code (ISO 639-1)
          example: en
        c_line_year:
          type: integer
          description: Copyright line year (©)
          example: 2024
        p_line_year:
          type: integer
          description: Phonogram line year (℗)
          example: 2024
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
          example: '2024-08-25T10:30:00Z'
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
          example: '2024-08-25T10:30:00Z'
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: Title is required
        code:
          type: string
          description: Error code
          example: BAD_REQUEST
        details:
          type: object
          description: Additional error details
          additionalProperties: true
      required:
        - error
        - code
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        JWT Authorization header using the Bearer scheme. Format: "Bearer
        {token}"

````