# Create an inventory item Adds an item to the account's catalogue and returns it. **The created item comes back with only the fields that were set on it**, not the full record that reading it returns - the columns left to their defaults are absent rather than present and defaulted. Read the item back if you need its complete state. name and type are required. type decides which of the other fields apply: a `distributable` item is physical and tracked per person, `virtual` is issued without stock, and `certificate` issues a certificate when allocated. **Four fields are gated by a companion switch** and are rejected without it - quantity needs has_quantity, ttl needs has_expiry, reward_point_cost needs is_redeemable, and serial_assignment_mode needs has_serial. Sending the value without the switch returns a 422 naming the field. Leaving a switch off resets its field rather than storing what was sent, so quantity comes back 0, ttl null, reward_point_cost 0 and serial_assignment_mode null. **To attach an uploaded image**, set is_image and send the request as `multipart/form-data` with the image in the file_path part; the other fields go in the same form. To point at an image you already host, set is_image and send file_path as a URL in an ordinary JSON body. Either way the resolved image is stored on icon and file_path itself is not kept. Without is_image, send an icon class name on icon instead. The account's own attribute configuration also applies, so a create may accept or require fields beyond those listed here. Endpoint: POST /api/v2/inventory/item Version: 2.0.0 Security: default ## Header parameters: - `Rosterfy-Platform` (string) ## Request fields (application/json): - `name` (string, required) The name of the item, as it appears to administrators and to volunteers choosing a reward. Required, and limited to 255 characters. - `type` (string, required) What kind of item this is. `distributable` is a physical item handed out and tracked per person, `virtual` is issued without stock, and `certificate` issues a certificate on allocation. Required, and it determines which of the other fields apply. - `external_id` (string) Your own reference for the item - a SKU or catalogue code. Not used by Rosterfy for anything; it exists so you can match an item back to your own system. - `parent_id` (integer) The ID of the item this one is a variant of. Set only on variant items. - `certificate_id` (integer) The ID of the certificate template to issue when the item is allocated. Applies to items of type `certificate`. - `category_id` (integer) The ID of the category the item is filed under. - `icon` (string) The icon shown against the item. Either an icon class name, or an image URL when is_image is set. See file_path for uploading an image instead. - `is_image` (boolean) Whether the item is shown with an uploaded image rather than an icon. When set, supply the image through file_path. - `file_path` (string) The image to show against the item, used only when is_image is set. Send either a URL to an existing image, or the image itself as a file - see the endpoint description for how to send a file. The value is not stored as sent; it is resolved and the result is stored on icon. - `has_quantity` (boolean) Whether stock is tracked for this item. When set, quantity must be given and must be greater than 0. When not set, quantity is reset to 0. - `quantity` (integer) How many of the item are in stock. Only accepted when has_quantity is set, and must be greater than 0. - `max_per_user` (integer) The most of this item any one person may hold at once. 0 means no limit. Cannot be negative. An allocation that would exceed it is rejected unless the request overrides the limit. - `has_serial` (boolean) Whether individual units carry serial numbers. When set, serial_assignment_mode must be given. When not set, serial_assignment_mode is reset to null. - `serial_assignment_mode` (string) How a serial is chosen when the item is allocated: `auto` takes the next free serial, `manual` requires the serial to be named on the allocation. Only accepted when has_serial is set. - `is_redeemable` (boolean) Whether volunteers can redeem this item with reward points. When set, reward_point_cost must be given. When not set, reward_point_cost is reset to 0. - `reward_point_cost` (integer) How many reward points redeeming the item costs. Only accepted when is_redeemable is set, and must be greater than 0. - `has_expiry` (boolean) Whether an allocation of this item expires. When set, ttl must be given. When not set, ttl is reset to null. Not stored on the item itself - it is the switch that decides whether ttl is accepted. - `ttl` (integer) How long an allocation of this item stays valid, in seconds. Used to work out the expiry date when the item is given to someone. Only accepted when has_expiry is set; when has_expiry is not set it is reset to null. - `budget_cost` (number) The unit cost of the item, used in budget reporting. Two decimal places. - `publish` (boolean) Whether the item is live. An unpublished item cannot be collected and is not offered to volunteers. - `is_archived` (boolean) Whether the item is archived. An archived item is kept for reporting but is no longer offered. - `is_inheritable` (boolean) Whether subaccounts of this account can use the item. - `is_distributable_at_checkin_checkout` (boolean) Whether the item can be handed out as part of checking a volunteer in or out of a shift. - `has_variants` (boolean) Whether this item is a parent that holds variants, such as a garment held in several sizes. - `varied_by_attribute_id` (integer) The ID of the attribute the variants differ by, such as size. Set on a parent item. - `variant_source_id` (integer) The ID of the option, within the varying attribute, that this variant represents. Set on a variant item. - `variation_config` (object) The variant configuration for a parent item. - `sort_order` (integer) Where the item sits in lists. Lower sorts first. - `custom_*` (string) A custom attribute, named by its code - custom_shirt_size, for example. The value follows the attribute's own type, so it may be a string, a number, a boolean or a list. See the custom attributes documentation. ## Response 201 fields (application/json): - `object` (object) - `object.name` (string) - `object.type` (string) - `object.publish` (integer) - `object.icon` (string) - `object.external_id` (string) - `object.has_quantity` (integer) - `object.quantity` (integer) - `object.max_per_user` (integer) - `object.ttl` (string | null) - `object.reward_point_cost` (integer) - `object.serial_assignment_mode` (string | null) - `object.varied_by_attribute_id` (string | null) - `object.updated_at` (string) - `object.created_at` (string) - `object.id` (integer) - `nice` (object) - `nice.created_at` (string) - `nice.created_at__date` (string) - `nice.created_at__time` (string) - `nice.created_at__offset` (string) - `nice.created_at__offset_minutes` (integer) - `nice.created_at__dayofweek` (string) - `nice.external_id` (string) - `nice.has_quantity` (string) - `nice.has_variants` (string) - `nice.is_distributable_at_checkin_checkout` (string) - `nice.name` (string) - `nice.publish` (string) - `nice.type` (string) - `nice.type:value` (string) - `nice.type:array` (string) - `nice.updated_at` (string) - `nice.updated_at__date` (string) - `nice.updated_at__time` (string) - `nice.updated_at__offset` (string) - `nice.updated_at__offset_minutes` (integer) - `nice.updated_at__dayofweek` (string) - `nice.distributed` (integer) - `nice.allocated` (integer) - `nice.available` (integer) - `nice.stock_level` (string) - `nice.manual_serial_required` (boolean) - `nice.account_name_path` (string) - `nice.is_foreign_account` (boolean) - `relations` (object) - `permissions` (object) - `permissions.read` (boolean) - `permissions.update` (boolean) - `permissions.delete` (boolean) - `permissions.redeem` (boolean) - `attributes` (object)