Instafeed is the merchant's Instagram-style gallery on their Shopify storefront. We can blend in your content (anything that works as a visual card with images and/or video), alongside Instagram and their other "posts to show" sources: reviews, UGC, lookbooks, shoppable drops, ambassador posts, or other item types you define.
This page is for any partner who wants that integration: a Shopify app, a headless or multi-channel platform, an agency-owned connector, a review or UGC provider, or any other team with a documented API we can call server-to-server once the merchant has opted in.
How we integrate: Instafeed pulls structured data from your side after authorization. We do not depend on embedding your storefront widget inside our app for this flow. We need predictable JSON (or equivalent), HTTPS media URLs our infrastructure can fetch, and clear rules when URLs or tokens expire.
Shopify note: Instafeed always resolves to a single merchant shop on Shopify. You do not need to be on the Shopify App Store to meet this spec, but list responses and identifiers must map cleanly to that shop (see section 1). For product-scoped listing and Shopify product identifiers, see sections 3 and 5.
1. Tenancy
- Every resource must be clearly scoped to one Shopify shop per Instafeed installation (for example
*.myshopify.com, Shopify shop GID, or another stable identifier you and we both derive for that merchant). - List and detail responses must only include items that belong to that shop, with no cross-merchant leakage.
2. Authentication
- Provide a documented way for Instafeed's servers to call your API after the merchant has authorized the integration (OAuth 2.0 client credentials, long-lived shop-scoped tokens, signed requests with a shared secret, etc.).
- Document how to obtain, refresh, and revoke credentials, expected token lifetime, and, if the merchant connects through your OAuth or linking UI, how Instafeed receives or exchanges the scoped secret or token we will use at runtime.
3. Listing items for the gallery
- Expose an endpoint (or GraphQL field) to list items the merchant is allowed to reuse in a third-party marketing gallery on their storefront, not only inside your own product, widget, or hosted experience.
- Support pagination (cursor-based preferred; offset/limit is acceptable) so we can sync in chunks.
- Default or explicit sort by newest first is sufficient unless you document otherwise.
- Optional filters we can rely on if you support them, for example:
- published / approved / moderation-safe subset only
- rows that include at least one image or video when we restrict to visual content
- filter by Shopify product when the item is product-scoped (catalog alignment on the storefront)
4. Required fields per item
Each gallery-ready item should include at least one image or video (see Media), plus the following.
| Field | Requirement |
|---|---|
| Stable ID | A string (or integer) that uniquely identifies this item for the lifetime of the shop. It must never be reassigned to a different row. |
| Created time (and updated time if available) | Used for ordering and cache freshness. ISO 8601 in UTC is ideal. |
| Body or caption text | Plain text (or HTML if documented; we may normalize to plain text). May be empty for media-first items; state that explicitly in your docs if allowed. |
| Attribution / author display | A label safe to show on the storefront (customer name, handle, "Verified buyer", brand, etc.). Document what you return and any truncation or pseudonymization rules. |
| Public URL | Where a shopper can open this item or its context (product page, post detail, campaign URL). Prefer no mandatory login for storefront visitors. |
| Media | For each image or video: HTTPS URLs callable from our servers. For video, include a poster / thumbnail URL. If you use time-limited signed URLs, document TTL and how to refresh without breaking the gallery. |
5. Recommended fields
Not strictly required for a first integration, but they improve merchant experience and future Instafeed features.
| Field | Purpose |
|---|---|
| Star or score rating | When applicable (e.g. reviews): numeric rating and scale (for example 1 to 5). |
| Title or headline | Short title when your model includes one. |
| Shopify product reference | When the item is tied to a product: Shopify product GID (gid://shopify/Product/...) and/or numeric product id plus shop scope, for feeds, tagging, or product-page context. |
| Locale / language | If the merchant or your content is multilingual. |
| Status flags | For example published, hidden, featured, so we ingest only rows meant for public display. |
6. Media and hosting
- Media URLs must use HTTPS.
- State whether hotlinking from non-browser server clients is allowed, and any CDN, referrer, or signed-URL constraints so assets do not disappear after a short TTL without a documented refresh path.
- If video requires a specific container or protocol (for example HLS), document it and whether a single MP4 progressive URL is also available.
7. Deletions, edits, and freshness
- When an item is deleted or redacted, it must disappear from list responses (or be returned with an explicit state we can map to remove from gallery).
- If you offer webhooks (create, update, delete), list event types and the identifiers in each payload. If not, confirm polling is supported and suggest reasonable intervals.
8. Rate limits and reliability
- Document rate limits (per shop, per token, or global) and behavior when limited (for example HTTP
429,Retry-After, error body). - Provide sandbox, staging tenant, or test credentials and a technical contact or changelog URL for breaking API changes.
9. Rights to display outside your product
The merchant must have the right to show the copy and customer- or brand-supplied media for that item inside Instafeed's gallery on their Shopify storefront, not only inside your default UI, embed, or off-store channel. Your terms or help center should confirm that reuse when the merchant enables the integration, and deletion or withdrawal in your system must match what the API returns (see section 7).
10. Contact
Questions, clarifications, or pilot integrations: support@minttstudio.com.