Products and images

A shoot starts from a photo of a product. This page covers putting your products and their photos into Shootika and keeping them in step with your own catalog.

Create a product

curl https://api.shootika.com/v1/products \
  -H "Authorization: Bearer $SHOOTIKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Ribbed crew sweater",
    "garment_category": "tops",
    "external_id": "SKU-1042",
    "image_urls": ["https://example.com/photos/sweater-flat.jpg"]
  }'

Field	Required	What it is
title	yes	Up to 500 characters.
garment_category	no	tops, bottoms or one-pieces.
external_id	no	Your own id for the product, up to 255 characters. Unique among your products.
image_urls	no	Up to 10 public http or https addresses of photos to fetch.

The answer is 201 with the product. When you sent image_urls, it also carries images_failed.

Check images_failed

The product is created even if some photos cannot be fetched. Each one that failed is listed in images_failed with its url, a code and a message. The code is one of invalid_url, unreachable_url, not_an_image, too_large or upload_failed. Check this list before you start a shoot with the product’s photos.

Link products to your store’s ids

Put your store’s own product id in external_id. Then find the Shootika product from your id:

curl "https://api.shootika.com/v1/products?external_id=SKU-1042" \
  -H "Authorization: Bearer $SHOOTIKA_API_KEY"

The list is empty, not an error, when nothing matches. Creating or changing a product with an external_id another product already uses answers 409 external_id_taken.

GET /v1/products without a filter lists all your products, ordered by title. Lists are paged: see Paging.

Add a photo

Add one photo to an existing product, from a web address:

curl https://api.shootika.com/v1/products/$PRODUCT_ID/images \
  -H "Authorization: Bearer $SHOOTIKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/photos/sweater-back.jpg"}'

Or upload a file, as multipart form data in the field image:

curl https://api.shootika.com/v1/products/$PRODUCT_ID/images \
  -H "Authorization: Bearer $SHOOTIKA_API_KEY" \
  -F "image=@sweater-flat.jpg"

The answer is 201 with the image. Use its id as source_image_id when you start a shoot.

What a photo must be

• A PNG, JPEG or WebP image of at most 15 MB.
• To be shot, its short side must be at least 600 pixels. POST /v1/frames refuses a smaller photo with 422 source_image_too_small.

A photo fetched from a web address also:

• must use http or https on the standard port (80 or 443);
• must be on a public address;
• is not followed through redirects, so give the final address;
• may take at most 20 seconds to fetch. All image_urls of one create together may take at most 30 seconds.

When adding one photo fails, the answer names why: 422 with invalid_url (an address that is not allowed), unreachable_url (it could not be fetched), not_an_image, too_large, or validation_error (the body or the file field is missing or wrong). A 503 is upload_failed when the photo could not be stored, or service_busy when Shootika is busy; try again in a moment.

Change or delete a product

PATCH /v1/products/{product_id} changes the title, the garment_category or the external_id. Send only the fields you want to change, and "external_id": null to clear it.

curl -X PATCH https://api.shootika.com/v1/products/$PRODUCT_ID \
  -H "Authorization: Bearer $SHOOTIKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Ribbed crew sweater, sage"}'

DELETE /v1/products/{product_id} removes the product and answers 204 with no body. Frames already made from it keep working, and GET /v1/frames?product_id= still lists them by its id.

Remove a photo

DELETE /v1/products/{product_id}/images/{image_id} removes one photo you added and answers 204. It answers 409 image_locked for a photo that a running shoot is using (wait for the shoot to finish) and for a photo that is itself an approved frame (take the approval down instead, see Approval).

GET /v1/products/{product_id} lists a product’s photos. Approved frames are not in that list: they belong to the frame.

Paging

GET /v1/products, GET /v1/scenes and GET /v1/frames are paged. Pass page (from 1) and page_size (default 24, at most 100). Each answer carries page, page_size and total, the number of items in all pages, next to the items.