> For the complete documentation index, see [llms.txt](https://docs.pyck.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pyck.cloud/graphql-api/inputs/mutation-inputs.md).

# Mutation Inputs

CreateInput and UpdateInput types for GraphQL mutations

Audience: Programmer

CreateInput and UpdateInput types define the structure of data accepted by create and update mutations in the pyck GraphQL API. These input types ensure type safety and validation when modifying data.

## Naming Patterns

pyck follows consistent naming patterns for mutation inputs:

* **Create**: `Create[Entity]Input` (e.g., `CreateInventoryItemInput`)
* **Update**: `Update[Entity]Input` (e.g., `UpdateInventoryItemInput`)

## CreateInput Types

CreateInput types define required and optional fields when creating new entities.

### Common Structure

```graphql
input CreateEntityInput {
  # Required fields
  name: String!
  type: EntityType!
  
  # Optional fields
  description: String
  data: Map
  
  # Relationships
  parentId: ID
  categoryIds: [ID!]
}
```

### Example: Creating an Inventory Item

```graphql
mutation {
  createInventoryItem(input: {
    name: "Blue Widget",
    sku: "WIDGET-BLUE-001",
    description: "A high-quality blue widget",
    data: {
      color: "blue",
      weight: 150,
      dimensions: {
        length: 10,
        width: 5,
        height: 3
      }
    }
  }) {
    id
    name
    sku
    data
  }
}
```

## UpdateInput Types

UpdateInput types define which fields can be modified when updating existing entities. All fields are typically optional, allowing partial updates.

### Common Structure

```graphql
input UpdateEntityInput {
  # All fields are optional for partial updates
  name: String
  description: String
  status: EntityStatus
  data: Map
  
  # Clear values by setting to null
  description: String  # null clears the description
  
  # Relationship updates
  parentId: ID
  addCategoryIds: [ID!]
  removeCategoryIds: [ID!]
}
```

### Example: Updating an Inventory Item

```graphql
mutation {
  updateInventoryItem(id: "inv_123", input: {
    name: "Blue Widget - Premium",
    data: {
      color: "blue",
      weight: 155,
      premium: true
    }
  }) {
    id
    name
    data
    updatedAt
  }
}
```

## Available Input Types

### Inventory Management

| Create Input                    | Update Input                     | Used For             |
| ------------------------------- | -------------------------------- | -------------------- |
| `CreateInventoryItemInput`      | `UpdateInventoryItemInput`       | Products and items   |
| `CreateRepositoryInput`         | `UpdateRepositoryInput`          | Storage locations    |
| `CreateItemMovementInput`       | `UpdateItemMovementInput`        | Item movements       |
| `CreateRepositoryMovementInput` | `UpdateRepositoryMovementInput`  | Bulk movements       |
| `CreateCollectionMovementInput` | `UpdateInventoryCollectionInput` | Collection movements |
| `CreateInventoryItemSetInput`   | `UpdateInventoryItemSetInput`    | Item groupings       |

### Order Management

| Create Input                      | Update Input                      | Used For          |
| --------------------------------- | --------------------------------- | ----------------- |
| `CreatePickingOrderInput`         | `UpdatePickingOrderInput`         | Picking orders    |
| `CreatePickingOrderItemInput`     | `UpdatePickingOrderItemInput`     | Order line items  |
| `CreateReceivingInboundInput`     | `UpdateReceivingInboundInput`     | Inbound shipments |
| `CreateReceivingInboundItemInput` | `UpdateReceivingInboundItemInput` | Inbound items     |

### Master Data

| Create Input          | Update Input          | Used For                |
| --------------------- | --------------------- | ----------------------- |
| `CreateCustomerInput` | `UpdateCustomerInput` | Customer records        |
| `CreateSupplierInput` | `UpdateSupplierInput` | Supplier records        |
| `CreateDataTypeInput` | `UpdateDataTypeInput` | JSON schema definitions |

### System Configuration

| Create Input                | Update Input                | Used For             |
| --------------------------- | --------------------------- | -------------------- |
| `CreateFileInput`           | `UpdateFileInput`           | File attachments     |
| `CreateWorkflowInput`       | `UpdateWorkflowInput`       | Workflow definitions |
| `CreateWorkflowSignalInput` | `UpdateWorkflowSignalInput` | Workflow triggers    |

## Common Fields

### Data Field

Most entities support a flexible `data` field of type `Map` for custom attributes:

```graphql
input CreateInventoryItemInput {
  # ... standard fields ...
  data: Map  # Stores custom JSON data
}
```

### Timestamps

Create/Update timestamps are automatically managed:

* `createdAt`: Set automatically on creation
* `updatedAt`: Updated automatically on modification

### Relationships

Input types handle relationships through ID references:

```graphql
input CreatePickingOrderItemInput {
  pickingOrderId: ID!    # Parent relationship
  inventoryItemId: ID!   # Item reference
  quantity: Int!
}
```

## Best Practices

### 1. Partial Updates

Only include fields you want to change in update mutations:

```javascript
// Good - Only updates specific fields
const updateInput = {
  name: "New Name",
  status: "ACTIVE"
};

// Avoid - Sending unchanged fields
const updateInput = {
  name: "New Name",
  description: existingDescription,  // Unnecessary
  status: "ACTIVE",
  type: existingType  // Unnecessary
};
```

### 2. Null Handling

Use null to explicitly clear optional fields:

```graphql
mutation {
  updateCustomer(id: "cust_123", input: {
    email: "new@example.com",
    phone: null  # Clears the phone number
  }) {
    id
    email
    phone
  }
}
```

### 3. Data Field Validation

The `data` field is validated against DataType schemas:

```javascript
// First, create a DataType for validation
const dataType = await createDataType({
  name: "ProductAttributes",
  schema: {
    type: "object",
    properties: {
      color: { type: "string" },
      weight: { type: "number", minimum: 0 }
    },
    required: ["color"]
  }
});

// Then use it when creating items
const item = await createInventoryItem({
  name: "Widget",
  sku: "W-001",
  dataTypeId: dataType.id,
  data: {
    color: "blue",  // Required by schema
    weight: 150     // Validated as positive number
  }
});
```

### 4. Batch Operations

For bulk updates, consider using specialized batch mutations when available:

```graphql
mutation {
  updateInventoryItems(
    where: { sku: { hasPrefix: "WIDGET-" } },
    input: { status: "DISCONTINUED" }
  ) {
    count
    items {
      id
      sku
      status
    }
  }
}
```

## JavaScript Example

```javascript
// Create a new inventory item
const createItem = async (itemData) => {
  const result = await client.mutate({
    mutation: gql`
      mutation CreateItem($input: CreateInventoryItemInput!) {
        createInventoryItem(input: $input) {
          id
          name
          sku
          data
          createdAt
        }
      }
    `,
    variables: {
      input: {
        name: itemData.name,
        sku: itemData.sku,
        description: itemData.description,
        data: itemData.customAttributes
      }
    }
  });
  
  return result.data.createInventoryItem;
};

// Update an existing item
const updateItem = async (itemId, updates) => {
  const result = await client.mutate({
    mutation: gql`
      mutation UpdateItem($id: ID!, $input: UpdateInventoryItemInput!) {
        updateInventoryItem(id: $id, input: $input) {
          id
          name
          sku
          data
          updatedAt
        }
      }
    `,
    variables: {
      id: itemId,
      input: updates  // Only include fields to update
    }
  });
  
  return result.data.updateInventoryItem;
};
```

## See Also

* Individual mutation documentation for specific input requirements
* [WhereInput Types](/graphql-api/inputs/where-inputs.md) for filtering in batch operations
* [Data Types](/graphql-api/types/datatype.md) for data field validation
* [Error Handling](/graphql-api/error-handling.md) for validation error responses


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.pyck.cloud/graphql-api/inputs/mutation-inputs.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.