Add an image

This guide uploads an image as a media and attaches it to a product and/or one of its variants, so it shows up wherever they are displayed.

Media are a two-step thing: you upload the file once to get a media IRI, then reference that IRI from the resources that use it. Both products and variants expose a medias list, so the same uploaded image can sit on the product, on specific variants, or both.

Prerequisites

You need a product with a variant on an existing instance. If you don’t have one, follow Create your first product first - a new product comes with a single default variant.

As in that guide, the commands below use:

• the organization id - shown as <org_id>
• the instance handle (the tenant) - shown as <tenant>
• your product and variant ids - shown as {productId} and {variantId}

Before you start

You need an OAuth 2.0 bearer token for a partner account. Sign in below: your token is dropped into every command on this page, and you can pick your organization and instance to fill <org_id> and <tenant> too. See Authentication for more.

Sign in to drop your real token into the commands below.

Enter tenant & organization ID manually

Organization ID Tenant

Steps

1. Upload the image.

   Media are created with a multipart/form-data upload, not JSON: send the binary in a file field. Capture the @id from the response - that’s the media IRI you’ll attach.

   curl -X POST 'https://<tenant>.product-management.flowkiwi.net/rest/api/medias' \
     -H 'Authorization: Bearer {token}' \
     -H 'X-Flowkiwi-Organization-Id: <org_id>' \
     -F 'file=@/path/to/tshirt-red-front.jpg'

   The response describes the stored media - its contentUrl, derived type, and (for images) its dimensions:

   {
     "@id": "/rest/api/medias/01234567-89ab-cdef-0123-456789abcdef",
     "contentUrl": "/uploads/medias/tshirt-red-front.jpg",
     "mimeType": "image/jpeg",
     "type": "image",
     "dimensions": {
       "width": 1200,
       "height": 1200
     }
   }

2. Attach it.

   Patch the medias list of the resource you want the image on. The list is ordered, so the first entry is the primary image. Attach it to a variant, to the product, or to both - the same media IRI can be reused.

   To a variant

   curl -X PATCH 'https://<tenant>.product-management.flowkiwi.net/rest/api/products/{productId}/variants/{variantId}' \
     -H 'Authorization: Bearer {token}' \
     -H 'X-Flowkiwi-Organization-Id: <org_id>' \
     -H 'Content-Type: application/merge-patch+json' \
     -d '{
       "medias": [
         "/rest/api/medias/01234567-89ab-cdef-0123-456789abcdef"
       ]
     }'

   To a product

   curl -X PATCH 'https://<tenant>.product-management.flowkiwi.net/rest/api/products/{productId}' \
     -H 'Authorization: Bearer {token}' \
     -H 'X-Flowkiwi-Organization-Id: <org_id>' \
     -H 'Content-Type: application/merge-patch+json' \
     -d '{
       "medias": [
         "/rest/api/medias/01234567-89ab-cdef-0123-456789abcdef"
       ]
     }'

   Images only

   Only media of type image can be attached to a product or a variant. Referencing a video or a document in medias is rejected with 422 Unprocessable Entity.

3. Verify.

   Read the resource back - its medias now includes the image you attached. For a variant:

   curl 'https://<tenant>.product-management.flowkiwi.net/rest/api/products/{productId}/variants/{variantId}' \
     -H 'Authorization: Bearer {token}' \
     -H 'X-Flowkiwi-Organization-Id: <org_id>' \
     -H 'Accept: application/ld+json'

Next steps

• Order several images. Send more than one IRI in medias - the array order is the display order, first is primary.
• Reuse a media. The same uploaded media can be referenced from the product and several variants; you don’t re-upload it.
• Product vs variant. Put shared shots on the product and variant-specific shots (a colour, say) on each variant.