Add a photo to a product

POST

/products/{product_id}/images

curl --request POST \
  --url https://api.shootika.com/v1/products/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/images \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form image=@file

Adds one photo to a product, either as a file upload (multipart form data, field image) or as a JSON body with a public web address in url. The photo must be a PNG, JPEG or WebP image of at most 15 MB. Use the returned image id as source_image_id when you start a shoot.

A web address must use http or https on the standard port (80 or 443), must be on a public address, is not followed through redirects, and may take at most 20 seconds to fetch. Not available on a Shopify store.

Send an Idempotency-Key to make a retry safe. Only 2xx answers are stored and replayed, for 24 hours. A request still running under the same key answers 409 idempotency_in_progress, and a claim older than 5 minutes is treated as abandoned.

Authorizations

• bearerAuth

Parameters

Path Parameters

product_id

required

string format: uuid

Header Parameters

Idempotency-Key

string

>= 1 characters <= 255 characters

A unique string you choose, 1 to 255 characters, for this request. Repeating the request with the same key and the same body replays the first answer for 24 hours instead of doing the work again. Only 2xx answers are stored. Using the same key with a different request answers 409 idempotency_conflict.

Request Body^required

object

image

required

A PNG, JPEG or WebP file of at most 15 MB.

string format: binary

object

url

required

A public http or https address of a PNG, JPEG or WebP image.

string

<= 2048 characters

Example^generated

{
  "url": "example"
}

Responses

201

The photo was added.

Media typeapplication/json

object

image

required

object

id

required

string format: uuid

url

required

string format: uri

width

required

integer | null

height

required

integer | null

Example^generated

{
  "image": {
    "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "url": "https://example.com",
    "width": 1,
    "height": 1
  }
}

400

bad_request: the request could not be read, for example a multipart body with no boundary.

Media typeapplication/json

object

error

required

What went wrong. Read code in your software; message is for people.

object

code

required

string

Allowed values: api_not_enabled approval_unavailable attach_conflict bad_request catalog_managed_by_shopify conflict daily_cap_reached external_id_taken family_unsupported forbidden idempotency_conflict idempotency_in_progress image_locked internal_error invalid_url media_processing_failed method_not_allowed not_an_image not_found not_ready payment_required quota_exceeded rate_limited result_purged scene_failed scene_generating scene_unsupported service_busy source_image_too_small store_uninstalled too_large unauthorized unreachable_url upload_failed validation_error

message

required

A plain sentence for a person.

string

details

Only present for some codes. For validation_error it maps each wrong field to a list of problems. For quota_exceeded and daily_cap_reached it describes the allowance.

object

key

additional properties

any

Example

{
  "error": {
    "code": "api_not_enabled"
  }
}

401

unauthorized: the Authorization header is missing, or the key is not valid or has been revoked.

Media typeapplication/json

object

error

required

What went wrong. Read code in your software; message is for people.

object

code

required

string

Allowed values: api_not_enabled approval_unavailable attach_conflict bad_request catalog_managed_by_shopify conflict daily_cap_reached external_id_taken family_unsupported forbidden idempotency_conflict idempotency_in_progress image_locked internal_error invalid_url media_processing_failed method_not_allowed not_an_image not_found not_ready payment_required quota_exceeded rate_limited result_purged scene_failed scene_generating scene_unsupported service_busy source_image_too_small store_uninstalled too_large unauthorized unreachable_url upload_failed validation_error

message

required

A plain sentence for a person.

string

details

Only present for some codes. For validation_error it maps each wrong field to a list of problems. For quota_exceeded and daily_cap_reached it describes the allowance.

object

key

additional properties

any

Example

{
  "error": {
    "code": "api_not_enabled"
  }
}

403

api_not_enabled when the API is not switched on for your store yet, store_uninstalled when the store has uninstalled Shootika, or forbidden when the key is not allowed to do that.

Media typeapplication/json

object

error

required

What went wrong. Read code in your software; message is for people.

object

code

required

string

Allowed values: api_not_enabled approval_unavailable attach_conflict bad_request catalog_managed_by_shopify conflict daily_cap_reached external_id_taken family_unsupported forbidden idempotency_conflict idempotency_in_progress image_locked internal_error invalid_url media_processing_failed method_not_allowed not_an_image not_found not_ready payment_required quota_exceeded rate_limited result_purged scene_failed scene_generating scene_unsupported service_busy source_image_too_small store_uninstalled too_large unauthorized unreachable_url upload_failed validation_error

message

required

A plain sentence for a person.

string

details

Only present for some codes. For validation_error it maps each wrong field to a list of problems. For quota_exceeded and daily_cap_reached it describes the allowance.

object

key

additional properties

any

Example

{
  "error": {
    "code": "api_not_enabled"
  }
}

404

not_found: no product with that id exists in your store.

Media typeapplication/json

object

error

required

What went wrong. Read code in your software; message is for people.

object

code

required

string

Allowed values: api_not_enabled approval_unavailable attach_conflict bad_request catalog_managed_by_shopify conflict daily_cap_reached external_id_taken family_unsupported forbidden idempotency_conflict idempotency_in_progress image_locked internal_error invalid_url media_processing_failed method_not_allowed not_an_image not_found not_ready payment_required quota_exceeded rate_limited result_purged scene_failed scene_generating scene_unsupported service_busy source_image_too_small store_uninstalled too_large unauthorized unreachable_url upload_failed validation_error

message

required

A plain sentence for a person.

string

details

Only present for some codes. For validation_error it maps each wrong field to a list of problems. For quota_exceeded and daily_cap_reached it describes the allowance.

object

key

additional properties

any

Example

{
  "error": {
    "code": "api_not_enabled"
  }
}

405

method_not_allowed: this address does not accept that method. The Allow header lists the ones it does.

Media typeapplication/json

object

error

required

What went wrong. Read code in your software; message is for people.

object

code

required

string

Allowed values: api_not_enabled approval_unavailable attach_conflict bad_request catalog_managed_by_shopify conflict daily_cap_reached external_id_taken family_unsupported forbidden idempotency_conflict idempotency_in_progress image_locked internal_error invalid_url media_processing_failed method_not_allowed not_an_image not_found not_ready payment_required quota_exceeded rate_limited result_purged scene_failed scene_generating scene_unsupported service_busy source_image_too_small store_uninstalled too_large unauthorized unreachable_url upload_failed validation_error

message

required

A plain sentence for a person.

string

details

Only present for some codes. For validation_error it maps each wrong field to a list of problems. For quota_exceeded and daily_cap_reached it describes the allowance.

object

key

additional properties

any

Example

{
  "error": {
    "code": "api_not_enabled"
  }
}

Headers

Allow

string

409

catalog_managed_by_shopify on a Shopify store, idempotency_conflict when the key was used for a different request, or idempotency_in_progress when the same key is still running.

Media typeapplication/json

object

error

required

What went wrong. Read code in your software; message is for people.

object

code

required

string

Allowed values: api_not_enabled approval_unavailable attach_conflict bad_request catalog_managed_by_shopify conflict daily_cap_reached external_id_taken family_unsupported forbidden idempotency_conflict idempotency_in_progress image_locked internal_error invalid_url media_processing_failed method_not_allowed not_an_image not_found not_ready payment_required quota_exceeded rate_limited result_purged scene_failed scene_generating scene_unsupported service_busy source_image_too_small store_uninstalled too_large unauthorized unreachable_url upload_failed validation_error

message

required

A plain sentence for a person.

string

details

Only present for some codes. For validation_error it maps each wrong field to a list of problems. For quota_exceeded and daily_cap_reached it describes the allowance.

object

key

additional properties

any

Example

{
  "error": {
    "code": "api_not_enabled"
  }
}

422

validation_error when the body or file field is missing or wrong, invalid_url when the web address is not an allowed one, unreachable_url when it could not be fetched, not_an_image when the file is not a PNG, JPEG or WebP image, or too_large when it is over 15 MB.

Media typeapplication/json

object

error

required

What went wrong. Read code in your software; message is for people.

object

code

required

string

Allowed values: api_not_enabled approval_unavailable attach_conflict bad_request catalog_managed_by_shopify conflict daily_cap_reached external_id_taken family_unsupported forbidden idempotency_conflict idempotency_in_progress image_locked internal_error invalid_url media_processing_failed method_not_allowed not_an_image not_found not_ready payment_required quota_exceeded rate_limited result_purged scene_failed scene_generating scene_unsupported service_busy source_image_too_small store_uninstalled too_large unauthorized unreachable_url upload_failed validation_error

message

required

A plain sentence for a person.

string

details

Only present for some codes. For validation_error it maps each wrong field to a list of problems. For quota_exceeded and daily_cap_reached it describes the allowance.

object

key

additional properties

any

Example

{
  "error": {
    "code": "api_not_enabled"
  }
}

429

rate_limited: more than 120 requests in a minute with this key. Wait the number of seconds in Retry-After.

Media typeapplication/json

object

error

required

What went wrong. Read code in your software; message is for people.

object

code

required

string

Allowed values: api_not_enabled approval_unavailable attach_conflict bad_request catalog_managed_by_shopify conflict daily_cap_reached external_id_taken family_unsupported forbidden idempotency_conflict idempotency_in_progress image_locked internal_error invalid_url media_processing_failed method_not_allowed not_an_image not_found not_ready payment_required quota_exceeded rate_limited result_purged scene_failed scene_generating scene_unsupported service_busy source_image_too_small store_uninstalled too_large unauthorized unreachable_url upload_failed validation_error

message

required

A plain sentence for a person.

string

details

Only present for some codes. For validation_error it maps each wrong field to a list of problems. For quota_exceeded and daily_cap_reached it describes the allowance.

object

key

additional properties

any

Example

{
  "error": {
    "code": "api_not_enabled"
  }
}

Headers

Retry-After

integer

500

internal_error: something went wrong on our side. Try again.

Media typeapplication/json

object

error

required

What went wrong. Read code in your software; message is for people.

object

code

required

string

Allowed values: api_not_enabled approval_unavailable attach_conflict bad_request catalog_managed_by_shopify conflict daily_cap_reached external_id_taken family_unsupported forbidden idempotency_conflict idempotency_in_progress image_locked internal_error invalid_url media_processing_failed method_not_allowed not_an_image not_found not_ready payment_required quota_exceeded rate_limited result_purged scene_failed scene_generating scene_unsupported service_busy source_image_too_small store_uninstalled too_large unauthorized unreachable_url upload_failed validation_error

message

required

A plain sentence for a person.

string

details

Only present for some codes. For validation_error it maps each wrong field to a list of problems. For quota_exceeded and daily_cap_reached it describes the allowance.

object

key

additional properties

any

Example

{
  "error": {
    "code": "api_not_enabled"
  }
}

503

upload_failed when the photo could not be stored, or service_busy when Shootika is busy. Try again in a moment.

Media typeapplication/json

object

error

required

What went wrong. Read code in your software; message is for people.

object

code

required

string

Allowed values: api_not_enabled approval_unavailable attach_conflict bad_request catalog_managed_by_shopify conflict daily_cap_reached external_id_taken family_unsupported forbidden idempotency_conflict idempotency_in_progress image_locked internal_error invalid_url media_processing_failed method_not_allowed not_an_image not_found not_ready payment_required quota_exceeded rate_limited result_purged scene_failed scene_generating scene_unsupported service_busy source_image_too_small store_uninstalled too_large unauthorized unreachable_url upload_failed validation_error

message

required

A plain sentence for a person.

string

details

Only present for some codes. For validation_error it maps each wrong field to a list of problems. For quota_exceeded and daily_cap_reached it describes the allowance.

object

key

additional properties

any

Example

{
  "error": {
    "code": "api_not_enabled"
  }
}