Create a product

POST

/products

curl --request POST \
  --url https://api.shootika.com/v1/products \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "title": "example", "garment_category": "tops", "external_id": "example", "image_urls": [ "example" ] }'

Creates a product, optionally with photos fetched from public web addresses in image_urls. The product is created even if some photos cannot be fetched. Each photo that failed is listed in images_failed with its own code, so check that list before you rely on the images.

Photos fetched from a web address must use http or https on the standard port (80 or 443), must be on a public address, are not followed through redirects, may be at most 15 MB, and each fetch may take at most 20 seconds. All image_urls together may take at most 30 seconds on one create. To upload a file instead, create the product first and then use POST /products/{product_id}/images.

Products created here cannot be made on a Shopify store, because Shopify stores get their products from Shopify.

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

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

Media typeapplication/json

object

title

required

string

<= 500 characters

garment_category

string

Allowed values: tops bottoms one-pieces

external_id

Your own id for the product. It must be unique among your products.

string | null

<= 255 characters

image_urls

Public http or https addresses of photos to fetch.

Array<string>

<= 10 items

Responses

201

The product was created. images_failed is only present when image_urls was sent.

Media typeapplication/json

object

product

required

object

id

required

string format: uuid

external_id

required

Your own id for the product, or null.

string | null

title

required

string

garment_category

required

Any of:

string

string

Allowed values: tops bottoms one-pieces

null

null

images

required

Array<object>

object

id

required

string format: uuid

url

required

string format: uri

width

required

integer | null

height

required

integer | null

created_at

required

string format: date-time

images_failed

Photos from image_urls that could not be added. Only present when image_urls was sent.

Array<object>

object

url

required

string

code

required

One of invalid_url, unreachable_url, not_an_image, too_large, upload_failed.

string

message

required

string

Example

{
  "product": {
    "garment_category": "tops"
  }
}

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"
  }
}

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 when the store is a Shopify store, external_id_taken when another product already uses that external_id, 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, and the details name the fields that are wrong.

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

service_busy: Shootika is busy right now. 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"
  }
}

Headers

Retry-After

integer