Skip to main content

Managing Files

You can manage files through your Integration, independently of Shape record data exchange.

When a file is uploaded, SyncHive automatically creates a control record for it in a system table named FileStore. This record stores the file's metadata, such as its name, size, and type. To attach the file to a Shape record, add a property on that Shape referencing the FileStore system table, and store the file's fileHiveId in it.

File Identity​

A stored file can be referenced in three ways:

  • Hive ID: SyncHive's own identifier for the stored file, returned when the file is uploaded.
  • External ID: An Integration-scoped identifier you assign. Resubmitting a file using an external ID that already exists in the Hive is treated as an update to that existing file, rather than creating a new one.
  • Alternate ID: An additional unique identifier on the file record..

The external ID and alternate ID cannot be modified with a shape data exchange request, they can only be updated via the file upload API.

Uploading or Replacing a File​

To upload a file, first request a temporary upload URL, then upload the file bytes directly to that URL.

POSThttps://{region}.synchive.com/data-service/v1/hives/{hiveIdentifier}/files/upload-url
Headers
"X-Shopify-Connector-Key": "9XnZr4JmPWTVHuyFBheg",
"limber-connector": "shopify_connector",
"Content-Type": "application/json"
Body
{
  "fileName": "invoice-2001.pdf",
  "contentType": "application/pdf",
  "fileSize": 48213
}
Response
{
  "fileHiveId": "D6BFA0AB71A1",
  "uploadUrl": "https://{region}.synchive.com/files/upload/...",
  "uploadToken": "<upload-token>",
  "expiresOn": "2026-08-27T12:30:00Z"
}

Upload the file bytes directly to uploadUrl. Include the uploadToken in the X-SH-Upload-Token header and send the file size in the Content-Length header.

note

There is an upload limit of 5GB per file.

Replacing a File's Content​

To replace an existing file's content, include one of the following in the request body:

  • fileHiveId: the Hive ID of the file to replace.
  • integrationKey and externalId: replace the file matching that external ID.
  • alternateId: replace the file matching that alternate ID.
Body
{
  "fileName": "invoice-2001.pdf",
  "contentType": "application/pdf",
  "fileSize": 48213,
  "fileHiveId": "D6BFA0AB71A1"
}

The file's fileHiveId does not change. Its metadata, such as file name and file size, is updated automatically to match the new content.

If the request supplies more than one identity and they resolve to different existing files, SyncHive responds with a 409 status.

Assigning External and Alternate IDs on Upload​

You can assign external IDs and an alternate ID when uploading a new file, so later requests can reference it without needing its fileHiveId:

Body
{
  "fileName": "invoice-2001.pdf",
  "contentType": "application/pdf",
  "fileSize": 48213,
  "integrationKey": "shopify_nz_integration",
  "externalId": ["90la078s93498"],
  "alternateId": "INV-2001"
}

If a supplied external ID or alternate ID already exists in the Hive, SyncHive treats the request as an update to that existing file instead of creating a new one.

Downloading a File​

Request a temporary download URL using the file's fileHiveId, externalId, or alternateId, then fetch the file bytes yourself from that URL.

By Hive ID​

GEThttps://{region}.synchive.com/data-service/v1/hives/{hiveIdentifier}/files/download-url?fileHiveId={fileHiveId}

By External ID​

GEThttps://{region}.synchive.com/data-service/v1/hives/{hiveIdentifier}/files/download-url?integrationKey={integrationKey}&externalId={externalId}

By Alternate ID​

GEThttps://{region}.synchive.com/data-service/v1/hives/{hiveIdentifier}/files/download-url?alternateId={alternateId}
Headers
X-Shopify-Connector-Key: 9XnZr4JmPWTVHuyFBheg
limber-connector: shopify_connector
Response
{
  "fileHiveId": "D6BFA0AB71A1",
  "fileName": "invoice-2001.pdf",
  "fileSize": 48213,
  "contentType": "application/pdf",
  "downloadUrl": "https://{region}.synchive.com/files/download/...",
  "expiresOn": "2026-08-27T12:30:00Z"
}

Fetch the file bytes yourself using downloadUrl.

If the file's upload has not finished, SyncHive responds with a 409 status.

Deleting a File​

Delete a file using its fileHiveId, externalId, or alternateId. Deleting a file also deletes its associated metadata. This cannot be undone.

By Hive ID​

DELETEhttps://{region}.synchive.com/data-service/v1/hives/{hiveIdentifier}/files?fileHiveId={fileHiveId}

By External ID​

DELETEhttps://{region}.synchive.com/data-service/v1/hives/{hiveIdentifier}/files?integrationKey={integrationKey}&externalId={externalId}

By Alternate ID​

DELETEhttps://{region}.synchive.com/data-service/v1/hives/{hiveIdentifier}/files?alternateId={alternateId}
Headers
"X-Shopify-Connector-Key": "9XnZr4JmPWTVHuyFBheg",
"limber-connector": "shopify_connector"

Deleting by external ID or alternate ID returns a successful response even if that identity no longer exists in the Hive.

Handling Responses​

Stuck messages are not automatically created when a file exchange encounters an error. Information on creating a stuck message can be found in event logging. The name of the shape of the data exchange should be provided for ops visibility.

Two file code related event codes are available for file exchange related errors: 5010E: File upload failed and 5011E: File download failed.