Fileflare

Get it free

Documentation »

Attaching assets to products

API reference for attaching and detaching assets to Shopify products and variants.

Beka Rice Avatar

Written by

Beka Rice

Last updated

Attach an asset to one or more Shopify products, or detach it from them. You can reference products by their Shopify product ID (numeric or GID) or by their Fileflare product UUID, and the response tells you which identifiers matched.

Requires Bearer authentication with your Fileflare key. Rate-limited to 60 requests per minute.

Endpoint

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

Or detach assets using:

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

Parameters

Path

  • {asset} — UUID of the Fileflare asset

Body (JSON)

Send shopify_product_ids, products, or both. At least one of the two is required, and each array holds 1 to 100 identifiers.

  • shopify_product_ids (array, required without products) — Shopify product IDs, either numeric (8123456789012) or GID (gid://shopify/Product/8123456789012). Bare integers and strings both work.
  • products (array of strings, required without shopify_product_ids) — Fileflare product UUIDs.

Which identifier to use

Use shopify_product_ids for anything driven from the Shopify side, which is most integrations. A Shopify product ID resolves to the parent product in Fileflare, so the asset attaches once and delivers for every variant of that product.

Use products when you need to target a single variant. Each variant has its own Fileflare product UUID, and attaching to that UUID delivers the asset for that variant only. Viewing products returns the UUID for every product and variant row.

Example request

# Attach an asset to two products by Shopify product ID
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"]}'

# Attach to a single variant by Fileflare product UUID
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 '{"products": ["d290f1ee-6c54-4b01-90e6-d701748f0851"]}'

# Detach, using the same identifier options
curl -X POST https://app.digital-downloads.com/api/v1/assets/82664d96-6dfd-4343-96b0-05c46f412a5b/detach \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"shopify_product_ids": [8123456789012]}'

Response — 201 Created

Attach and detach both return 201 Created with a per-identifier result, grouped by the key you sent them under. Identifiers are echoed back exactly as you sent them, so a GID comes back as a GID.

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

Detach returns the same shape with detached in place of attached.

  • attached / detached — identifiers that matched a product on your store and were processed.
  • not_found — identifiers that matched nothing. A deleted product lands here, as does an ID from a different store.

Check not_found after every call. A request where nothing matched still returns 201, because the request itself was valid.

Headers

Include Accept: application/json. Without it, validation errors are returned as a 302 redirect to the dashboard instead of a JSON error body.

Notes

  • Attaching is idempotent, so re-attaching an already-attached asset is a no-op.
  • Detaching an asset that isn’t attached is also a no-op, and the identifier still reports under detached because the product itself resolved.
  • Each array is capped at 100 identifiers per request. Batch larger jobs across multiple calls.
  • Newly synced products can lag by a few seconds after the Shopify webhook fires before they’re resolvable here.

Common errors

  • 404 — the asset doesn’t exist.
  • 422 — neither products nor shopify_product_ids was sent, an array was empty or longer than 100 items, a products entry wasn’t a string, or a shopify_product_ids entry wasn’t a numeric ID or a gid://shopify/Product/… GID.
  • 201 with everything in not_found — the identifiers are valid in shape but match no products on your store. Confirm the products exist in Fileflare (they sync from Shopify automatically) and that you’re using the right store’s API key.

Keep learning

Tagged:

Reading mode