{"openapi":"3.0.0","info":{"title":"Stockhub Fulfilment Open API","version":"1.0.0","description":"Manage warehouse operations across the relations in your catalog.","contact":{"name":"Stockhub Support","url":"https://www.stockhub.nl","email":"support@stockhub.nl"},"license":{"name":"Proprietary","url":"https://www.stockhub.nl/license"}},"servers":[{"url":"https://openapi.stockhub.nl/fulfilment","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Key","description":"Bearer token authentication using a Stockhub API Key. Read \"Authentication\" to learn how to create and manage keys."}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"success":{"type":"boolean","example":false}},"required":["error","success"]},"SuccessResponse":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"success":{"type":"boolean","example":true},"data":{"type":"object","description":"Response data"}},"required":["success"]},"Me":{"type":"object","properties":{"success":{"type":"boolean"},"keyId":{"type":"string","format":"uuid"},"catalog":{"type":"string"},"rights":{"type":"array","items":{"type":"string"}}}},"OrderSummary":{"type":"object","properties":{"id":{"type":"integer","description":"Order ID","example":12345},"barcode":{"type":"string","description":"Order barcode","example":"ORD-123456"},"state":{"type":"string","description":"Current state of the order","example":"pending"},"webshopreference":{"type":"string","description":"Reference from webshop","example":"WS-ORDER-789"},"orderlines":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"integer","description":"Quantity of the product","example":2},"sku":{"type":"string","description":"Product SKU","example":"PROD-123"},"product":{"type":"string","description":"Product description","example":"Red T-Shirt Size M"}}}},"created":{"type":"string","format":"date-time","description":"Date and time the order was created"},"date_planned":{"type":"string","format":"date-time","description":"Planned shipment date"},"date_sent":{"type":"string","format":"date-time","description":"Date and time the order was packed and shipped"},"channel":{"type":"string","description":"Name of the webshop as registered in Stockhub"},"externalId":{"type":"string","description":"External order identifier"},"isB2B":{"type":"boolean","description":"Whether the order is a B2B (business-to-business) order","example":false},"stream":{"type":"string","nullable":true,"readOnly":true,"description":"Name of the stream the order is assigned to. Null when the order has no stream. Read-only.","example":"PostNL brievenbus"},"deliveryMethod":{"$ref":"#/components/schemas/DeliveryMethod"},"totalCost":{"type":"number","format":"float","description":"The fulfilment cost for this order"},"errorReason":{"type":"string","nullable":true,"description":"Why the order is on hold (e.g. address validation failure). Null when the order has no open error.","example":"Stad niet gevonden."},"addressSuggestion":{"type":"string","nullable":true,"description":"Suggested corrected address when address validation found a close match.","example":"Dorpsstraat 1, 1231 AA Amsterdam, Nederland"},"shippingAdress":{"type":"object","description":"Shipping address details","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"countryCode":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"}}}}},"OrderAddressUpdate":{"type":"object","description":"Partial shipping address update; only supplied fields are changed.","required":["shippingAddress"],"properties":{"shippingAddress":{"type":"object","minProperties":1,"properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"insertion":{"type":"string"},"company":{"type":"string"},"addressLine1":{"type":"string","example":"Dorpsstraat 1"},"addressLine2":{"type":"string"},"street":{"type":"string","example":"Dorpsstraat"},"houseNumber":{"type":"string","example":"1"},"houseNumberAddition":{"type":"string"},"postalCode":{"type":"string","example":"1231 AA"},"city":{"type":"string","example":"Amsterdam"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code","example":"NL"},"state":{"type":"string","description":"Province/region"},"phone":{"type":"string"},"email":{"type":"string"},"skipValidation":{"type":"boolean","description":"Set to true to skip address validation for this order, e.g. for an address without a house number. The order then leaves its \"action required\" state. Can be sent on its own or together with address fields.\n"}}}}},"OrderCreate":{"type":"object","properties":{"relationId":{"type":"integer","description":"Relation that owns the order. Must be an existing relation in the warehouse the API key belongs to.\n","example":12},"webshopId":{"type":"integer","description":"Webshop the order belongs to. Must belong to the relation given in `relationId`, otherwise the API responds 403.\n","example":42},"orderlines":{"type":"array","description":"Order line items","items":{"type":"object","properties":{"amount":{"type":"integer","description":"Quantity of items","example":2},"sku":{"type":"string","description":"Product SKU","example":"PROD-001"},"externalId":{"type":"string","description":"External line identifier","example":"LINE-001"}},"required":["amount","sku","externalId"]}},"externalId":{"type":"string","description":"External order identifier","example":"EXT-456"},"webshopreference":{"type":"string","description":"Reference from webshop / Order number","example":"WS-ORDER-789"},"date_planned":{"type":"string","format":"date","description":"Planned delivery date","example":"2024-01-15"},"remark":{"type":"string","description":"Remark for the order","example":"Please read this remark"},"isB2B":{"type":"boolean","description":"Mark the order as a B2B (business-to-business) order","example":true},"email":{"type":"string","format":"email","description":"Customer email","example":"john.doe@example.com"},"shippingAddress":{"type":"object","description":"Shipping address details","properties":{"firstName":{"type":"string","example":"John"},"lastName":{"type":"string","example":"Doe"},"company":{"type":"string","example":"Acme Corp"},"addressLine1":{"type":"string","example":"Ambachtstraat 15b"},"addressLine2":{"type":"string","example":"Appartement 25"},"postal":{"type":"string","example":"1012 AB"},"city":{"type":"string","example":"Amsterdam"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country code","example":"NL"},"phone":{"type":"string","example":"+31612345678"}},"required":["firstName","lastName","addressLine1","postal","city","country_code"]}},"required":["relationId","webshopId","orderlines","externalId","email","shippingAddress"]},"Shipment":{"type":"object","properties":{"order_barcode":{"type":"string","description":"Associated order barcode","example":"O25-6324"},"tracking_number":{"type":"string","description":"Shipment tracking number","example":"TRK123456789"},"shipment_date":{"type":"string","format":"date-time","description":"Shipment date and time"},"shipper_code":{"type":"string","description":"Carrier code","example":"postnl"},"tracking_url":{"type":"string","description":"Tracking URL"},"delivery_address":{"type":"object","description":"Delivery address","properties":{"street":{"type":"string","example":"Amstel"},"house_nr":{"type":"string","example":"1"},"house_nr_extra":{"type":"string"},"city":{"type":"string","example":"Amsterdam"},"postal":{"type":"string","example":"1011 PN"},"country":{"type":"string","example":"NL"}}}}},"DeliveryMethod":{"type":"string","readOnly":true,"description":"How the order is delivered. Read-only.","enum":["regular","pickup","vvb","vvb_sameday","lvb","fba","amazon_easyship","dropshipping"],"example":"regular"},"Dimensions":{"type":"object","description":"Package dimensions in millimetres, weight in grams. 0 when not measured.","properties":{"length":{"type":"integer","example":300},"width":{"type":"integer","example":200},"height":{"type":"integer","example":100},"weight":{"type":"number","example":1250}}},"ShipmentDimensions":{"type":"object","readOnly":true,"description":"Read-only.","properties":{"internal":{"allOf":[{"$ref":"#/components/schemas/Dimensions"}],"description":"Dimensions measured by Stockhub"},"external":{"allOf":[{"$ref":"#/components/schemas/Dimensions"}],"description":"Dimensions reported by the carrier"}}},"ShipmentListItem":{"type":"object","description":"Shipment summary used by the list endpoint (camelCase keys)","properties":{"orderBarcode":{"type":"string","description":"Associated order barcode","example":"O25-6324"},"trackingNumber":{"type":"string","description":"Shipment tracking number","example":"TRK123456789"},"shipmentDate":{"type":"string","format":"date-time","description":"Shipment date and time","example":"2025-12-01T10:30:00Z"},"shipperCode":{"type":"string","description":"Canonical carrier code (e.g. postnl, dhl, dpd, bpost)","example":"postnl"},"trackingUrl":{"type":"string","description":"Public tracking URL for the shipment","example":"https://jouw.postnl.nl/track-and-trace/..."},"carrierStatus":{"type":"string","nullable":true,"description":"Latest carrier status known to Stockhub. Null when tracking has not been fetched yet.","enum":["created","underway","delivered","not_delivered","failed","not_fetched",null],"example":"delivered"},"deliveredAt":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp of the latest carrier scan once carrierStatus is delivered; null otherwise.","example":"2025-12-03T14:22:00Z"},"dimensions":{"$ref":"#/components/schemas/ShipmentDimensions"},"deliveryAddress":{"type":"object","description":"Delivery address (snake_case inside the address object, matching the per-order endpoint)","properties":{"street":{"type":"string","example":"Amstel"},"house_nr":{"type":"string","example":"1"},"house_nr_extra":{"type":"string","example":"A"},"city":{"type":"string","example":"Amsterdam"},"postal":{"type":"string","example":"1011 PN"},"country":{"type":"string","example":"NL"}}}}},"ShipmentsListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"page":{"type":"integer"},"prev":{"type":"integer","nullable":true},"next":{"type":"integer","nullable":true},"totalItems":{"type":"integer"},"totalPages":{"type":"integer"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentListItem"}}}},"ShipmentStatusResponse":{"type":"object","description":"Carrier status and full scan history for one shipment","properties":{"orderBarcode":{"type":"string","example":"O25-6324"},"trackingNumber":{"type":"string","example":"TRK123456789"},"carrierStatus":{"type":"string","nullable":true,"description":"Latest carrier status known to Stockhub. Null when tracking has not been fetched yet.","enum":["created","underway","delivered","not_delivered","failed","not_fetched",null],"example":"delivered"},"deliveredAt":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp of the latest carrier scan once carrierStatus is delivered; null otherwise.","example":"2025-12-03T14:22:00Z"},"events":{"type":"array","description":"All carrier scans known to Stockhub, oldest first. Empty until the tracking job has fetched scans.","items":{"type":"object","properties":{"type":{"type":"string","description":"Carrier-specific event category or code","example":"DELIVERED"},"status":{"type":"string","description":"Human-readable scan description as provided by the carrier","example":"Delivered to neighbour"},"timeStamp":{"type":"string","format":"date-time","example":"2025-12-03T14:22:00Z"}}}}}},"Webshop":{"type":"object","properties":{"id":{"type":"integer","description":"Webshop ID","example":42},"description":{"type":"string","description":"Human-readable label for the webshop","example":"Main Shopify Store"},"webshop_type":{"type":"string","description":"Webshop platform type","example":"shopify"},"state":{"type":"string","description":"Current state of the webshop integration","example":"active"},"relationId":{"type":"integer","description":"Relation this webshop belongs to","example":12},"externalId":{"type":"string","description":"External identifier","nullable":true},"shippingName":{"type":"string","description":"Default shipping name used for orders","nullable":true},"logoUrl":{"type":"string","description":"URL to the webshop logo","nullable":true},"syncOrders":{"type":"boolean","description":"Whether order sync is enabled"},"syncProducts":{"type":"boolean","description":"Whether product sync is enabled"},"syncStock":{"type":"boolean","description":"Whether stock sync is enabled"},"syncShipments":{"type":"boolean","description":"Whether shipment sync is enabled"},"snooze":{"type":"boolean","description":"Whether the webshop is snoozed"},"lastOrderSync":{"type":"string","format":"date-time","description":"Last successful order sync timestamp","nullable":true},"lastProductSync":{"type":"string","format":"date-time","description":"Last successful product sync timestamp","nullable":true},"lastStockSync":{"type":"string","format":"date-time","description":"Last successful stock sync timestamp","nullable":true},"lastCancelledOrderSync":{"type":"string","format":"date-time","description":"Last successful cancelled-order sync timestamp","nullable":true}}},"WebshopsListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"page":{"type":"integer"},"prev":{"type":"integer","nullable":true},"next":{"type":"integer","nullable":true},"totalItems":{"type":"integer"},"totalPages":{"type":"integer"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Webshop"}}}},"Relation":{"type":"object","properties":{"id":{"type":"integer","description":"Relation ID","example":12},"state":{"type":"string","description":"Current state of the relation","example":"active"},"name":{"type":"string","description":"Relation (company) name","example":"Acme BV"},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"website":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"house_nr":{"type":"string","nullable":true},"house_nr_extra":{"type":"string","nullable":true},"postal":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"kvk":{"type":"string","nullable":true},"externalId":{"type":"integer","nullable":true},"logoUrl":{"type":"string","nullable":true},"debtorNumber":{"type":"string","description":"Auto-assigned debtor number","nullable":true},"eoriNumber":{"type":"string","nullable":true},"vatNumber":{"type":"string","nullable":true},"invoiceEmail":{"type":"string","nullable":true},"invoiceName":{"type":"string","nullable":true},"invoiceReference":{"type":"string","nullable":true},"shippingName":{"type":"string","nullable":true},"cutoffTime":{"type":"string","nullable":true}}},"RelationUpdate":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"website":{"type":"string"},"street":{"type":"string"},"house_nr":{"type":"string"},"house_nr_extra":{"type":"string"},"postal":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"kvk":{"type":"string"},"externalId":{"type":"integer"},"eoriNumber":{"type":"string"},"vatNumber":{"type":"string"},"invoiceEmail":{"type":"string"},"invoiceName":{"type":"string"},"invoiceReference":{"type":"string"},"shippingName":{"type":"string"},"cutoffTime":{"type":"string"}}},"RelationsListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"page":{"type":"integer"},"prev":{"type":"integer","nullable":true},"next":{"type":"integer","nullable":true},"totalItems":{"type":"integer"},"totalPages":{"type":"integer"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Relation"}}}},"Product":{"type":"object","properties":{"sku":{"type":"string","description":"Stock Keeping Unit. Unique in Stockhub.","example":"0195950643787"},"barcodes":{"type":"array","description":"Array of product barcodes including product SKU","items":{"type":"string"},"example":["0195950643787","6973463100195"]},"description":{"type":"string","description":"Product description","example":"Apple iPhone 17 256GB White"},"length":{"type":"integer","nullable":true,"description":"Product length in mm","example":150},"width":{"type":"integer","nullable":true,"description":"Product width in mm","example":71},"height":{"type":"integer","nullable":true,"description":"Product height in mm","example":8},"weight":{"type":"integer","nullable":true,"description":"Product weight in grams","example":1717},"isVirtual":{"type":"boolean","description":"Whether the product is non-physical (consists of multiple other products)","example":false},"components":{"type":"array","description":"Components of a virtual product. Empty for physical products.","items":{"$ref":"#/components/schemas/ProductComponent"}},"safetyStock":{"type":"integer","description":"Safety stock level. When the stock of this product reaches below this level, notifications will be sent.","example":10},"hsCode":{"type":"string","nullable":true,"description":"Harmonized System code for customs","example":"57011010"},"externalId":{"type":"string","nullable":true,"description":"External identifier from third-party system","example":"123456"},"externalReference":{"type":"string","nullable":true,"description":"External reference number","example":"my-ref-123456"},"batchRequired":{"type":"boolean","description":"Whether batch tracking is required when receiving inbounds","example":false},"lotRequired":{"type":"boolean","description":"Whether lot tracking is required when receiving inbounds","example":false},"serialNumberRequired":{"type":"boolean","description":"Whether serial number tracking is required when receiving inbounds","example":false},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp","example":"2025-08-19T10:43:39.068Z"},"updatedAt":{"type":"string","format":"date-time","description":"Last modification timestamp","example":"2025-08-19T10:43:39.068Z"}}},"ProductComponent":{"type":"object","description":"One component of a virtual product (bundle)","properties":{"sku":{"type":"string","description":"SKU of the physical component product","example":"0195950643787"},"amount":{"type":"integer","minimum":1,"description":"How many of the component go into one unit of the virtual product","example":2}},"required":["sku","amount"]},"ProductCreate":{"type":"object","properties":{"relationId":{"type":"integer","description":"Relation that will own the product","example":12},"sku":{"type":"string","description":"Stock Keeping Unit. Unique in Stockhub.","example":"0195950643787"},"barcodes":{"type":"array","description":"Array of product barcodes including product SKU","items":{"type":"string"},"example":["0195950643787","6973463100195"]},"description":{"type":"string","description":"Product description","example":"Apple iPhone 17 256GB White"},"length":{"type":"integer","nullable":true,"description":"Product length in mm","example":150},"width":{"type":"integer","nullable":true,"description":"Product width in mm","example":71},"height":{"type":"integer","nullable":true,"description":"Product height in mm","example":8},"weight":{"type":"integer","nullable":true,"description":"Product weight in grams","example":1717},"safetyStock":{"type":"integer","description":"Safety stock level","example":10},"hsCode":{"type":"string","nullable":true,"description":"Harmonized System code for customs","example":"57011010"},"externalId":{"type":"string","nullable":true,"description":"External identifier from third-party system","example":"123456"},"externalReference":{"type":"string","nullable":true,"description":"External reference number","example":"my-ref-123456"},"isVirtual":{"type":"boolean","description":"Whether the product is a virtual product (bundle) made up of other products. Required (true) when components are supplied.","example":false},"components":{"type":"array","description":"Components of a virtual product as `{ sku, amount }` pairs. Only allowed together with isVirtual true.\nOn update this replaces the full component set; omit to leave components untouched, send an empty array to clear them.\nComponent skus must be existing physical products of the same relation. Duplicate skus are merged by summing their amounts.","items":{"$ref":"#/components/schemas/ProductComponent"}}},"required":["relationId","sku","description"]},"ProductUpdate":{"type":"object","properties":{"sku":{"type":"string","description":"Stock Keeping Unit. Unique in Stockhub.","example":"0195950643787"},"barcodes":{"type":"array","description":"Array of product barcodes including product SKU","items":{"type":"string"},"example":["0195950643787","6973463100195"]},"description":{"type":"string","description":"Product description","example":"Apple iPhone 17 256GB White"},"length":{"type":"integer","nullable":true,"description":"Product length in mm","example":150},"width":{"type":"integer","nullable":true,"description":"Product width in mm","example":71},"height":{"type":"integer","nullable":true,"description":"Product height in mm","example":8},"weight":{"type":"integer","nullable":true,"description":"Product weight in grams","example":1717},"safetyStock":{"type":"integer","description":"Safety stock level","example":10},"hsCode":{"type":"string","nullable":true,"description":"Harmonized System code for customs","example":"57011010"},"externalId":{"type":"string","nullable":true,"description":"External identifier from third-party system","example":"123456"},"externalReference":{"type":"string","nullable":true,"description":"External reference number","example":"my-ref-123456"},"relationId":{"type":"integer","description":"Optional. Provide to move the product to a different relation. Omit to keep the product on its current relation.","example":12},"countryOfOrigin":{"type":"string","nullable":true,"description":"Country of origin as ISO 3166-1 alpha-2 code","example":"NL"},"supplier":{"type":"string","nullable":true,"description":"Supplier name. Created when it does not exist yet for the relation.","example":"Acme Supplies"},"isVirtual":{"type":"boolean","description":"Whether the product is a virtual product (bundle) made up of other products. Required (true) when components are supplied.","example":false},"components":{"type":"array","description":"Components of a virtual product as `{ sku, amount }` pairs. Only allowed together with isVirtual true.\nOn update this replaces the full component set; omit to leave components untouched, send an empty array to clear them.\nComponent skus must be existing physical products of the same relation. Duplicate skus are merged by summing their amounts.","items":{"$ref":"#/components/schemas/ProductComponent"}}}},"Stock":{"type":"object","properties":{"sku":{"type":"string","description":"Stock Keeping Unit","example":"PROD-001"},"barcodes":{"type":"array","description":"Array of product barcodes including product SKU","items":{"type":"string"},"example":["0195950643787","6973463100195"]},"availableStock":{"type":"integer","description":"Available stock quantity. For a virtual product this is calculated live as the minimum over its components of floor(component available / amount).","example":50},"lastChanged":{"type":"string","format":"date-time","description":"Last modification timestamp","example":"2025-08-19T10:43:39.068Z"}}},"ProductsListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"page":{"type":"integer"},"prev":{"type":"integer","nullable":true},"next":{"type":"integer","nullable":true},"totalItems":{"type":"integer"},"totalPages":{"type":"integer"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}},"StockListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"page":{"type":"integer"},"prev":{"type":"integer","nullable":true},"next":{"type":"integer","nullable":true},"totalItems":{"type":"integer"},"totalPages":{"type":"integer"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Stock"}}}},"Inbound":{"type":"object","properties":{"state":{"type":"string","description":"Current state of the inbound","example":"active"},"barcode":{"type":"string","description":"Unique barcode identifier for the inbound","example":"INSL-1"},"reference":{"type":"string","description":"Own reference by customer","example":"RFM-123"},"shipmentDate":{"type":"string","format":"date-time","description":"Expected shipment date","example":"2025-05-06T00:00:00.000Z"},"receivedFromDate":{"type":"string","format":"date-time","nullable":true,"description":"Date of the first received product(s)","example":null},"receivedToDate":{"type":"string","format":"date-time","nullable":true,"description":"Date of the last received product(s)","example":null},"pallets":{"type":"integer","description":"Number of pallets","example":2},"colli":{"type":"integer","description":"Number of colli/packages","example":4},"amountOfShipments":{"type":"integer","description":"Number of shipments","example":0},"skuCount":{"type":"integer","description":"Number of unique SKUs","example":5},"itemCount":{"type":"integer","description":"Total number of items","example":255},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp","example":"2025-05-06T08:01:41.060Z"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp","example":"2025-06-06T08:40:52.113Z"},"inboundlines":{"type":"array","items":{"$ref":"#/components/schemas/InboundLine"}}}},"InboundLine":{"type":"object","properties":{"state":{"type":"string","description":"Current state of the inbound line","example":"active"},"amountForecasted":{"type":"integer","description":"Forecasted amount of products","example":30},"amountReceived":{"type":"integer","description":"Confirmed amount of received products that have been counted","example":0},"amountMoved":{"type":"integer","description":"Amount of products moved to stock and available for sale","example":0},"product":{"type":"object","properties":{"sku":{"type":"string","description":"Product SKU","example":"48583"},"description":{"type":"string","description":"Product description","example":"dayshake vogel afschrik lint 80 meter"},"barcode":{"type":"string","description":"Primary product barcode","example":"8719327545409"},"barcodes":{"type":"array","items":{"type":"string"},"description":"Array of all product barcodes","example":["8719327545409"]}}}}},"InboundCreate":{"type":"object","properties":{"relationId":{"type":"integer","description":"Relation that owns the inbound","example":12},"reference":{"type":"string","description":"Reference identifier for the inbound","example":"ASD"},"shipmentDate":{"type":"string","format":"date","description":"Expected shipment date","example":"2025-10-28"},"pallets":{"type":"integer","description":"Number of pallets","example":1},"colli":{"type":"integer","description":"Number of colli/packages","example":2},"inboundLines":{"type":"array","description":"Array of inbound line items","items":{"type":"object","properties":{"sku":{"type":"string","description":"Product SKU","example":"8719327477564"},"amount":{"type":"integer","description":"Quantity expected","example":1},"batch":{"type":"string","description":"Batch number for the product.\n**Required if the product has `batchRequired` set to true.**\nUsed for tracking products by batch for quality control and expiration management.","example":"BATCH-2025-001"},"lot":{"type":"string","description":"Lot number for the product.\n**Required if the product has `lotRequired` set to true.**\nUsed for tracking products by lot for quality control and expiration management.","example":"LOT-2025-001"},"bbDate":{"type":"string","format":"date","description":"Best before date for the product.\nOptional field that can be used with either batch or lot to track product expiration.","example":"2026-12-31"},"serialNumbers":{"type":"array","description":"Array of serial numbers for the product.\n**Required if the product has `serialNumberRequired` set to true.**\nThe number of serial numbers must match the `amount` field.","items":{"type":"string"},"example":["SN001","SN002"]}},"required":["sku","amount"]}},"shipments":{"type":"array","description":"Array of tracking numbers for shipments","items":{"type":"string"},"example":["TRACK123","TRACK456"]}},"required":["relationId","reference","shipmentDate","inboundLines"]},"InboundsListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"page":{"type":"integer"},"prev":{"type":"integer","nullable":true},"next":{"type":"integer","nullable":true},"totalItems":{"type":"integer"},"totalPages":{"type":"integer"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Inbound"}}}},"Return":{"type":"object","properties":{"reference":{"type":"string","description":"Return reference","example":"R-O25-6325"},"state":{"type":"string","description":"Current state of the return","example":"active"},"name":{"type":"string","description":"Customer name","example":"John Doe"},"email":{"type":"string","description":"Customer email","example":"john.doe@example.com"},"phone":{"type":"string","description":"Customer phone number","example":"+31612345678"},"remark":{"type":"string","nullable":true,"description":"General remark for the return","example":"Customer changed mind"},"internalRemark":{"type":"string","nullable":true,"description":"Internal-only note on the return, not shown to the customer","example":"Refund approved by support"},"trackandtrace":{"type":"string","nullable":true,"description":"Tracking number for return shipment","example":"3SDEVC123456789"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp","example":"2025-08-19T10:43:39.068Z"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp","example":"2025-08-19T10:43:39.068Z"},"order":{"type":"object","nullable":true,"description":"Associated order information","properties":{"id":{"type":"integer","example":123},"barcode":{"type":"string","example":"O25-6325"},"webshopreference":{"type":"string","example":"WS-ORDER-789"}}},"returnlines":{"type":"array","description":"Array of return line items","items":{"type":"object","properties":{"amount":{"type":"integer","description":"Quantity being returned","example":2},"remark":{"type":"string","description":"Remark or reason for return","example":"Defective item"},"acceptedCount":{"type":"integer","nullable":true,"description":"Number of items accepted","example":1},"rejectedCount":{"type":"integer","nullable":true,"description":"Number of items rejected","example":1},"state":{"type":"string","description":"State of the return line","example":"active"},"externalReturnReason":{"type":"string","nullable":true,"description":"External return reason provided by customer","example":"Product arrived damaged"},"returnreasonDescription":{"type":"string","nullable":true,"description":"Description of the return reason from the returnreasons table","example":"Defective product"},"rejectionReason":{"type":"string","nullable":true,"description":"Reason recorded by the warehouse when (part of) the line was rejected. Null when nothing was rejected or no reason was given.","example":"Product used"},"photos":{"type":"array","description":"Array of photo URLs for this return line","items":{"type":"string","format":"uri"},"example":["https://storage.blob.core.windows.net/returns/photo1.jpg"]},"product":{"type":"object","properties":{"sku":{"type":"string","description":"Product SKU","example":"0195950643787"},"description":{"type":"string","description":"Product description","example":"Apple iPhone 17 256GB White"},"barcodes":{"type":"array","description":"Array of product barcodes including SKU","items":{"type":"string"},"example":["0195950643787","6973463100195"]}}}}}}}},"ReturnCreate":{"type":"object","properties":{"relationId":{"type":"integer","description":"Relation that owns the return","example":12},"webshopId":{"type":"integer","description":"Optional. Webshop the return belongs to. When supplied, must belong to the given relation.","example":42},"orderId":{"type":"integer","description":"ID of the order this return is for. Provide either `orderId` OR `orderBarcode`.","example":123},"orderBarcode":{"type":"string","description":"Barcode of the order this return is for. Provide either `orderId` OR `orderBarcode`. When supplied, the server resolves it to the orderId within the relation.","example":"ORD-2025-00123"},"name":{"type":"string","description":"Customer name","example":"John Doe"},"email":{"type":"string","format":"email","description":"Customer email","example":"john.doe@example.com"},"reference":{"type":"string","description":"Optional reference for the return","example":"RET-2025-001"},"remark":{"type":"string","nullable":true,"description":"General remark for the return","example":"Customer changed mind"},"returnLines":{"type":"array","description":"Array of return line items","items":{"type":"object","properties":{"barcode":{"type":"string","description":"Product barcode or SKU.\nCan match either the product SKU or any barcode in the product's barcodes array.","example":"0195950643787"},"amount":{"type":"integer","description":"Quantity being returned","example":2},"remark":{"type":"string","description":"Remark or reason for return","example":"Defective item"},"returnreasonId":{"type":"integer","description":"ID of the return reason (optional)","example":5}},"required":["barcode","amount"]}}},"required":["relationId","name","email","returnLines"]},"ReturnUpdate":{"type":"object","description":"Fields to update on an existing return. All fields are optional; only the\nfields supplied in the request are updated.","properties":{"remark":{"type":"string","nullable":true,"description":"General remark for the return","example":"Customer changed mind"},"internalRemark":{"type":"string","nullable":true,"description":"Internal-only note on the return, not shown to the customer","example":"Refund approved by support"},"trackandtrace":{"type":"string","nullable":true,"description":"Tracking number for the return shipment","example":"3SDEVC123456789"},"name":{"type":"string","description":"Customer name","example":"John Doe"},"email":{"type":"string","format":"email","description":"Customer email","example":"john.doe@example.com"},"phone":{"type":"string","description":"Customer phone number","example":"+31612345678"}}},"ReturnsListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"page":{"type":"integer"},"prev":{"type":"integer","nullable":true},"next":{"type":"integer","nullable":true},"totalItems":{"type":"integer"},"totalPages":{"type":"integer"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Return"}}}},"InvoiceLine":{"type":"object","properties":{"id":{"type":"integer","description":"InvoiceLine ID","example":1},"state":{"type":"string","description":"State of the invoice line","example":"active"},"amount":{"type":"string","description":"Amount (quantity)","example":"10.0000"},"price":{"type":"string","description":"Price per unit","example":"5.0000"},"description":{"type":"string","description":"Description of the line item","example":"Product ABC"},"ledger":{"type":"string","description":"Ledger code","example":"3000","nullable":true}}},"Invoice":{"type":"object","properties":{"id":{"type":"integer","description":"Invoice ID","example":42},"state":{"type":"string","description":"Invoice state","example":"finalized"},"date":{"type":"string","format":"date-time","description":"Invoice date","example":"2025-01-15T10:00:00Z","nullable":true},"number":{"type":"integer","description":"Invoice number","example":1001,"nullable":true},"startDate":{"type":"string","format":"date","description":"Start date of invoice period","example":"2025-01-01"},"endDate":{"type":"string","format":"date","description":"End date of invoice period","example":"2025-01-31","nullable":true},"totalLines":{"type":"integer","description":"Total number of lines","example":5},"totalPrice":{"type":"string","description":"Total price","example":"250.00"},"externalId":{"type":"string","description":"External invoice ID","example":"EXT-12345","nullable":true},"externalReference":{"type":"string","description":"External reference","example":"REF-XYZ","nullable":true},"paymentUrl":{"type":"string","description":"Payment URL","example":"https://example.com/pay/invoice/42","nullable":true},"viewUrl":{"type":"string","description":"View URL","example":"https://example.com/invoices/42","nullable":true},"relationId":{"type":"integer","description":"Relation ID","example":12},"invoiceLines":{"type":"array","description":"Associated invoice lines (only on GET /:id)","items":{"$ref":"#/components/schemas/InvoiceLine"}}}},"InvoicesListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"page":{"type":"integer"},"prev":{"type":"integer","nullable":true},"next":{"type":"integer","nullable":true},"totalItems":{"type":"integer"},"totalPages":{"type":"integer"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}}}},"WebhookSubscription":{"type":"object","properties":{"id":{"type":"integer","description":"Subscription id"},"url":{"type":"string","format":"uri","description":"HTTPS endpoint events are delivered to","example":"https://example.com/webhooks/stockhub"},"events":{"type":"array","description":"Event types this subscription receives","items":{"type":"string","enum":["order.created","order.updated","order.status_changed","order.cancelled"]}},"relationId":{"type":"integer","nullable":true,"description":"Relation this subscription is scoped to. Null when the subscription (created by a catalog-wide key) receives events for every relation.","example":12},"state":{"type":"string","description":"Subscription state","example":"active"},"createdAt":{"type":"string","format":"date-time","description":"When the subscription was created"}}},"WebhookSubscriptionWithSecret":{"description":"A newly created subscription, including its signing secret.","allOf":[{"$ref":"#/components/schemas/WebhookSubscription"},{"type":"object","properties":{"secret":{"type":"string","description":"Returned only on creation — store it now. Used to verify the X-Stockhub-Signature header on delivered events; it cannot be retrieved again afterwards."}}}]},"WebhookEventPayload":{"type":"object","description":"Body of every webhook POST. Signed headers: X-Stockhub-Event, X-Stockhub-Event-Id, X-Stockhub-Timestamp (unix seconds) and X-Stockhub-Signature: sha256=<hex>, where hex is HMAC-SHA256(secret, \"<timestamp>.<raw body>\"). Verify with a timing-safe compare and reject timestamps older than your tolerance (e.g. 5 minutes) to prevent replays.\n","properties":{"id":{"type":"string","format":"uuid","description":"Unique event id (identical across delivery retries)"},"type":{"type":"string","enum":["order.created","order.updated","order.status_changed","order.cancelled"]},"timestamp":{"type":"string","format":"date-time","description":"Moment the event occurred (not the delivery attempt)"},"data":{"type":"object","properties":{"order":{"type":"object","description":"Same shape as an item of GET /orders. `status` is the real fulfilment order status: [open, concept, snooze, blocked, replenish, backordered, picking_in_progress, joker, picked, fullypicked, action_required_customer, action_required_warehouse, shipped, cancelled, deleted]. The internal `echeck`/`echeckpaused` packing states never appear here — both are reported as `fullypicked` because echeck is a transient packing block while the order is being packed.\n","properties":{"status":{"type":"string","enum":["open","concept","snooze","blocked","replenish","backordered","picking_in_progress","joker","picked","fullypicked","action_required_customer","action_required_warehouse","shipped","cancelled","deleted"]}}},"previousStatus":{"type":"string","description":"Present only on order.status_changed"}}}}},"PaginatedSuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"},"page":{"type":"integer"},"prev":{"type":"integer"},"next":{"type":"integer"},"totalItems":{"type":"integer"},"totalPages":{"type":"integer"},"data":{"type":"array","items":{"type":"object"}}}}}},"paths":{"/me":{"get":{"summary":"Identity and rights of the calling key","description":"Returns the identity, catalog, and rights of the calling API key.\nAvailable to any authenticated key — no specific right required.\n","tags":["Identity"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/orders":{"get":{"summary":"List orders for a relation","description":"List orders (paginated) for the given relation. Optionally narrow by webshopId.","tags":["Orders"],"parameters":[{"name":"relationId","in":"query","required":false,"description":"Relation to list orders for (optional; if omitted, lists across the entire catalog)","schema":{"type":"integer","example":12}},{"name":"webshopId","in":"query","required":false,"description":"Optional webshop to narrow the listing. Must belong to the given relation (if provided).","schema":{"type":"integer","example":42}},{"name":"page","in":"query","required":false,"description":"Results page index","schema":{"type":"integer","default":1,"minimum":1}},{"name":"size","in":"query","required":false,"description":"Results per page","schema":{"type":"integer","default":50,"minimum":1,"maximum":250}},{"name":"barcode","in":"query","required":false,"description":"Unique barcode of the order (exact match)","schema":{"type":"string"}},{"name":"reference","in":"query","required":false,"description":"Webshop reference (full-text search)","schema":{"type":"string"}},{"name":"name","in":"query","required":false,"description":"Delivery name (full-text search)","schema":{"type":"string"}},{"name":"plannedFromDate","in":"query","required":false,"description":"Planned after this date","schema":{"type":"string","format":"date-time"}},{"name":"plannedToDate","in":"query","required":false,"description":"Planned before this date","schema":{"type":"string","format":"date-time"}},{"name":"state","in":"query","required":false,"description":"Order state (comma separated)","schema":{"type":"string","example":"open,shipped"}}],"responses":{"200":{"description":"Paginated order list","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedSuccessResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrderSummary"}}}}]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (e.g. webshop does not belong to relation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/orders/add":{"post":{"summary":"Create a new order","description":"Create a new order for the given relation and webshop. `relationId` and `webshopId` are required as top-level fields in the request body. The request MUST be sent with the header `Content-Type: application/json` — without it the body is not parsed and the API responds with `400 Missing relationId` or `400 Missing webshopId`, even if the JSON body is present.\n","tags":["Orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderCreate"}}}},"responses":{"201":{"description":"Order created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrderSummary"}}}]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (e.g. webshop does not belong to relation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/orders/{barcode}":{"get":{"summary":"Get one order with per-orderline quantities","description":"Full detail of a single order: address, relation, weights, shipments and the orderlines with their fulfilment quantities — `ordered` (requested amount), `picked` (completed picks), `shipped` (shipped amount) and `backorder` (amount currently in backorder). `state` is the real fulfilment order state.\n","tags":["Orders"],"parameters":[{"name":"barcode","in":"path","required":true,"description":"Order barcode","schema":{"type":"string","example":"O25-6324"}},{"name":"relationId","in":"query","required":false,"description":"Scope the lookup to one relation","schema":{"type":"integer"}}],"responses":{"200":{"description":"The order","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"barcode":{"type":"string","example":"O25-6324"},"state":{"type":"string","example":"picking_in_progress"},"webshopreference":{"type":"string"},"externalId":{"type":"string","nullable":true},"channel":{"type":"string","nullable":true,"description":"Description of the webshop the order came from"},"date_planned":{"type":"string","format":"date-time","nullable":true},"date_sent":{"type":"string","format":"date-time","nullable":true},"totalCost":{"type":"number","nullable":true},"totalWeight":{"type":"number","nullable":true,"description":"Total weight of the order"},"volume":{"type":"number","nullable":true},"maxLength":{"type":"number","nullable":true},"stream":{"type":"string","nullable":true,"readOnly":true,"description":"Name of the stream the order is assigned to. Read-only."},"deliveryMethod":{"$ref":"#/components/schemas/DeliveryMethod"},"relation":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"shippingAdress":{"type":"object","nullable":true,"properties":{"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"addressLine1":{"type":"string","nullable":true},"addressLine2":{"type":"string","nullable":true},"postalCode":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"countryCode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true}}},"orderlines":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","nullable":true},"product":{"type":"string","nullable":true,"description":"Product description"},"price":{"type":"number","nullable":true},"ordered":{"type":"integer","description":"Requested amount on the orderline"},"picked":{"type":"integer","description":"Amount picked (completed picks)"},"shipped":{"type":"integer","description":"Amount shipped"},"backorder":{"type":"integer","description":"Amount currently in backorder"}}}},"shipments":{"type":"array","items":{"type":"object","properties":{"trackingNumber":{"type":"string","nullable":true},"shipperType":{"type":"string","nullable":true},"shipmentStatus":{"type":"string","nullable":true,"enum":["created","underway","delivered","not_delivered","failed","not_fetched"]},"shipmentDate":{"type":"string","format":"date-time","nullable":true},"dimensions":{"$ref":"#/components/schemas/ShipmentDimensions"}}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing orders:read)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Correct the shipping address of an order","description":"Update (only) the shipping address of an existing order, for example after an address validation failure. The address is revalidated immediately: when it becomes valid the order automatically leaves its error state, and the webshop/platform link of the order is preserved. Orders that are already shipped or cancelled cannot be modified. Send `skipValidation: true` to release an order whose address cannot be validated (e.g. no house number). Requires the orders:write right.\n","tags":["Orders"],"parameters":[{"name":"barcode","in":"path","required":true,"description":"Order barcode","schema":{"type":"string","example":"O25-6324"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderAddressUpdate"}}}},"responses":{"200":{"description":"Address updated; returns the new order state and any remaining validation error","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"barcode":{"type":"string","example":"O25-6324"},"state":{"type":"string","example":"open"},"errorReason":{"type":"string","nullable":true},"addressSuggestion":{"type":"string","nullable":true}}}}}]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/orders/{barcode}/cancel":{"post":{"summary":"Cancel an order","description":"Cancel the order with the given barcode. Orders in state `shipped`, `picking_in_progress`, `cancelled` or `deleted` cannot be cancelled, and orders of a blocked relation are rejected. Cancelling releases reserved stock, unwinds open picking and replenish lines and emits the `order.cancelled` webhook event. `relationId` is required as a top-level field in the request body and must match the relation that owns the order. The request MUST be sent with the header `Content-Type: application/json` — without it the body is not parsed and the API responds with `400 Missing relationId`, even if the JSON body is present.\n","tags":["Orders"],"parameters":[{"name":"barcode","in":"path","required":true,"description":"Barcode of the order to cancel","schema":{"type":"string","example":"O123-456"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"relationId":{"type":"integer","description":"Relation that owns the order","example":12}},"required":["relationId"]}}}},"responses":{"200":{"description":"Order cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"barcode":{"type":"string","example":"O123-456"},"state":{"type":"string","example":"cancelled"}}}}}},"400":{"description":"Validation error (missing relationId, blocked relation, or order state does not allow cancellation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing orders:write right)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Order not found for the given barcode and relation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Order was modified concurrently and could not be cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/orders/{barcode}/fields":{"get":{"summary":"Get the custom field values of an order","description":"Key-value custom fields on the order (orderfields). `fields` is the flat name→value map; `details` adds each field's valueType. Requires the orders:read right.\n","tags":["Order fields"],"parameters":[{"name":"barcode","in":"path","required":true,"schema":{"type":"string","example":"O25-6324"}}],"responses":{"200":{"description":"The order's custom field values","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"fields":{"type":"object","additionalProperties":{"type":"string"},"example":{"Bezorgstatus":"delivered","Priority":"7"}},"details":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"valueType":{"type":"string","enum":["text","number","boolean","list"]},"value":{"type":"string"}}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing orders:read)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Upsert custom field values on an order","description":"Upserts only the keys provided in `fields`; other stored values are left untouched. A `null` value removes that field's value from the order. Every key must match an existing orderfield definition (see GET /orderfields) — unknown keys reject the whole request with a 400, as do values that don't match the field's valueType (number must be numeric, boolean true/false, list value must be one of the field's listValues). A successful write emits the order.updated webhook. Requires the orders:write right.\n","tags":["Order fields"],"parameters":[{"name":"barcode","in":"path","required":true,"schema":{"type":"string","example":"O25-6324"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fields"],"properties":{"fields":{"type":"object","additionalProperties":{"nullable":true},"example":{"Bezorgstatus":"delivered","Priority":7,"Obsolete":null}}}}}}},"responses":{"200":{"description":"Updated field values (same shape as GET)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"details":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"valueType":{"type":"string"},"value":{"type":"string"}}}}}}}}},"400":{"description":"Unknown field name or value does not match the field's valueType","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing orders:write)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/orderfields":{"get":{"summary":"List available custom field definitions","description":"Read-only list of the orderfield definitions that can be written via PUT /orders/{barcode}/fields. Definitions are managed in the WMS.\n","tags":["Order fields"],"responses":{"200":{"description":"Field definitions","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"orderfields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Bezorgstatus"},"valueType":{"type":"string","enum":["text","number","boolean","list"]},"listValues":{"type":"array","items":{"type":"string"}}}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing orders:read)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/orders/{barcode}/shipments":{"get":{"summary":"Get shipments for an order","description":"Retrieve all active shipments for the given order barcode.","tags":["Orders"],"parameters":[{"name":"barcode","in":"path","required":true,"description":"Order barcode","schema":{"type":"string","example":"O25-6324"}},{"name":"relationId","in":"query","required":false,"description":"Relation that owns the order (optional; barcode is unique within the catalog)","schema":{"type":"integer","example":12}},{"name":"webshopId","in":"query","required":false,"description":"Webshop the order belongs to (optional; barcode is unique within the catalog)","schema":{"type":"integer","example":42}}],"responses":{"200":{"description":"Shipments for the order","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentListItem"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (e.g. webshop does not belong to relation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/orderlines":{"get":{"summary":"List orderlines with fulfilment quantities","description":"Paginated, filterable list of orderlines flattened with their parent-order context and per-line quantities (`ordered`, `picked`, `shipped`, `backorder`). Filter by orderline `state` (comma-separated for multiple), product `sku`, and the parent order's planned date range. Newest orders first.\n","tags":["Orderlines"],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1}},{"name":"size","in":"query","required":false,"schema":{"type":"integer"}},{"name":"state","in":"query","required":false,"description":"Orderline state; comma-separated for multiple (e.g. \"active,backordered\")","schema":{"type":"string"}},{"name":"sku","in":"query","required":false,"description":"Filter on product SKU (exact match)","schema":{"type":"string"}},{"name":"plannedFromDate","in":"query","required":false,"description":"Filter on the parent order's date_planned (after this date)","schema":{"type":"string","format":"date-time"}},{"name":"plannedToDate","in":"query","required":false,"description":"Filter on the parent order's date_planned (before this date)","schema":{"type":"string","format":"date-time"}},{"name":"relationId","in":"query","required":false,"description":"Scope to one relation (required behaviour for relation-scoped keys)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Paginated orderlines","content":{"application/json":{"schema":{"type":"object","properties":{"totalItems":{"type":"integer"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Orderline id"},"barcode":{"type":"string","description":"Barcode of the parent order","example":"O25-6324"},"webshopreference":{"type":"string","nullable":true},"orderState":{"type":"string","description":"Current state of the parent order","example":"picking_in_progress"},"date_planned":{"type":"string","format":"date-time","nullable":true},"sku":{"type":"string","nullable":true},"product":{"type":"string","nullable":true,"description":"Product description"},"price":{"type":"number","nullable":true},"state":{"type":"string","description":"Orderline state","example":"active"},"ordered":{"type":"integer","description":"Requested amount on the orderline"},"picked":{"type":"integer","description":"Amount picked (completed picks)"},"shipped":{"type":"integer","description":"Amount shipped"},"backorder":{"type":"integer","description":"Amount currently in backorder"}}}},"totalPages":{"type":"integer"},"page":{"type":"integer"},"prev":{"type":"integer","nullable":true},"next":{"type":"integer","nullable":true},"success":{"type":"boolean"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing orders:read)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/orderlines/backorders":{"get":{"summary":"List open backorders per orderline","description":"Paginated list of orderlines with an open backorder (`backorder > 0`) on orders that are not cancelled, deleted or shipped. Newest orders first.\n","tags":["Orderlines"],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1}},{"name":"size","in":"query","required":false,"schema":{"type":"integer"}},{"name":"relationId","in":"query","required":false,"description":"Scope to one relation (required behaviour for relation-scoped keys)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Paginated backorder lines","content":{"application/json":{"schema":{"type":"object","properties":{"totalItems":{"type":"integer"},"data":{"type":"array","items":{"type":"object","properties":{"barcode":{"type":"string","description":"Barcode of the order the line belongs to","example":"O25-6324"},"webshopreference":{"type":"string","nullable":true},"state":{"type":"string","description":"Current order state","example":"backordered"},"date_planned":{"type":"string","format":"date-time","nullable":true},"sku":{"type":"string","nullable":true},"product":{"type":"string","nullable":true,"description":"Product description"},"ordered":{"type":"integer","description":"Requested amount on the orderline"},"backorder":{"type":"integer","description":"Amount currently in backorder"}}}},"totalPages":{"type":"integer"},"page":{"type":"integer"},"prev":{"type":"integer","nullable":true},"next":{"type":"integer","nullable":true},"success":{"type":"boolean"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing orders:read)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/shipments":{"get":{"summary":"List shipments","description":"List shipments (paginated) across all orders. Filters allow\nscoping to a specific relation and/or webshop. \n\nThe per-order endpoint `GET /fulfilment/orders/{barcode}/shipments` returns\nthe SAME per-shipment shape but for a single order at a time.\n","tags":["Shipments"],"parameters":[{"name":"page","in":"query","required":false,"description":"Results page index","schema":{"type":"integer","default":1,"minimum":1}},{"name":"size","in":"query","required":false,"description":"Results per page","schema":{"type":"integer","default":50,"minimum":1,"maximum":250}},{"name":"fromDate","in":"query","required":false,"description":"ISO 8601 date/datetime - filters shipments with shipmentDate >= this value","schema":{"type":"string","format":"date-time","example":"2025-01-01T00:00:00Z"}},{"name":"trackingNumber","in":"query","required":false,"description":"Exact tracking number match","schema":{"type":"string","example":"TRK123456789"}},{"name":"orderBarcode","in":"query","required":false,"description":"Exact order barcode match (joins through order)","schema":{"type":"string","example":"O25-6324"}},{"name":"state","in":"query","required":false,"description":"Shipment state filter (defaults to active)","schema":{"type":"string","example":"active"}},{"name":"relationId","in":"query","required":false,"description":"Filter shipments to a specific relation","schema":{"type":"integer","example":12}},{"name":"webshopId","in":"query","required":false,"description":"Filter shipments whose underlying order belongs to this webshopCredentials","schema":{"type":"integer","example":42}}],"responses":{"200":{"description":"Paginated list of shipments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentsListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (e.g. webshop does not belong to relation, or missing orders:read)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/shipments/{trackingNumber}/status":{"get":{"summary":"Get carrier status and scan history for a shipment","description":"Returns the latest carrier status plus every carrier scan (event) Stockhub has stored for the shipment with the given tracking number. Scans are collected periodically by the tracking job for trackable carriers.\n","tags":["Shipments"],"parameters":[{"name":"trackingNumber","in":"path","required":true,"description":"Tracking number of the shipment","schema":{"type":"string","example":"TRK123456789"}},{"name":"relationId","in":"query","required":false,"description":"Relation that owns the shipment's order (optional; falls back to the token's relation)","schema":{"type":"integer","example":12}},{"name":"webshopId","in":"query","required":false,"description":"Webshop the shipment's order belongs to (optional)","schema":{"type":"integer","example":42}}],"responses":{"200":{"description":"Carrier status and scan history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentStatusResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (e.g. webshop does not belong to relation, or missing orders:read)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Shipment not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/relations":{"get":{"summary":"List relations for the fulfillment","description":"Returns a paginated list of relations.\n","tags":["Relations"],"parameters":[{"name":"page","in":"query","required":false,"description":"Results page index","schema":{"type":"integer","default":1,"minimum":1}},{"name":"size","in":"query","required":false,"description":"Results per page","schema":{"type":"integer","default":50,"minimum":1,"maximum":250}}],"responses":{"200":{"description":"Paginated list of relations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelationsListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing relations:read)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/relations/{id}":{"put":{"summary":"Update a relation","description":"Update an existing relation.\n","tags":["Relations"],"parameters":[{"name":"id","in":"path","required":true,"description":"Relation ID","schema":{"type":"integer","example":12}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelationUpdate"}}}},"responses":{"200":{"description":"Relation updated","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Relation"}}}]}}}},"400":{"description":"Validation error or forbidden field in body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing relations:write)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Relation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/webshops":{"get":{"summary":"List webshops in the catalog","description":"Returns a paginated list of webshops.\nOptionally filter by relationId.\n","tags":["Webshops"],"parameters":[{"name":"relationId","in":"query","required":false,"description":"Optional relation filter; when omitted, lists across the entire catalog","schema":{"type":"integer","example":12}},{"name":"page","in":"query","required":false,"description":"Results page index","schema":{"type":"integer","default":1,"minimum":1}},{"name":"size","in":"query","required":false,"description":"Results per page","schema":{"type":"integer","default":50,"minimum":1,"maximum":250}}],"responses":{"200":{"description":"Paginated list of webshops","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebshopsListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing webshops:read)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/products":{"get":{"summary":"List products for a relation","description":"Returns a paginated list of products for the given relation.\n","tags":["Products"],"parameters":[{"name":"relationId","in":"query","required":false,"description":"Optional. Filter products to a single relation. When omitted, lists products across all relations in the catalog.","schema":{"type":"integer","example":12}},{"name":"page","in":"query","required":false,"description":"Results page index","schema":{"type":"integer","default":1,"minimum":1}},{"name":"size","in":"query","required":false,"description":"Results per page","schema":{"type":"integer","default":50,"minimum":1,"maximum":250}},{"name":"barcode","in":"query","required":false,"description":"Filter on the barcode of a product (any, including SKU). Accepts a single barcode or a comma-separated list (e.g. `A,B,C`) to match any of them.","schema":{"type":"string","example":"0195950643787"}},{"name":"lastChangedSince","in":"query","required":false,"description":"Only return products changed at or after this timestamp","schema":{"type":"string","format":"date-time","example":"2025-08-19T10:43:39.068Z"}}],"responses":{"200":{"description":"Paginated list of products","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductsListResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing products:read or unknown relation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No products found for the given filters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/products/stock":{"get":{"summary":"List stock levels for a relation's products","description":"Returns paginated stock levels for the given products.\n","tags":["Products"],"parameters":[{"name":"relationId","in":"query","required":false,"description":"Optional. Filter stock to a single relation. When omitted, lists stock across all relations in the catalog.","schema":{"type":"integer","example":12}},{"name":"page","in":"query","required":false,"description":"Results page index","schema":{"type":"integer","default":1,"minimum":1}},{"name":"size","in":"query","required":false,"description":"Results per page","schema":{"type":"integer","default":50,"minimum":1,"maximum":250}},{"name":"barcode","in":"query","required":false,"description":"Filter on the barcode of a product (any, including SKU). Accepts a single barcode or a comma-separated list (e.g. `A,B,C`) to match any of them.","schema":{"type":"string","example":"0195950643787"}},{"name":"lastChangedSince","in":"query","required":false,"description":"Only return stock changed at or after this timestamp","schema":{"type":"string","format":"date-time","example":"2025-08-19T10:43:39.068Z"}}],"responses":{"200":{"description":"Paginated list of stock levels","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockListResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing products:read or unknown relation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No products found for the given filters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/products/{sku}/stock":{"get":{"summary":"Get stock level for a single SKU","description":"Returns the available stock level for the given SKU. \n","tags":["Products"],"parameters":[{"name":"sku","in":"path","required":true,"description":"Product SKU","schema":{"type":"string","example":"0195950643787"}},{"name":"relationId","in":"query","required":false,"description":"Optional. Scope the SKU lookup to a single relation. When omitted, searches the SKU across all relations in the catalog (first match wins).","schema":{"type":"integer","example":12}}],"responses":{"200":{"description":"Stock level for the SKU","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Stock"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing products:read or unknown relation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/products/{sku}/locations":{"get":{"summary":"Get the warehouse locations of a product","description":"All warehouse locations coupled to the product through its stock records, with per-location quantities. There is no single \"primary\" location: `general`-type locations are the pick locations and are listed first, followed by `bulk` and other types. Virtual products return an empty list.\n","tags":["Products"],"parameters":[{"name":"sku","in":"path","required":true,"schema":{"type":"string","example":"SKU-123"}},{"name":"relationId","in":"query","required":false,"description":"Scope the lookup to one relation (required behaviour for relation-scoped keys)","schema":{"type":"integer"}}],"responses":{"200":{"description":"The product's locations, pick (general) locations first","content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string","example":"SKU-123"},"locations":{"type":"array","items":{"type":"object","properties":{"location":{"type":"string","nullable":true,"description":"Location code","example":"A-01-02"},"barcode":{"type":"string","nullable":true},"type":{"type":"string","nullable":true,"enum":["general","bulk","echeck","link","temp","transition","returns"],"description":"Location type; general = pick location"},"warehouse":{"type":"string","nullable":true,"description":"Warehouse name"},"quantity":{"type":"integer","description":"Total quantity on this location"},"available":{"type":"integer","description":"Available (unreserved) quantity on this location"}}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing products:read)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/products/add":{"post":{"summary":"Create a product","description":"Creates a product for the given relation.\n`relationId` is required in the request body.\n","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductCreate"}}}},"responses":{"201":{"description":"Product created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}}}]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing products:write or unknown relation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"SKU or barcode conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/products/{sku}":{"put":{"summary":"Update a product by SKU","description":"Update an existing product identified by SKU. The product is located by searching\nthe catalog. To move the product to a different relation, include `relationId` in\nthe request body.\n","tags":["Products"],"parameters":[{"name":"sku","in":"path","required":true,"description":"Product SKU","schema":{"type":"string","example":"0195950643787"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductUpdate"}}}},"responses":{"200":{"description":"Product updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing products:write or unknown relation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"SKU or barcode conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/inbounds":{"get":{"summary":"List inbounds for a relation","description":"List inbounds (paginated). Optionally narrow by relationId. Inbounds are scoped to products and relations only; they are not bound to a webshop.","tags":["Inbounds"],"parameters":[{"name":"relationId","in":"query","required":false,"description":"Relation to list inbounds for (optional; if omitted, lists across the entire catalog)","schema":{"type":"integer","example":12}},{"name":"page","in":"query","required":false,"description":"Results page index","schema":{"type":"integer","default":1,"minimum":1}},{"name":"size","in":"query","required":false,"description":"Results per page","schema":{"type":"integer","default":50,"minimum":1,"maximum":250}},{"name":"barcode","in":"query","required":false,"description":"Unique barcode of the inbound (exact match)","schema":{"type":"string"}},{"name":"reference","in":"query","required":false,"description":"Inbound reference (full-text search)","schema":{"type":"string"}},{"name":"state","in":"query","required":false,"description":"Inbound state (comma separated)","schema":{"type":"string","example":"active,fullyreceived"}},{"name":"lastChangedSince","in":"query","required":false,"description":"Only return inbounds changed at or after this timestamp","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Paginated inbound list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundsListResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (e.g. webshop does not belong to relation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/inbounds/add":{"post":{"summary":"Create a new inbound","description":"Create a new inbound for the given relation. Inbounds are scoped to products and relations only; they are not bound to a webshop. `relationId` is required in the request body.","tags":["Inbounds"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundCreate"}}}},"responses":{"201":{"description":"Inbound created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"barcode":{"type":"string","description":"Barcode of the created inbound","example":"INSL-1"},"message":{"type":"string","example":"Inbound created successfully"}}}]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (e.g. webshop does not belong to relation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/inbounds/{barcode}":{"delete":{"summary":"Cancel an inbound","description":"Cancel an existing inbound by barcode.","tags":["Inbounds"],"parameters":[{"name":"barcode","in":"path","required":true,"description":"Inbound barcode","schema":{"type":"string","example":"INSL-1"}},{"name":"relationId","in":"query","required":false,"description":"Relation that owns the inbound (optional; barcode is unique within the catalog)","schema":{"type":"integer","example":12}}],"responses":{"200":{"description":"Inbound cancelled successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"message":{"type":"string","example":"Inbound cancelled successfully"}}}]}}}},"400":{"description":"Inbound cannot be cancelled anymore","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (e.g. webshop does not belong to relation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Inbound not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/returns":{"get":{"summary":"List returns for a relation","description":"List returns (paginated). Optionally narrow by webshopId or relationId.","tags":["Returns"],"parameters":[{"name":"relationId","in":"query","required":false,"description":"Relation to list returns for (optional; if omitted, lists across the entire catalog)","schema":{"type":"integer","example":12}},{"name":"webshopId","in":"query","required":false,"description":"Optional webshop to narrow the listing. Must belong to the given relation (if provided).","schema":{"type":"integer","example":42}},{"name":"page","in":"query","required":false,"description":"Results page index","schema":{"type":"integer","default":1,"minimum":1}},{"name":"size","in":"query","required":false,"description":"Results per page","schema":{"type":"integer","default":50,"minimum":1,"maximum":250}},{"name":"reference","in":"query","required":false,"description":"Return reference (full-text search)","schema":{"type":"string"}},{"name":"name","in":"query","required":false,"description":"Customer name (full-text search)","schema":{"type":"string"}},{"name":"barcode","in":"query","required":false,"description":"Product barcode or SKU to filter return lines","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated return list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnsListResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (e.g. webshop does not belong to relation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/returns/add":{"post":{"summary":"Create a new return","description":"Create a new return for the given relation. `relationId` is required in the request body.\n`webshopId` is optional; when supplied it must belong to the relation.\nThe order this return is for can be specified by either `orderId` OR `orderBarcode` in the body.\n","tags":["Returns"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnCreate"}}}},"responses":{"201":{"description":"Return created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"reference":{"type":"string","description":"Reference of the created return","example":"R-O25-6325"},"message":{"type":"string","example":"Return created successfully"}}}]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (e.g. webshop does not belong to relation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/returns/{reference}":{"put":{"summary":"Update a return","description":"Update an existing return by reference. Only the fields supplied in the\nrequest body are updated; omitted fields are left unchanged.\n","tags":["Returns"],"parameters":[{"name":"reference","in":"path","required":true,"description":"Return reference","schema":{"type":"string","example":"R-O25-6325"}},{"name":"relationId","in":"query","required":false,"description":"Relation that owns the return (optional; reference is unique within the catalog)","schema":{"type":"integer","example":12}},{"name":"webshopId","in":"query","required":false,"description":"Webshop the return belongs to (optional; reference is unique within the catalog)","schema":{"type":"integer","example":42}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnUpdate"}}}},"responses":{"200":{"description":"Return updated successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"message":{"type":"string","example":"Return updated successfully"}}}]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (e.g. webshop does not belong to relation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Return not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a return","description":"Delete an existing return by reference.","tags":["Returns"],"parameters":[{"name":"reference","in":"path","required":true,"description":"Return reference","schema":{"type":"string","example":"R-O25-6325"}},{"name":"relationId","in":"query","required":false,"description":"Relation that owns the return (optional; reference is unique within the catalog)","schema":{"type":"integer","example":12}},{"name":"webshopId","in":"query","required":false,"description":"Webshop the return belongs to (optional; reference is unique within the catalog)","schema":{"type":"integer","example":42}}],"responses":{"200":{"description":"Return deleted successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"message":{"type":"string","example":"Return deleted successfully"}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (e.g. webshop does not belong to relation or cannot delete return)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Return not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/invoices":{"get":{"summary":"List invoices","description":"List invoices (paginated) with optional filters by state, date range, or relationId.","tags":["Invoices"],"parameters":[{"name":"state","in":"query","required":false,"description":"Invoice state filter (concept, finalized, exported, paid, sent)","schema":{"type":"string","enum":["concept","finalized","exported","paid","sent"],"example":"finalized"}},{"name":"startDate","in":"query","required":false,"description":"ISO 8601 date or datetime (filters invoices with startDate >= this value)","schema":{"type":"string","format":"date-time","example":"2025-01-01T00:00:00Z"}},{"name":"endDate","in":"query","required":false,"description":"ISO 8601 date or datetime (filters invoices with endDate >= this value)","schema":{"type":"string","format":"date-time","example":"2025-01-31T23:59:59Z"}},{"name":"relationId","in":"query","required":false,"description":"Filter by relation ID","schema":{"type":"integer","example":12}},{"name":"page","in":"query","required":false,"description":"Results page index","schema":{"type":"integer","default":1,"minimum":1}},{"name":"size","in":"query","required":false,"description":"Results per page","schema":{"type":"integer","default":50,"minimum":1,"maximum":250}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoicesListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing invoices:read)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/invoices/{id}":{"get":{"summary":"Get a single invoice","description":"Retrieve a single invoice by ID, including associated invoice lines.","tags":["Invoices"],"parameters":[{"name":"id","in":"path","required":true,"description":"Invoice ID","schema":{"type":"integer","example":42}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Invoice"}}}]}}}},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing invoices:read)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Invoice not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/webhooks":{"post":{"summary":"Create a webhook subscription","description":"Subscribe a HTTPS endpoint to one or more order event types. The response includes a one-time signing secret. It is generated server-side, stored encrypted, and cannot be retrieved again afterwards; if it is lost, delete the subscription and create a new one.\nEvery delivered event is a `WebhookEventPayload` sent with the headers X-Stockhub-Event, X-Stockhub-Event-Id, X-Stockhub-Timestamp (unix seconds) and X-Stockhub-Signature: sha256=<hex>, where hex is HMAC-SHA256(secret, \"<timestamp>.<raw body>\"). A status-changing update can produce both `order.updated` and `order.status_changed`; cancelling an order produces both `order.cancelled` and `order.status_changed`.\nVerify the signature with a timing-safe compare, and reject deliveries whose timestamp is older than your replay tolerance (e.g. 5 minutes):\n```js\nconst crypto = require('crypto');\nconst expected = crypto.createHmac('sha256', secret).update(`${req.headers['x-stockhub-timestamp']}.${rawBody}`).digest('hex');\nconst valid = crypto.timingSafeEqual(Buffer.from(`sha256=${expected}`), Buffer.from(req.headers['x-stockhub-signature']));\n```\n","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"HTTPS endpoint events are delivered to","example":"https://example.com/webhooks/stockhub"},"events":{"type":"array","description":"Non-empty list of event types to subscribe to","items":{"type":"string","enum":["order.created","order.updated","order.status_changed","order.cancelled"]}}},"required":["url","events"]}}}},"responses":{"201":{"description":"Subscription created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"subscription":{"$ref":"#/components/schemas/WebhookSubscriptionWithSecret"}}}]}}}},"400":{"description":"Validation error (invalid url or events)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing webhooks:write)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"summary":"List webhook subscriptions","description":"List active webhook subscriptions. A relation-scoped key only sees its own relation's subscriptions. Requires the webhooks:read right.\n","tags":["Webhooks"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"subscriptions":{"type":"array","items":{"$ref":"#/components/schemas/WebhookSubscription"}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing webhooks:read)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/webhooks/{id}":{"put":{"summary":"Update a webhook subscription","description":"Partially update a subscription's url and/or events. A relation-scoped key may only update its own relation's subscriptions. Requires the webhooks:write right.\n","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"description":"Subscription id","schema":{"type":"integer"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"New HTTPS endpoint (omit to keep the current one)","example":"https://example.com/webhooks/stockhub"},"events":{"type":"array","description":"New non-empty list of event types (omit to keep the current ones)","items":{"type":"string","enum":["order.created","order.updated","order.status_changed","order.cancelled"]}}}}}}},"responses":{"200":{"description":"Subscription updated","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"subscription":{"$ref":"#/components/schemas/WebhookSubscription"}}}]}}}},"400":{"description":"Validation error (invalid url or events)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing webhooks:write)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Subscription not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a webhook subscription","description":"Delete a subscription. A relation-scoped key may only delete its own relation's subscriptions. Requires the webhooks:write right.\n","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"description":"Subscription id","schema":{"type":"integer"}}],"responses":{"200":{"description":"Subscription deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing webhooks:write)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Subscription not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}