How to attach files to Shopify products with Fileflare’s API

Use Fileflare’s API to attach files by Shopify product ID, target variants when needed, and verify every batch before rollout or handoff.

Beka Rice Avatar

Author

Published

Category

Display

Attaching a file to a product by hand is perfectly reasonable when a store sells 20 digital products. At 200 products, it becomes an afternoon. At 2,000, manual attachment is a substantial project — and every interruption creates another chance to connect the wrong file.

That’s where a Shopify digital downloads API becomes essential. This guide uses Fileflare’s public v1 REST API to manage digital products. Fileflare can attach a delivery asset directly to one or more Shopify product IDs, so an integration doesn’t have to translate every product into a Fileflare UUID first. You still have variant-level control when you need it, but the common product-level job has a much shorter path.

This is the implementation layer beneath our agency and partner playbook: choose the right identifier, run the attachment in safe batches, inspect every miss, and verify the finished catalog before rollout or handoff.

Product media and delivery files solve different jobs

Shopify product media is what a shopper sees while deciding whether to buy: product images, videos, and other media in the storefront gallery. A delivery file is what the customer receives after buying, such as a PDF, ZIP archive, audio pack, template, or course resource.

The Fileflare API workflow in this guide connects a delivery asset to a product. It doesn’t add media to the storefront gallery or change the Shopify product itself. If the mapping is already a simple spreadsheet of SKUs and asset names, bulk attach via CSV may be the shorter route; it’s available on the Growth plan and above. Use the API when another system owns the mapping, when the job needs custom logic and a machine-readable result, or when CSV isn’t on your plan.

That distinction matters in an integration because both jobs may use the word file. A migration script that successfully uploads a preview image to Shopify still hasn’t attached the paid download. Treat the storefront catalog and the delivery catalog as related systems with separate checks.

Choose product-level or variant-level attachment

The attachment endpoint accepts two kinds of product identifiers. The right one depends on whether every variant should receive the asset.

If the asset should…Send…What Fileflare does
Deliver for every variant of a Shopify productThe Shopify product ID in shopify_product_idsResolves the parent product and attaches the asset across its variants
Deliver for one specific variantThe Fileflare product UUID in productsAttaches the asset only to that product or variant row

Imagine a book sold in PDF and EPUB formats. A bonus reading guide that belongs with both formats can attach once at the Shopify product level. The format files themselves should attach to the corresponding PDF and EPUB variant UUIDs, so buyers receive the version they selected.

This is also why you shouldn’t translate every Shopify product ID into a Fileflare UUID by habit. Use the Shopify ID for the broad product-level relationship; resolve a Fileflare UUID only when the catalog mapping calls for variant-level delivery.

Build the attachment job

The safest migration job is a small pipeline with an input, an attachment result, and a reconciliation step. Keep those three records separate. A successful HTTP response proves that Fileflare understood the request, but the response body tells you whether each identifier matched.

Get an API key and keep it server-side

Generate a key in Settings » Developer. Send it as a Bearer token on each request, and treat it like a password: keep it in a server-side secret store, never commit the key to source control, and never expose it in browser code.

Start with one authenticated request before you process the catalog. The Fileflare API quick start covers key generation and headers, while the authentication reference documents response codes and the default rate limit of 60 requests per minute.

Keep the asset UUID with the source record

The attachment route identifies the Fileflare asset in its URL:

POST https://app.digital-downloads.com/api/v1/assets/{asset}/attach

Your job therefore needs the Fileflare asset UUID plus the product identifiers that should receive it. If your workflow uploads the file first, retain the returned asset UUID with the source filename or content record. That gives later steps one durable identifier instead of asking them to match assets by name.

Names are useful to people; IDs are safer for repeatable jobs. Two client catalogs can both contain welcome-guide.pdf, and a filename can change without changing the asset relationship your script intends to create.

Attach by Shopify product ID

For the common product-level case, send numeric Shopify product IDs or product GIDs in shopify_product_ids. Each array accepts one to 100 identifiers.

curl -X POST \
  https://app.digital-downloads.com/api/v1/assets/82664d96-6dfd-4343-96b0-05c46f412a5b/attach \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "shopify_product_ids": [
      8123456789012,
      "gid://shopify/Product/8123456789013"
    ]
  }'

Fileflare echoes the identifiers in the response. Matches appear under attached; identifiers with the right shape but no matching product appear under not_found.

{
  "attached": {
    "products": [],
    "shopify_product_ids": [8123456789012]
  },
  "not_found": {
    "products": [],
    "shopify_product_ids": ["gid://shopify/Product/8123456789013"]
  }
}

Check not_found after every request. The endpoint returns 201 Created for a valid request even if an identifier doesn’t resolve, because the request itself was valid. Treat the per-identifier result — not the status code alone — as the attachment record.

Target one variant when the catalog requires it

When different variants deliver different files, use the products endpoint to find each variant’s Fileflare product UUID. Send those UUIDs in the products array on the same attachment route. The variant delivery guide explains how parent and variant attachments combine on an order.

The input changes, but the operating pattern does not: batch the UUIDs, record attached and not_found, and reconcile the relationships after the write. You can send products, shopify_product_ids, or both in one request, although separate batches can be easier to audit when the two lists come from different source rules.

Make large reruns boring

Catalog automation should be uneventful enough that rerunning it isn’t scary. Four rules do most of that work:

  • Chunk every array at 100 identifiers or fewer. Larger catalogs need multiple calls; preserve a batch number so a failed run can restart at a known point.
  • Stay below the rate limit, 60 requests per minute by default. The ceiling is set per account, so read it from the rate-limit response headers rather than hardcoding 60. A modest delay between calls is cheaper than building a recovery path around avoidable rate-limit responses.
  • Store the input and response for every batch. The product IDs you sent, asset UUID, response status, attached values, and not_found values form a useful handoff record.
  • Retry the same attachment safely. Attaching an asset that is already attached is a no-op. The endpoint is idempotent, so a timeout doesn’t force you to guess whether repeating the batch will create duplicate relationships.

New Shopify products can take a few seconds to appear in Fileflare after the sync event arrives. If a recently created product lands in not_found, first confirm that it is visible in Fileflare and belongs to the store associated with the API key. Then retry that identifier; don’t loosen validation or silently drop the row. The product-sync guide covers the manual checks if a product still hasn’t appeared.

The same discipline helps with input problems. A 422 response means the request needs correction — for example, a missing identifier array, an empty array, more than 100 values, or an identifier in the wrong format. Log that as a failed batch, fix the source data, and rerun it. Don’t let the job continue as though the attachment succeeded.

Reconcile the catalog before handoff

An attachment log tells you what the write endpoint reported. Reconciliation asks the catalog what exists now.

For product-level attachments, list products with both parent rows and attached assets. A page can contain up to 1,000 rows; follow links.next until it is null so the reconciliation covers the whole catalog.

curl "https://app.digital-downloads.com/api/v1/products?include_parents=1&with_assets=1&limit=1000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

The default products response is variant-shaped: products with variants appear as one row per variant. Adding include_parents=1 also returns each parent product row, which is the row a Shopify product ID resolves to during attachment. Adding with_assets=1 includes the assets attached to each row. A product-level attachment is one relationship on that parent row, even though its delivery cascades to every variant; don’t inflate the reconciliation total by counting each inheriting variant as another direct attachment.

Compare the response against the source mapping rather than checking a handful of products by eye. At minimum, verify:

  • Every expected Shopify product ID has the intended asset on its parent row.
  • Every variant-specific Fileflare UUID has the intended asset and no sibling variant received it accidentally.
  • Every not_found value was resolved, intentionally excluded, or documented for the client.
  • The total expected relationships match the reconciled total.

Finish with a manual test order for each attachment mode you used. If the catalog includes both product-level and variant-specific mappings, test one of each; if it uses only product-level attachments, one representative product is enough. The API checks the relationship, but a test order checks the customer outcome. Open the download page and confirm that the buyer receives the right files, not merely that the admin reports an attachment.

Use the pattern where manual setup stops scaling

This workflow is useful whenever the product-to-file mapping already exists somewhere else:

  • A platform migration exports Shopify product IDs alongside source file URLs or filenames.
  • A client launches hundreds of digital products from a prepared catalog spreadsheet.
  • A product information system creates the Shopify catalog and should attach the corresponding delivery asset after sync.
  • An agency repeats the same setup across stores and wants a consistent attachment report for handoff.

The API doesn’t replace discovery or mapping decisions. Someone still has to decide which file belongs to which product and whether variants inherit the same asset. It replaces the repetitive clicking after those decisions are made, while giving you a response you can inspect and reconcile.

Start with one product

Before you point an integration at the full catalog:

  1. Generate an API key and authenticate one request.
  2. Choose one uploaded asset and one Shopify product ID.
  3. Attach the asset, then confirm the identifier appears under attached.
  4. Fetch that product with product_id={SHOPIFY_PRODUCT_ID}&include_parents=1&with_assets=1 and verify the relationship.
  5. Place a test order and check the customer’s files.
  6. Move to batches only after that path works end to end.

The product-attachment API reference has the complete request, response, and validation details. Once one product works, scaling the job is mostly batch size, logging, and patience — a good place for the machinery to be boring.

You can add Fileflare to a Shopify store when you’re ready to build the delivery side of the catalog.