Insert a file attachment

Uploads a file and attaches it to exactly one existing record. On success the file is stored and served back through the url on the response, so a single call both persists the document and makes it downloadable.

Send the request as multipart/form-data with three parts: • file — the binary to upload. Required, and must be non-empty (a zero-byte file is rejected). • name — optional display name; defaults to the uploaded file's original filename when omitted or blank. • exactly one reference id (product_id, order_id, purchase_id, ...) naming the record to attach to. Supply the id — the same id that record's own endpoint returns. Providing no reference id is rejected, and providing more than one is also rejected; exactly one is required.

This endpoint is create-only. There is no public endpoint to update or delete an attachment, and a file cannot be replaced once uploaded — upload a new attachment instead. The response echoes the attachment with all reference-id fields present but only the one you set populated; the rest are null.

The attachment is owned by the company tied to the API key you authenticate with, and the response's uploader is the user that key belongs to. On success you get a 201 with the created attachment wrapped in a data envelope; its url is immediately downloadable.

System effects: the upload counts against your company's storage quota. If it would exceed the remaining quota the call fails with 400 and nothing is stored — free space under Settings (or remove other attachments) and retry. This endpoint does not move inventory and does not push to Metrc or BioTrack; it only associates a document with the referenced record.

Required permission: products_permissions_edit.