Tillwire Read the guide
API reference

Catalogue. 88 operations.

88 of them work. Page 2 of 5. Each needs a bearer token with its scope. All operations.

Operations

POST/api/v1/catalogue/variants/{sku}/deletecatalogue.delete-variantcatalogue.write

Parameters

skupathstring
skupathstring
Idempotency-KeyheaderstringSee common parameters

Answer

Deletion

Errors: 401, 403, 404, 405, 409, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/catalogue/variants/{sku}/delete

GET/api/v1/catalogue/fieldscatalogue.fieldscatalogue.read

Errors: 401, 403, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/catalogue/fields

GET/api/v1/catalogue/images/{name}/historycatalogue.image-historycatalogue.read

Parameters

namepathstring
namepathstring

Answer

array of PictureReviewEntry

Errors: 401, 403, 404, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/catalogue/images/{name}/history

GET/api/v1/catalogue/products/{slug}/imagescatalogue.imagescatalogue.read

Parameters

slugpathstring
slugpathstring

Answer

array of ImageUpload

Errors: 401, 403, 404, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/catalogue/products/{slug}/images

POST/api/v1/catalogue/importscatalogue.importcatalogue.write

Parameters

Idempotency-KeyheaderstringSee common parameters

Errors: 401, 403, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/catalogue/imports

POST/api/v1/catalogue/imports/previewcatalogue.import-previewcatalogue.write

Parameters

Idempotency-KeyheaderstringSee common parameters

Errors: 401, 403, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/catalogue/imports/preview

GET/api/v1/catalogue/mediacatalogue.mediacatalogue.read

Parameters

filterquerystringall (or left out) for every image; unplaced for the images on no product.
limitqueryintegerThe most images in the page: 1 to 200; 50 when left out.
afterquerystringThe cursor of the page: the next of the page before; the first page when left out. The images follow it.

Answer

MediaPage

Errors: 401, 403, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/catalogue/media

POST/api/v1/catalogue/review/{slug}/open-againcatalogue.open-againcatalogue.write

Parameters

slugpathstring
slugpathstring
Idempotency-KeyheaderstringSee common parameters

Request body

SeenRequest

Errors: 401, 403, 404, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/catalogue/review/{slug}/open-again

GET/api/v1/catalogue/products/{slug}/option-picturescatalogue.option-picturescatalogue.read

Parameters

slugpathstring
slugpathstring

Answer

array of OptionPictures

Errors: 401, 403, 404, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/catalogue/products/{slug}/option-pictures

POST/api/v1/catalogue/categories/ordercatalogue.order-categoriescatalogue.write

Parameters

Idempotency-KeyheaderstringSee common parameters

Answer

array of Category

Errors: 401, 403, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/catalogue/categories/order

POST/api/v1/catalogue/products/{slug}/images/ordercatalogue.order-imagescatalogue.write

Parameters

slugpathstring
slugpathstring
Idempotency-KeyheaderstringSee common parameters

Request body

ImageOrderRequest

Answer

array of ImageUpload

Errors: 401, 403, 404, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/catalogue/products/{slug}/images/order

GET/api/v1/catalogue/picture-settingscatalogue.picture-settingscatalogue.read

Errors: 401, 403, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/catalogue/picture-settings

GET/api/v1/catalogue/pictures/to-reviewcatalogue.pictures-to-reviewcatalogue.read

Parameters

limitqueryintegerThe most pictures in the page: 1 to 200; 50 when left out.
afterquerystringThe cursor of the page: the next of the page before; the first page when left out. The pictures follow it.

Errors: 401, 403, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/catalogue/pictures/to-review

POST/api/v1/catalogue/collection-rules/previewcatalogue.preview-collection-rulescatalogue.read

Parameters

Idempotency-KeyheaderstringSee common parameters

Request body

CollectionRules

Errors: 401, 403, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/catalogue/collection-rules/preview

GET/api/v1/catalogue/variants/{sku}/price-changescatalogue.price-changescatalogue.read

Parameters

skupathstring
skupathstring
limitqueryintegerThe most changes in the answer: 1 to 200.

Errors: 401, 403, 404, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/catalogue/variants/{sku}/price-changes

GET/api/v1/catalogue/productscatalogue.productscatalogue.read

Read a page at a time: give limit (1 to 500; 100 when none is given) and after, the Next-Cursor of the page before. Follow the Link, rel next, to the rest.

Parameters

limitqueryintegerThe most products in the page: 1 to 500; 100 when the call gives no limit. The Next-Cursor and Link headers name the next page.
afterquerystringSee common parameters

Answer

array of Product

Errors: 400, 401, 403, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/catalogue/products

GET/api/v1/catalogue/products-by-slugcatalogue.products-by-slugcatalogue.read

Parameters

slugsquerystringThe slugs of the products, separated by commas.

Errors: 401, 403, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/catalogue/products-by-slug

POST/api/v1/catalogue/review/{slug}/retirecatalogue.propose-retirecatalogue.write

Parameters

slugpathstring
slugpathstring
Idempotency-KeyheaderstringSee common parameters

Errors: 401, 403, 404, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/catalogue/review/{slug}/retire

POST/api/v1/catalogue/products/{slug}/publishcatalogue.publishcatalogue.write

Parameters

slugpathstring
slugpathstring
Idempotency-KeyheaderstringSee common parameters

Errors: 401, 403, 404, 405, 409, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/catalogue/products/{slug}/publish

POST/api/v1/catalogue/collections/{slug}/publishcatalogue.publish-collectioncatalogue.write

Parameters

slugpathstring
slugpathstring
Idempotency-KeyheaderstringSee common parameters

Errors: 401, 403, 404, 405, 409, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/catalogue/collections/{slug}/publish

Schemas 47

Category

Category is a category of the store's tree as the owner sees it: its name, its slug, its parent's slug ("" for a root), its description in the safe Markdown subset, its position among its siblings (0 for none), and its trail, the names from the root down to it, such as "Braais / Accessories", which tells two categories of one name apart.

descriptionrequiredstring
enquiry_mail_torequiredstring
enquiry_onlyrequiredboolean
namerequiredstring
parentrequiredstring
positionrequiredinteger
slugrequiredstring
trailrequiredstring
CategoryOrderRequest

CategoryOrderRequest is the order of the categories under one parent: the parent's slug, "" for the roots, and the slugs of its children, first to last: exactly those, each once.

categoriesrequiredarray of string
parentrequiredstring
ChoiceField

ChoiceField is a question a product asks the buyer for each cart line: a free text, or one value of a list. Its Key never changes after an order uses it.

helprequiredstring
keyrequiredstring
kindrequiredstring
labelrequiredstring
linesrequiredinteger
max_lengthrequiredinteger
optionalrequiredboolean
valuesrequiredarray of string
Collection

Collection is a collection as the owner sees it: its title, its slug, its description in the safe Markdown subset, whether buyers see it, and its products by slug, in the owner's order.

descriptionrequiredstring
dynamicrequiredboolean
product_countrequiredinteger
productsrequiredarray of string
publishedrequiredboolean
revisionrequiredinteger
rulesCollectionRules
rules_saved_atstring (date-time)
rules_saved_bystring
rules_textstring
slugrequiredstring
titlerequiredstring
CollectionChange

CollectionChange is a collection as an operation left it, and whether the operation changed it.

changedrequiredboolean
collectionrequiredCollection
CollectionCondition

CollectionCondition is one condition: its kind, and the arguments of that kind, the others left out. Kinds: category (a category's slug, and the categories below it), price (Min, Max, either one may be left out), on_sale, in_stock, new_within (Days, from 1 to 365) and option (Option, an option's name, and Value, one of its values, in any case) and field (Field, a custom product field's key, and either Value, a choice or yes/no value of it, or Lo and Hi, the lowest and the highest of a number or a date, as the field writes them, either one may be left out). A price is text with exactly two decimals, VAT-inclusive as the owner enters it.

categorystring
daysinteger
fieldstring
histring
kindrequiredstring
lostring
maxstring
minstring
optionstring
valuestring
CollectionPreview

CollectionPreview is what rules would hold now: how many products, and the slugs of the first 24, in the rules' sort.

countrequiredinteger
productsrequiredarray of string
CollectionRules

CollectionRules are a dynamic collection's rules: how the conditions combine, all or any; the conditions; and the sort of its products, one of newest, price_asc, price_desc, title and featured. From contract version 6.

conditionsrequiredarray of CollectionCondition
matchrequiredstring
sortrequiredstring
Combo

Combo is a combo variant as the operations show it: whether it sells at the sum of its parts' prices, and its parts in order. From version 6.

partsrequiredarray of ComboPartRequest
sumrequiredboolean
ComboPartRequest

ComboPartRequest is a part of a combo: the SKU of a variant of the store that is no combo itself, once in a combo, and how many of it one combo holds, from 1 to 99.

quantityrequiredinteger
skurequiredstring
Deletion

Deletion is what a delete deleted: the slug of the category, the collection or the content page that is gone, or the name of the image.

deletedrequiredstring
Dimensions

Dimensions are a variant's size in whole millimetres: all three 0 for none, or each from 1 to 10 000.

height_mmrequiredinteger
length_mmrequiredinteger
width_mmrequiredinteger
FieldDefinition

FieldDefinition is one field: the key a theme and a filter name it by, which never changes; the label a buyer reads; its type (text, number, yes_no, choice or date); its scope (product or variant); where it is shown (page, listings, both or hidden); whether it is filterable; its position; a number's unit; a choice field's choices and whether it holds several; how many products or variants hold a value of it; and who saved it and when.

choicesarray of string
countrequiredinteger
filterablerequiredboolean
keyrequiredstring
labelrequiredstring
multipleboolean
positionrequiredinteger
saved_atstring (date-time)
saved_byrequiredstring
scoperequiredstring
shownrequiredstring
typerequiredstring
unitstring
ImageOrderRequest

ImageOrderRequest is the order of a product's images: the names of every image it has, each once, the first its lead image.

namesrequiredarray of string
ImageUpload

ImageUpload is a product's image: as its upload left it, and as catalogue.images reads it.

altrequiredstring
copy_failurestring
heightrequiredinteger
namerequiredstring
positionrequiredinteger
processingrequiredboolean
productrequiredstring
thumbnailrequiredstring
widthrequiredinteger
ImportDraft

ImportDraft is a description imported as a draft.

sourcesrequiredarray of string
ImportOutcome

ImportOutcome is one product's outcome: "created" with the state it landed in, or "refused" with why. A refused row changes nothing.

codestring
indexrequiredinteger
outcomerequiredstring
slugrequiredstring
statestring
wordsstring
ImportPicture

ImportPicture is a picture of an imported product: from a picture source the store registers (engine/ext), by its name and its free-text reference; its state "pending" (when left out) or "approved", which needs the approve right as State does.

mainboolean
sourcerequiredstring
source_refrequiredstring
statestring
variantstring
ImportProduct

ImportProduct is one product of an import.

categorystring
classesarray of string
descriptionrequiredstring
draftImportDraft
merged_fromarray of string
optionsarray of string
picturesarray of ImportPicture
questionsarray of ImportQuestion
short_descriptionstring
slugstring
titlerequiredstring
variantsrequiredarray of ImportVariant
ImportQuestion

ImportQuestion is an open question put on an imported product (ASI-2.4).

choicesrequiredarray of string
rightstring
textrequiredstring
ImportVariant

ImportVariant is a variant of an imported product.

digitalboolean
height_mminteger
length_mminteger
option_valuesarray of string
pricerequiredstring
skurequiredstring
weight_gramsinteger
width_mminteger
MediaImage

MediaImage is an image of the media library. From version 6.

altrequiredstring
bytesrequiredinteger
file_namerequiredstring
heightrequiredinteger
namerequiredstring
productsrequiredarray of MediaProduct
srcrequiredstring
uploaded_atrequiredstring (date-time)
widthrequiredinteger
MediaPage

MediaPage is a page of the media library, as catalogue.media reads it: its images, newest first, and Next, the cursor of the page after it, to give as after; "" on the last page. From version 6.

imagesrequiredarray of MediaImage
nextrequiredstring
MediaProduct

MediaProduct is a product that shows an image of the library.

slugrequiredstring
titlerequiredstring
Money

Money is an amount: in minor units of its ISO 4217 currency, and as the store displays it.

currencyrequiredstring
displayrequiredstring
minorrequiredinteger
OptionPictures

OptionPictures is the list of pictures of one value of one option of a product (ASI-3.5, C14): the names of the product's own pictures, in order. A variant with none of its own shows the list of the first of its option values that has one, else its product's pictures. Additive, from version 6.

imagesrequiredarray of string
optionrequiredstring
valuerequiredstring
PictureReviewEntry

PictureReviewEntry is a review of a picture: its state, note, who and the checklist lines ticked.

actorrequiredstring
atrequiredstring (date-time)
checksrequiredarray of string
noterequiredstring
staterequiredstring
PictureSettings

PictureSettings are the settings the screens of the review read (ASI-3.9b, ASI-3.9c, ASI-3.11): whether the store reviews its uploads, the lines of its checklist, the months a version that is no longer shown is kept, and the importers and picture tools a fork registered (none until it does).

checklistrequiredarray of string
importersrequiredarray of PictureSource
keep_monthsrequiredinteger
reviewrequiredboolean
toolsrequiredarray of PictureSource
PictureSource

PictureSource is an importer or a picture tool: its kind, which the operations name, and its label for a screen.

kindrequiredstring
labelrequiredstring
PictureToReview

PictureToReview is a picture that waits for review: a version of a picture, or a picture itself in a store that reviews its uploads, and the product that shows it.

categoryrequiredstring
numberrequiredinteger
product_slugrequiredstring
product_titlerequiredstring
versionrequiredPictureVersion
PictureVersion

PictureVersion is a picture, or an edited version of one, with its review state (ASI-3.1 to ASI-3.6). A version has Of, the name of the original it is a version of; an original has Of "" and Shown, the name of the version it shows, "" when it shows itself. Additive, from version 6.

altrequiredstring
digestrequiredstring
heightrequiredinteger
heldrequiredboolean
hold_reasonrequiredstring
largerequiredstring
made_byrequiredstring
namerequiredstring
noterequiredstring
ofrequiredstring
shownrequiredstring
sourcerequiredstring
source_refrequiredstring
staterequiredstring
thumbnailrequiredstring
uploaded_atrequiredstring (date-time)
widthrequiredinteger
PicturesToReview

PicturesToReview is a page of the pictures that wait for review (ASI-3.8), oldest first: Count is the number waiting in all, and Next the cursor to give as after for the page after this one, "" on the last. From version 6, additive.

countrequiredinteger
itemsrequiredarray of PictureToReview
nextrequiredstring
PriceChange

PriceChange is one change to a variant's price, sale price or compare-at price: Field is price, sale_price or compare_at; Before and After the value it had and has, null for none (a first price has none before, a sale taken away none after); for a sale set, SaleStartsAt and SaleEndsAt the window it was given; Actor who made the change, such as user:owner, integration:id, cli or engine, and At when.

actorrequiredstring
afterrequiredMoney
atrequiredstring (date-time)
beforerequiredMoney
fieldrequiredstring
idrequiredinteger
sale_ends_atrequiredstring (date-time)
sale_starts_atrequiredstring (date-time)
PriceChanges

PriceChanges is a variant's log of price changes, newest first. From contract version 6.

changesrequiredarray of PriceChange
skurequiredstring
Product

Product is a product of the catalogue, with every variant.

card_titlerequiredstring
categoriesrequiredarray of string
categoryrequiredstring
choicesrequiredarray of ChoiceField
choices_allowedrequiredboolean
choices_refusedstring
country_of_originrequiredstring
cross_sellsrequiredarray of string
descriptionrequiredstring
enquiry_moderequiredstring
enquiry_onlyrequiredboolean
enquiry_show_pricerequiredboolean
featured_positionrequiredinteger
fieldsrequiredmap of array of string
hs_coderequiredstring
meta_descriptionrequiredstring
meta_titlerequiredstring
optionsrequiredarray of string
relatedrequiredarray of string
retiredProductRetirement
ships_freerequiredboolean
short_descriptionrequiredstring
slugrequiredstring
titlerequiredstring
unpublished_atstring (date-time)
updatedstring (date-time)
upsellsrequiredarray of string
variantsrequiredarray of Variant
ProductChange

ProductChange is a product as an operation left it, and whether the operation changed it.

changedrequiredboolean
productrequiredProduct
ProductFields

ProductFields are the definitions of the custom product fields, in the owner's order, at the revision each write must send back (0 while the owner never saved one).

fieldsrequiredarray of FieldDefinition
revisionrequiredinteger
ProductImportRequest

ProductImportRequest is an import of products (ASI-2.13). The preview writes nothing and answers what the import would do.

productsrequiredarray of ImportProduct
statestring
ProductImportResult

ProductImportResult is what an import did, or a preview would do, row by row (46i).

createdrequiredinteger
refusedrequiredinteger
rowsrequiredarray of ImportOutcome
ProductRetirement

ProductRetirement is how a product left the shop (PR-4): At, when it was retired; ReplacedBy, the slug of the product that replaces it, "" for none; KeepPage, whether its address keeps a page that says it is no longer sold.

atrequiredstring (date-time)
keep_pagerequiredboolean
replaced_byrequiredstring
ProductsBySlug

ProductsBySlug is the products at the slugs asked, in the order asked, and the slugs asked that are no product, in the order asked; an empty list for none. From version 6.

productsrequiredarray of Product
unknownrequiredarray of string
ProposeRetireRequest

ProposeRetireRequest proposes to retire the product (ASI-2.12).

keep_pageboolean
noterequiredstring
targetrequiredstring
ReviewActResult

ReviewActResult is the product after an act: its state and look-again flag, whether it is published, and, after an approval, the next product of the list ("" for none).

look_againrequiredboolean
nextrequiredstring
publishedrequiredboolean
slugrequiredstring
staterequiredstring
Sale

Sale is a variant's sale price and its window: the price it sells at from Start, inclusive, to End, exclusive.

endrequiredstring (date-time)
pricerequiredMoney
startrequiredstring (date-time)
SeenRequest

SeenRequest is the body of an approval act that takes nothing but Seen.

seenrequiredstring
Variant

Variant is a variant of a product.

allow_backorderrequiredboolean
archived_atstring (date-time)
comboCombo
compare_atMoney
digitalrequiredboolean
dimensionsDimensions
dispatch_byrequiredstring
fieldsrequiredmap of array of string
filerequiredVariantFile
imagesrequiredarray of string
low_stock_thresholdinteger
made_to_orderrequiredboolean
option_valuesrequiredarray of string
pricerequiredMoney
production_daysrequiredinteger
saleSale
ships_alonerequiredboolean
skurequiredstring
stockrequiredinteger
supplierrequiredstring
tax_classrequiredstring
track_stockrequiredboolean
weight_gramsrequiredinteger
VariantFile

VariantFile is a digital variant's file: its name as a download is saved, its size in bytes, its SHA-256 in lower-case hex, and when and by whom it was uploaded. From contract version 6.

digestrequiredstring
namerequiredstring
sizerequiredinteger
uploaded_atrequiredstring (date-time)
uploaded_byrequiredstring

Made from engine/internal/openapi/openapi.json at commit 6c4cbd921. The contract-only operations come from the engine’s stub file, engine/internal/ops.