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

# Create a product

> Create a product in your organisation, optionally with nested prices, contributors, collections, and collateral.

Creates a product scoped to the authenticated organisation. You can include
related records in the same request.

**Required:** `title`

Optional nested arrays on create:

| Key                      | Purpose                                         |
| ------------------------ | ----------------------------------------------- |
| `custom_fields`          | Custom field values (`field_id`, `field_value`) |
| `product_prices`         | Retail/list prices by currency                  |
| `packing_configurations` | Inner/outer/pallet packing rows                 |
| `contributors`           | Contributor and role links                      |
| `product_collections`    | Collection membership                           |
| `collateral`             | Text content, cited content, and awards         |

<Note>
  `product_form_id` is accepted on write but stored on the linked format (when
  `format_id` is set), not on the product row itself. `license_id` must belong
  to the same organisation.
</Note>

## Headers

<ParamField header="x-api-key" type="string" required>
  Organisation API key.
</ParamField>

<ParamField header="Accept-Version" type="string" default="1.0">
  API version. Use `1.0`.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

## Body

<ParamField body="title" type="string" required>
  Product title.
</ParamField>

<ParamField body="subtitle" type="string">
  Subtitle.
</ParamField>

<ParamField body="isbn13" type="string">
  ISBN-13.
</ParamField>

<ParamField body="isbn10" type="string">
  ISBN-10.
</ParamField>

<ParamField body="page_count" type="integer">
  Positive page count.
</ParamField>

<ParamField body="publication_date" type="string">
  Publication date string (nullable).
</ParamField>

<ParamField body="format_id" type="string">
  Format UUID.
</ParamField>

<ParamField body="title_id" type="string">
  Parent title UUID (nullable).
</ParamField>

<ParamField body="publishing_status_id" type="string">
  Publishing status UUID (ONIX List 64). Pass `null` to clear on update.
</ParamField>

<ParamField body="product_availability_id" type="string">
  Product availability UUID (ONIX List 65).
</ParamField>

<ParamField body="lifecycle_status_id" type="string">
  Lifecycle status UUID.
</ParamField>

<ParamField body="license_id" type="string">
  Organisation license UUID. Must belong to the authenticated organisation.
  Omit to create without a license.
</ParamField>

<ParamField body="season_id" type="string">
  Season UUID.
</ParamField>

<ParamField body="publisher_id" type="string">
  Publisher UUID.
</ParamField>

<ParamField body="division_id" type="string">
  Division UUID.
</ParamField>

<ParamField body="imprint_id" type="string">
  Imprint UUID.
</ParamField>

<ParamField body="series_id" type="string">
  Series collection UUID. Must be one of the product's attached collections when
  set.
</ParamField>

<ParamField body="product_form_id" type="string">
  Product form UUID. Synced to the linked format when `format_id` is present.
</ParamField>

<ParamField body="product_type" type="string">
  One of `normal`, `kit`, `kit_part`, `indent`, `charge`, `special`,
  `trade_only`.
</ParamField>

<ParamField body="cover_image_url" type="string">
  Absolute URL for the cover image.
</ParamField>

<ParamField body="product_prices" type="object[]">
  Nested price rows. Each entry requires `currency_code`. Optional fields
  include `retail_price`, `retail_price_inc_tax`, `list_price`, `tax_rate`,
  `is_default`, `valid_from`, and `valid_to` (`YYYY-MM-DD`).
</ParamField>

<ParamField body="packing_configurations" type="object[]">
  Nested packing rows. Each entry requires `unit_of_measure`: `inner`, `outer`,
  or `pallet`.
</ParamField>

<ParamField body="contributors" type="object[]">
  Nested contributor links with `contributor_id` and `contributor_role_id`.
</ParamField>

<ParamField body="product_collections" type="object[]">
  Nested collection membership with `collection_id`.
</ParamField>

<ParamField body="collateral" type="object[]">
  Nested collateral items. Discriminated by `collateral_type`: `text_content`,
  `cited_content`, or `award`.
</ParamField>

<ParamField body="custom_fields" type="object[]">
  Custom field values. Each entry has `field_id` and `field_value`
  (string, number, boolean, or null). Duplicate `field_id` values are rejected.
</ParamField>

## Response

Returns **201** with the enriched product in `data`.

<ResponseField name="success" type="boolean" required>
  `true` when the product is created.
</ResponseField>

<ResponseField name="data" type="object" required>
  Created product, including enriched display fields such as `license_name`.
</ResponseField>

## Errors

| Status | When                                                                           |
| ------ | ------------------------------------------------------------------------------ |
| `400`  | Validation failed, invalid `license_id`, or series not in attached collections |
| `401`  | Missing or invalid API key                                                     |
| `500`  | Database or unexpected server error                                            |

<RequestExample>
  ```bash theme={null}
  curl -X POST "https://vzguoukmiwxvqdnabfma.supabase.co/functions/v1/api/products" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Accept-Version: 1.0" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "New Book Title",
      "subtitle": "An Amazing Story",
      "isbn13": "9781234567890",
      "publishing_status_id": "status-uuid",
      "format_id": "format-uuid",
      "license_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "page_count": 250,
      "publication_date": "2024-12-01"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "id": "newly-created-uuid",
      "title": "New Book Title",
      "publishing_status_id": "status-uuid",
      "license_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "license_name": "Example License",
      "license_badge_colour": "#7C3AED",
      "organization_id": "your-org-id",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  }
  ```
</ResponseExample>