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:
| Field | Use it when |
|---|---|
url | The image is on the public web. Ordexs downloads it (15 seconds at most). |
upload_id | You have the file. Get a slot with POST /v1/uploads, PUT the bytes to it, then pass its id. |
media_id | The 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
position0 is the main image.PATCH /v1/products/{product_id}/images/{image_id}withpositionmoves an image (the others shift) and withaltdescribes it.DELETEtakes an image off the product; the file stays in the media library.PATCH /v1/variants/{variant_id}withimage_idgives a variant its own image, one of its product's images (nullgoes 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.
