Ordexs API v1 Get an API key

Selling cash on delivery

Product images

Add images to products from a URL or a file, reorder them, give variants their own image, and read the media library.

Adding an image

POST /v1/products/{product_id}/images takes one of three sources:

FieldUse it when
urlThe image is on the public web. Ordexs downloads it (15 seconds at most).
upload_idYou have the file. Get a slot with POST /v1/uploads, PUT the bytes to it, then pass its id.
media_idThe image is already in the store's media library (GET /v1/media).

JPG, PNG, WebP or AVIF, 3 MB at most. Ordexs makes the sizes the storefront serves (WebP, from 320 to 1920 pixels on the longest side, never enlarged), adds the file to the media library, where it counts toward the store's storage, and puts the image on the product.

curl https://api.ordexs.com/v1/products/prod_…/images \
  -H "Authorization: Bearer $ORDEXS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hoodie-black.jpg","alt":"Black oversized hoodie","position":0}'

Uploading a file

# 1. A slot (valid 15 minutes)
curl https://api.ordexs.com/v1/uploads -H "Authorization: Bearer $ORDEXS_KEY" \
  -H "Content-Type: application/json" -d '{"content_type":"image/jpeg","size":845120}'
# 2. PUT the file to upload_url with the headers the slot gave
curl -X PUT "$UPLOAD_URL" -H "Content-Type: image/jpeg" --data-binary @hoodie.jpg
# 3. Put it on the product
curl https://api.ordexs.com/v1/products/prod_…/images -H "Authorization: Bearer $ORDEXS_KEY" \
  -H "Content-Type: application/json" -d '{"upload_id":"upl_…"}'

A slot is used once; one that is never used is deleted after a day.

Order, alt text and variants

  • position 0 is the main image. PATCH /v1/products/{product_id}/images/{image_id} with position moves an image (the others shift) and with alt describes it.
  • DELETE takes an image off the product; the file stays in the media library.
  • PATCH /v1/variants/{variant_id} with image_id gives a variant its own image, one of its product's images (null goes back to the product's images).

The image url is the largest size. The others sit beside it with -320, -640 and -1024 in place of -1920, so a srcset can serve phones a small file.

Limits

A product holds 50 images, and a store can add 500 images a day through the API. Past either, the answer is quota_exceeded. A full store storage is quota_exceeded too: the merchant frees space under Media or upgrades.

The media library

GET /v1/media lists the store's files (images, videos, documents) newest first, with type and in_use filters; in_use is true when a file is shown somewhere on the store. Deleting library files is done in the dashboard.