Tillwire Read the guide
API reference

Catalogue. 88 operations.

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

Operations

POST/api/v1/catalogue/review/{slug}/descriptioncatalogue.accept-descriptioncatalogue.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}/description

POST/api/v1/catalogue/products/{slug}/variantscatalogue.add-variantcatalogue.write

Parameters

slugpathstring
slugpathstring
Idempotency-KeyheaderstringSee common parameters

Request body

VariantRequest

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

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

POST/api/v1/catalogue/review/{slug}/questions/{id}catalogue.answer-questioncatalogue.write

Parameters

slugpathstring
idpathstring
slugpathstring
idpathstring
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}/questions/{id}

POST/api/v1/catalogue/review/{slug}/approvecatalogue.approve-productcatalogue.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}/approve

POST/api/v1/catalogue/variants/{sku}/archivecatalogue.archive-variantcatalogue.write

Parameters

skupathstring
skupathstring
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/variants/{sku}/archive

POST/api/v1/catalogue/review/{slug}/ask-photocatalogue.ask-photocatalogue.write

Parameters

slugpathstring
slugpathstring
Idempotency-KeyheaderstringSee common parameters

Request body

AskPhotoRequest

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

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

POST/api/v1/catalogue/media/{name}/attachcatalogue.attach-imagecatalogue.write

Parameters

namepathstring
namepathstring
Idempotency-KeyheaderstringSee common parameters

Request body

AttachImageRequest

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

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/catalogue/media/{name}/attach

POST/api/v1/catalogue/products/{slug}/variants/bulkcatalogue.bulk-set-variantscatalogue.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/products/{slug}/variants/bulk

GET/api/v1/catalogue/categoriescatalogue.categoriescatalogue.read

Answer

array of Category

Errors: 401, 403, 405, 422, 429

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

POST/api/v1/catalogue/variants/{sku}/sale/clearcatalogue.clear-salecatalogue.write

Parameters

skupathstring
skupathstring
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/variants/{sku}/sale/clear

GET/api/v1/catalogue/collections/{slug}/productscatalogue.collection-productscatalogue.read

Parameters

slugpathstring
slugpathstring
limitqueryintegerThe most products in the page; all when left out.
afterquerystringThe cursor of the page: the next of the page before; the first page when left out. The products follow it.

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

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

GET/api/v1/catalogue/collectionscatalogue.collectionscatalogue.read

Answer

array of Collection

Errors: 401, 403, 405, 422, 429

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

POST/api/v1/catalogue/productscatalogue.create-productcatalogue.write

Parameters

Idempotency-KeyheaderstringSee common parameters

Request body

ProductRequest

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

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

POST/api/v1/catalogue/review/{slug}/held/{id}catalogue.decide-heldcatalogue.write

Parameters

slugpathstring
idpathstring
slugpathstring
idpathstring
Idempotency-KeyheaderstringSee common parameters

Request body

DecideHeldRequest

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

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

POST/api/v1/catalogue/review/{slug}/retire/decidecatalogue.decide-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/decide

POST/api/v1/catalogue/categories/{slug}/deletecatalogue.delete-categorycatalogue.write

Parameters

slugpathstring
slugpathstring
Idempotency-KeyheaderstringSee common parameters

Answer

Deletion

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

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

POST/api/v1/catalogue/collections/{slug}/deletecatalogue.delete-collectioncatalogue.write

Parameters

slugpathstring
slugpathstring
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/collections/{slug}/delete

POST/api/v1/catalogue/fields/{key}/deletecatalogue.delete-fieldcatalogue.write

Parameters

keypathstring
keypathstring
Idempotency-KeyheaderstringSee common parameters

Request body

FieldDeleteRequest

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

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

POST/api/v1/catalogue/images/{name}/deletecatalogue.delete-imagecatalogue.write

Parameters

namepathstring
namepathstring
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/images/{name}/delete

POST/api/v1/catalogue/media/{name}/deletecatalogue.delete-mediacatalogue.write

Parameters

namepathstring
namepathstring
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/media/{name}/delete

Schemas 39

AcceptDescriptionRequest

AcceptDescriptionRequest accepts one description, Part "long" (when left out) or "short", as seen.

partstring
seenrequiredstring
AnswerQuestionRequest

AnswerQuestionRequest resolves a question with one of its choices.

choicerequiredstring
seenrequiredstring
ApproveProductRequest

ApproveProductRequest approves the product (ASI-2.6): it also publishes a product that was never published (ASI-2.8). The list's filters give Next.

listrequiredReviewWorkspaceQuery
seenrequiredstring
AskPhotoRequest

AskPhotoRequest asks for a new photo (ASI-2.10).

wordsrequiredstring
AttachImageRequest

AttachImageRequest puts an image of the library on a product: the product's slug, and the position it takes among the product's images, from 0; absent or null for the last.

positionrequiredinteger
productrequiredstring
BulkVariantEdit

BulkVariantEdit is one variant's change: its price as the owner enters it, its stock count with the count expected, or both; a field left out leaves it as it is. The API door refuses an edit that sets nothing.

pricestring
skurequiredstring
stockStockRequest
BulkVariantsRequest

BulkVariantsRequest is the changes of several variants of one product, made together or not at all: each variant by its SKU.

variantsrequiredarray of BulkVariantEdit
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
CategoryDeleteRequest

CategoryDeleteRequest deletes a category. A category that the rules of a dynamic collection name is refused unless DropFromCollections is set: the conditions on it are then taken out of the rules, in the same transaction; rules left with no condition are cleared. Drops, when it is given (even empty), names the slugs of the collections the owner was shown as the ones to change; the request is refused (409, naming both) unless they are exactly the collections the rules name now, in any order. Without it nothing is checked.

drop_from_collectionsboolean
dropsarray of string
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
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
CollectionProductsPage

CollectionProductsPage is a page of a collection's products: their slugs, in the collection's order; Total, how many it holds in all; and Next, the cursor of the next page, to pass as after, "" for the last.

nextrequiredstring
slugsrequiredarray of string
totalrequiredinteger
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
ComboRequest

ComboRequest is a combo variant's parts and how it is priced: its parts in order, and whether it sells at the sum of their prices now (Sum), in which case its variant has no price of its own.

partsrequiredarray of ComboPartRequest
sumboolean
DecideHeldRequest

DecideHeldRequest decides a held change: Use true is "I checked it: use the new value", false is "Keep the approved value".

seenrequiredstring
userequiredboolean
DecideRetireRequest

DecideRetireRequest approves (Approve true) or refuses a proposed retire.

approverequiredboolean
noterequiredstring
seenrequiredstring
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
FieldDeleteRequest

FieldDeleteRequest deletes the field its path names: the definitions' revision as the owner read it, and whether the owner confirms deleting the values it holds with it.

confirmboolean
drop_from_collectionsboolean
dropsarray of string
revisionrequiredinteger
FieldDeletion

FieldDeletion is a field deleted: how many products and variants held a value of it, and the definitions then.

fieldsrequiredProductFields
removedrequiredinteger
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
Money

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

currencyrequiredstring
displayrequiredstring
minorrequiredinteger
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
ProductRequest

ProductRequest is a product the owner creates, with its first variant. It starts unpublished, with no image: catalogue.upload-image adds them, catalogue.set-categories puts it in categories, and catalogue.publish shows it to buyers.

descriptionrequiredstring
optionsarray of string
short_descriptionstring
slugstring
titlerequiredstring
variantrequiredVariantRequest
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
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
ReviewWorkspaceQuery

ReviewWorkspaceQuery is the query of catalogue.review-workspace: the list's filters the product was opened from (ReviewListQuery but After and Limit), for its place and neighbours (ASI-7.4).

categorystring
checkstring
propertystring
qstring
statestring
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)
StockRequest

StockRequest is a variant's new stock count, and the count the caller saw, which the store must still hold for the set to be made. The body must carry both: the API door refuses one without either. Location names the stock location whose level is set; none (or main) is the location main. Expected and Count are then that location's.

countrequiredinteger
expectedrequiredinteger
locationstring
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
VariantChange

VariantChange is a variant as an operation left it, and whether the operation changed it.

changedrequiredboolean
variantrequiredVariant
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
VariantRequest

VariantRequest is a new product's first variant, or a variant added to a product.

allow_backorderboolean
comboComboRequest
compare_atstring
dimensionsDimensions
low_stock_thresholdinteger
optionsmap of string
pricerequiredstring
ships_aloneboolean
skurequiredstring
stockrequiredinteger
tax_classstring
track_stockrequiredboolean
weight_gramsinteger

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