{"openapi":"3.0.0","info":{"title":"Stockhub Open API","version":"1.0.0","description":"Manage your webshop inventory and orders in Stockhub.\n\n## Rate limits\nLimits are applied per API token, per window of one minute. Each row is one shared\nallowance: for example, all write requests together count towards the same 10 per minute.\n\n| Endpoints | Limit |\n|-----------|-------|\n| `GET /api/me` | 10 requests per minute |\n| `GET /api/products/stock` (all stock) | 10 requests per minute |\n| Other `GET` endpoints | 100 requests per minute (shared) |\n| `POST` / `PUT` endpoints and `DELETE /api/returns/{reference}` | 10 requests per minute (shared) |\n| Other `DELETE` endpoints | 10 requests per minute (shared) |\n\nResponses carry the `RateLimit` and `RateLimit-Policy` headers (IETF draft-7). When a limit\nis exceeded the API responds with `429 Too Many Requests` and a `Retry-After` header (seconds).","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","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":{"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-phyisical (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":"Indicates whether batch tracking is required for this product.\nWhen creating inbounds for this product, a batch number must be provided if this is true.","example":false},"lotRequired":{"type":"boolean","description":"Indicates whether lot tracking is required for this product.\nWhen creating inbounds for this product, a lot number must be provided if this is true.","example":false},"serialNumberRequired":{"type":"boolean","description":"Indicates whether serial number tracking is required for this product.\nWhen creating inbounds for this product, serial numbers must be provided if this is true.","example":false},"createdAt":{"type":"string","format":"date-time","description":"Last modification 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":{"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":["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"},"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"}}},"Order":{"type":"object","properties":{"id":{"type":"integer","description":"Internal Stockhub order ID (used as `orderId` when creating a return)","example":123},"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":"datetime","description":"Date and time the order was created","example":"2024-01-16 14:32:50"},"date_planned":{"type":"string","format":"datetime","description":"Planned shipment date","example":"2024-01-15 15:00:00"},"date_sent":{"type":"string","format":"datetime","description":"Date and time the order was packed and shipped","example":"2024-01-16 14:32:50"},"channel":{"type":"string","format":"string","description":"Name of the webshop as registered in Stockhub"},"externalId":{"type":"string","description":"External order identifier","example":"EXT-456"},"remark":{"type":"string","description":"Remark for the order","example":"Please read this remark"},"isB2B":{"type":"boolean","description":"Whether the order is a B2B (business-to-business) order","example":false},"totalCost":{"type":"float","description":"The fulfilment cost for this order","example":"9.95"},"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"},"shippingAddress":{"type":"object","description":"Shipping address details","properties":{"firstName":{"type":"string","description":"Customer first name","example":"John"},"lastName":{"type":"string","description":"Customer last name","example":"Doe"},"company":{"type":"string","description":"Company name (optional)","example":"Acme Corp"},"addressLine1":{"type":"string","description":"Primary address line","example":"123 Main St"},"addressLine2":{"type":"string","description":"Secondary address line","example":"Apt 4B"},"postalCode":{"type":"string","description":"Postal code","example":"1012 AB"},"city":{"type":"string","description":"City name","example":"Amsterdam"},"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code","example":"NL"},"phone":{"type":"string","description":"Phone number","example":"+31612345678"},"email":{"type":"string","description":"Customer email","example":"john.doe@example.com"}}}},"required":["id","state"]},"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":{"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"},"price":{"type":"float","description":"Selling price of the products in this line (sum of amount x unit) (required for international shipments)","example":12.34}},"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","description":"Customer first name","example":"John"},"lastName":{"type":"string","description":"Customer last name","example":"Doe"},"company":{"type":"string","description":"Company name (optional)","example":"Acme Corp"},"addressLine1":{"type":"string","description":"Primary address line","example":"Ambachtstraat 15b"},"addressLine2":{"type":"string","description":"Secondary address line (only use for addresses outside of NL, BE, DE)","example":"Appartement 25"},"postal":{"type":"string","description":"Postal code","example":"1012 AB"},"city":{"type":"string","description":"City name","example":"Amsterdam"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country code","example":"NL"},"phone":{"type":"string","description":"Phone number of the recipient (optional, may be empty). Do not send a placeholder such as the webshop's own number: carriers use it to contact the recipient. When a carrier requires a phone number for the destination country, Stockhub supplies it. Outside the EU a missing phone number can put the order on hold, depending on the shipping profile (see `errorReason`).\n","example":"+31612345678"}},"required":["firstName","lastName","addressLine1","postal","city","country_code"]}},"required":["orderlines","externalId","email","shippingAddress"]},"Shipment":{"type":"object","properties":{"order_barcode":{"type":"string","description":"Associated order identifier","example":"O25-6324"},"tracking_number":{"type":"string","description":"Shipment tracking number","example":"TRK123456789"},"carrier":{"type":"string","description":"Shipping carrier","example":"PostNL"},"shipped_at":{"type":"string","format":"date-time","description":"Shipment date and time","example":"2023-12-01T10:30:00Z"},"delivery_address":{"type":"object","description":"Delivery address","properties":{"street":{"type":"string","example":"Amstel"},"house_nr":{"type":"string","example":"1"},"city":{"type":"string","example":"Amsterdam"},"postal":{"type":"string","example":"1011 PN"},"country":{"type":"string","example":"NL"}}}}},"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"},"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"}}}}}},"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 delivery date at the warehouse (not the date the supplier ships)","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"]}}}}},"InboundLineInput":{"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"]},"InboundCreate":{"type":"object","properties":{"reference":{"type":"string","description":"Reference identifier for the inbound","example":"ASD"},"shipmentDate":{"type":"string","format":"date","description":"Expected delivery date at the warehouse (not the date the supplier ships)","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":{"$ref":"#/components/schemas/InboundLineInput"}},"shipments":{"type":"array","description":"Array of tracking numbers for shipments","items":{"type":"string"},"example":["TRACK123","TRACK456"]}},"required":["reference","shipmentDate","inboundLines"]},"InboundUpdate":{"type":"object","description":"All fields are optional, but at least one must be given. Fields that are left out keep their current value.","minProperties":1,"properties":{"reference":{"type":"string","description":"New reference for the inbound. Must be unique among your inbounds.","example":"ASD"},"shipmentDate":{"type":"string","format":"date","description":"Expected delivery date at the warehouse (not the date the supplier ships)","example":"2025-11-04"},"pallets":{"type":"integer","description":"Number of pallets","example":1},"colli":{"type":"integer","description":"Number of colli/packages","example":2},"inboundLines":{"type":"array","minItems":1,"description":"The complete new set of lines. Each SKU may appear once. A SKU that is already on the\ninbound gets the new amount, a new SKU is added and a SKU that is left out is removed.\nBatch, lot, best before date and serial numbers are replaced by what the line carries.","items":{"$ref":"#/components/schemas/InboundLineInput"}},"shipments":{"type":"array","description":"The complete new list of tracking numbers; replaces the existing ones. An empty array removes them all.","items":{"type":"string"},"example":["TRACK123","TRACK456"]}}},"WebhookSubscription":{"type":"object","properties":{"id":{"type":"integer","description":"Subscription id","example":12},"url":{"type":"string","format":"uri","description":"HTTPS endpoint events are delivered to","example":"https://example.com/webhooks/stockhub"},"events":{"type":"array","description":"Subscribed event types","items":{"type":"string","enum":["stock.changed","shipment.confirmed"]}},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp. Only events that happen after this moment are sent.","example":"2025-08-19T10:43:39.068Z"}}},"WebhookSubscriptionWithSecret":{"allOf":[{"$ref":"#/components/schemas/WebhookSubscription"},{"type":"object","properties":{"secret":{"type":"string","description":"Signing secret for verifying deliveries. Returned only once, on creation.","example":"3f1c9a7e5b2d48f6a0c4e8b1d7f3925a6c0e4b8d2f6a1c5e9b3d7f0a4c8e2b6d"}}}]},"ShipmentWebhookEvent":{"type":"object","description":"Body of a `shipment.confirmed` delivery","properties":{"id":{"type":"string","format":"uuid","description":"Unique event id, equal to the `X-Stockhub-Event-Id` header. Stays the same on a retry.","example":"4f7bb810-5968-5ba3-8f93-3c1062f75c68"},"type":{"type":"string","enum":["shipment.confirmed"]},"timestamp":{"type":"string","format":"date-time","description":"Moment the event was created","example":"2025-08-19T10:44:15.000Z"},"data":{"type":"object","properties":{"shipment":{"$ref":"#/components/schemas/ShipmentListItem"}}}}},"StockWebhookEvent":{"type":"object","description":"Body of a `stock.changed` delivery","properties":{"id":{"type":"string","format":"uuid","description":"Unique event id, equal to the `X-Stockhub-Event-Id` header. Stays the same on a retry.","example":"dd6690cd-1fce-4fb9-8cd1-3e0a71495457"},"type":{"type":"string","enum":["stock.changed"]},"timestamp":{"type":"string","format":"date-time","description":"Moment the event was created","example":"2025-08-19T10:44:15.000Z"},"data":{"type":"object","properties":{"stock":{"$ref":"#/components/schemas/Stock"},"reasons":{"type":"array","description":"What changed the available stock since the previous event for this product. The most common values:\n- inbound = received on an inbound\n- reservation = reserved for an order, or a reservation released\n- manual = manual correction\n- return = processed return\n\nOther possible values: import, moving, outbound, backorder, backorder_prio, picking,\nreopen, replenish, sending. Treat unknown values as \"stock changed\" and rely on\n`stock.availableStock` for the new level.","items":{"type":"string"},"example":["inbound","reservation"]}}}}},"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"},"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","description":"The order is identified by either `orderId` or `orderBarcode`; `orderId` takes precedence when both are sent.","properties":{"orderId":{"type":"integer","description":"ID of the order this return is for (the `id` field of the order in `GET /api/orders`)","example":123},"orderBarcode":{"type":"string","description":"Barcode of the order this return is for (returned by `POST /api/orders/add`)","example":"O25-6325"},"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":["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"},"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"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"success":{"type":"boolean","example":false}},"required":["error","success"]},"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"}}}},"SuccessResponse":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"success":{"type":"boolean","example":true},"data":{"type":"object","description":"Response data"}},"required":["success"]},"ErrorsResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"success":{"type":"boolean","example":false}},"required":["error","success"]}},"responses":{"UnauthorizedError":{"description":"Authentication information is missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Missing secret","success":false}}}},"ValidationError":{"description":"The posted data is invalid or in an incorrect format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorsResponse"},"example":{"errors":"AddressLine1 missing","success":false}}}},"InvalidSecretError":{"description":"Invalid authentication secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Invalid secret","success":false}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Internal server connection error","success":false}}}},"ServerError":{"description":"Server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"error"},"error":{"type":"object","description":"Error details"},"success":{"type":"boolean","example":false}}}}}},"RateLimitError":{"description":"Too many requests - rate limit exceeded","headers":{"RateLimit-Limit":{"description":"The maximum number of requests allowed in the time window","schema":{"type":"integer","example":100}},"RateLimit-Remaining":{"description":"The number of requests remaining in the current time window","schema":{"type":"integer","example":0}},"RateLimit-Reset":{"description":"The time at which the current rate limit window resets (Unix timestamp)","schema":{"type":"integer","example":1640000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Too many requests from this API key, please try again later.","success":false}}}}}},"paths":{"/api/me":{"get":{"operationId":"getMe","summary":"Me","description":"Verify the current authentication key and returns info of the authenticated user.\n\n**Rate Limit**: 10 requests per minute per API key\n","tags":["Authentication"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successfully Authenticated","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed per minute","schema":{"type":"integer","example":10}},"RateLimit-Remaining":{"description":"Remaining requests in current window","schema":{"type":"integer","example":9}},"RateLimit-Reset":{"description":"Unix timestamp when limit resets","schema":{"type":"integer","example":1640000060}}},"content":{"application/json":{"schema":{"type":"object","properties":{"relation":{"type":"string","example":"Your company name"},"success":{"type":"boolean","example":true}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"429":{"$ref":"#/components/responses/RateLimitError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/products":{"get":{"operationId":"getProducts","summary":"Get all products","description":"Retrieve a list of all products for the authenticated webshop","tags":["Products"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":true,"description":"Results page index","schema":{"type":"integer","example":5,"minimum":1,"maximum":"totalPages","default":1}},{"name":"size","in":"query","required":true,"description":"Results per page","schema":{"type":"integer","example":50,"default":20,"minimum":1,"maximum":100}},{"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":195950643787}},{"name":"lastChangedSince","in":"query","required":false,"description":"Filter on products that have changed since this date/time","schema":{"type":"datetime","example":"2025-08-19T10:43:39.068Z"}}],"responses":{"200":{"description":"Successfully retrieved products","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedSuccessResponse"},{"type":"object","properties":{"data":{"items":{"$ref":"#/components/schemas/Product"}}}}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/products/add":{"post":{"operationId":"createProduct","summary":"Create a new product","description":"Add a new product to the warehouse","tags":["Products"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductCreate"}}}},"responses":{"201":{"description":"Product created successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}}}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/products/{sku}":{"put":{"operationId":"updateProduct","summary":"Update a product","description":"Update an existing product by SKU","tags":["Products"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"sku","in":"path","required":true,"description":"Product SKU","schema":{"type":"string","example":195950643787}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductUpdate"}}}},"responses":{"200":{"description":"Product updated successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}}}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"description":"Product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/products/stock":{"get":{"operationId":"getAllStock","summary":"Get stock levels for all products","description":"Retrieve stock information for all products","tags":["Stock"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":true,"description":"Results page index","schema":{"type":"integer","example":5,"minimum":1,"maximum":"totalPages","default":1}},{"name":"size","in":"query","required":true,"description":"Results per page","schema":{"type":"integer","example":50,"default":20,"minimum":1,"maximum":100}},{"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":195950643787}},{"name":"lastChangedSince","in":"query","required":false,"description":"Filter on products that have changed since this date/time","schema":{"type":"datetime","example":"2025-08-19T10:43:39.068Z"}}],"responses":{"200":{"description":"Successfully retrieved stock levels","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedSuccessResponse"},{"type":"object","properties":{"data":{"items":{"$ref":"#/components/schemas/Stock"}}}}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/products/{sku}/stock":{"get":{"operationId":"getProductStock","summary":"Get stock level for a specific product","description":"Retrieve stock information for a specific product by SKU","tags":["Stock"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"sku","in":"path","required":true,"description":"Product SKU","schema":{"type":"integer","example":195950643787}}],"responses":{"200":{"description":"Successfully retrieved product stock","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Stock"},"success":{"type":"boolean","example":true}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"description":"Product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/orders/":{"get":{"operationId":"listOrders","summary":"List orders","description":"List all orders with filters (paginated)","tags":["Orders"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":true,"description":"Results page index","schema":{"type":"integer","example":5,"minimum":1,"maximum":"totalPages","default":1}},{"name":"size","in":"query","required":true,"description":"Results per page","schema":{"type":"integer","example":50,"default":20,"minimum":1,"maximum":100}},{"name":"barcode","in":"query","required":false,"description":"Unique barcode of the order (Exact match)","schema":{"type":"string","example":"O25-6325"}},{"name":"reference","in":"query","required":false,"description":"Webshop reference of the order (Full-text search)","schema":{"type":"string","example":"ORD-A123456"}},{"name":"name","in":"query","required":false,"description":"Delivery name for the receiver of the order (Full-text search)","schema":{"type":"string","example":"Firstname Lastname"}},{"name":"plannedFromDate","in":"query","required":false,"description":"Planned after this date","schema":{"type":"datetime","example":"2025-08-09T15:00:00"}},{"name":"plannedToDate","in":"query","required":false,"description":"Planned before this date","schema":{"type":"datetime","example":"2025-08-09T15:00:00"}},{"name":"state","in":"query","required":false,"description":"Order state (comma seperated).","schema":{"type":"string","example":"open,shipped","enum":["open","shipped","cancelled","backorder"],"default":"all states"}}],"responses":{"200":{"description":"Success. List of orders","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedSuccessResponse"},{"type":"object","properties":{"data":{"items":{"$ref":"#/components/schemas/Order"}}}}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/orders/add":{"post":{"operationId":"createOrder","summary":"Create a new order","description":"Add a new order to the warehouse management system","tags":["Orders"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderCreate"}}}},"responses":{"201":{"description":"Order created successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Order"}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/orders/{barcode}":{"patch":{"operationId":"updateOrderAddress","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).\n","tags":["Orders"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"barcode","in":"path","required":true,"description":"Unique barcode of the order","schema":{"type":"string","example":"O25-6325"}}],"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-6325"},"state":{"type":"string","example":"open"},"errorReason":{"type":"string","nullable":true},"addressSuggestion":{"type":"string","nullable":true}}}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"description":"Order not found"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/orders/{barcode}/cancel":{"post":{"operationId":"cancelOrder","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. Cancelling releases the reserved stock and emits the `order.cancelled` webhook event. No request body is needed.\n","tags":["Orders"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"barcode","in":"path","required":true,"description":"Unique barcode of the order","schema":{"type":"string","example":"O25-6325"}}],"responses":{"200":{"description":"Order cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"barcode":{"type":"string","example":"O25-6325"},"state":{"type":"string","example":"cancelled"}}}}}},"400":{"description":"Order cannot be cancelled in its current state, or the relation is blocked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The order changed state while it was being cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"$ref":"#/components/responses/RateLimitError"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/orders/{barcode}/shipments":{"get":{"operationId":"getOrderShipments","summary":"Get shipments for an order","description":"Retrieve all shipments associated with a specific order","tags":["Orders"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"barcode","in":"path","required":true,"description":"Order barcode","schema":{"type":"integer","example":"O25-6324"}}],"responses":{"200":{"description":"Successfully retrieved order shipments","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentListItem"}},"success":{"type":"boolean","example":true}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/shipments":{"get":{"operationId":"listShipments","summary":"List shipments","description":"List shipments (paginated) across all orders for the authenticated webshop.\nScoped by the bearer token: only shipments belonging to orders owned by the\ntoken's relation are returned. The per-order endpoint\n`GET /api/orders/{barcode}/shipments` exists for fetching shipments of a\nsingle order.\n","tags":["Shipments"],"security":[{"bearerAuth":[]}],"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"}}],"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":{"$ref":"#/components/responses/UnauthorizedError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/shipments/{trackingNumber}/status":{"get":{"operationId":"getShipmentStatus","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"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"trackingNumber","in":"path","required":true,"description":"Tracking number of the shipment","schema":{"type":"string","example":"TRK123456789"}}],"responses":{"200":{"description":"Carrier status and scan history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentStatusResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"description":"Shipment not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/shipments/webhook":{"put":{"operationId":"setShipmentWebhook","summary":"Configure the shipment webhook URL","description":"Register the URL that should receive shipment notifications for the\nauthenticated webshop. Whenever a shipment of an API order is confirmed, a `POST` is sent\nto this URL with a single shipment as the JSON body. The payload is one\n`ShipmentListItem` object - the exact same shape returned per item by\n`GET /api/shipments`.\n\nDelivery is best-effort (fire-and-forget): the webhook is called once per\nshipment and is not retried. Secure your endpoint by including a secret in\nthe URL you register here. Call this endpoint again to update the URL.\n\nThis webhook only reports shipments of orders that were created through this API. The\n`shipment.confirmed` event on `POST /api/webhooks` reports the shipments of all your\norders, with signed deliveries and retries; prefer it for new integrations. A URL that\nis registered on both is only notified through `/api/webhooks`.\n","tags":["Shipments"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"The http(s) URL to POST shipment notifications to","example":"https://example.com/hooks/shipments?token=secret123"}}}}}},"responses":{"200":{"description":"Webhook URL stored","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"400":{"description":"Validation error (missing or invalid url)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/webhooks":{"post":{"operationId":"createWebhook","summary":"Create a webhook subscription","description":"Subscribe an HTTPS endpoint to one or more events, so Stockhub notifies you instead of\nyou having to poll. A subscription covers your whole account; any of your API keys can\nmanage it. One subscription can listen to several events, or you can create a\nsubscription per event with its own endpoint.\n\n**Events**\n\n| Event | Sent when | Body |\n| --- | --- | --- |\n| `stock.changed` | The available stock of a product changed | `StockWebhookEvent` |\n| `shipment.confirmed` | A shipment of one of your orders is confirmed | `ShipmentWebhookEvent` |\n\n`stock.changed` is sent for every change of the available stock: a receipt (inbound), a\nreservation or release for an order, a manual correction, a processed return, and so on.\nOne event is sent per product, carrying the current stock in the same shape as an item of\n`GET /api/products/stock`, plus the `reasons` that caused the change. Changes are\ncollected about once a minute, so several changes of one product shortly after each other\narrive as one event with the latest stock. A set (virtual product) gets its own event when\none of its components changes.\n\n`shipment.confirmed` is sent for every shipment of your account, whichever channel the\norder came from (API, webshop or marketplace integration, manually created). It carries\nthe shipment in the same shape as an item of `GET /api/shipments`. A shipment is confirmed\na few minutes after it is created, so a label that is cancelled right away is not reported.\n\n**Authentication:** the response of this call includes a signing secret. It is generated\nby Stockhub, shown once and cannot be retrieved again; if it is lost, delete the\nsubscription and create a new one. Every delivery is a `POST` with a JSON body and these\nheaders: `X-Stockhub-Event` (the event name), `X-Stockhub-Event-Id`,\n`X-Stockhub-Timestamp` (unix seconds) and `X-Stockhub-Signature: sha256=<hex>`, where hex\nis HMAC-SHA256(secret, \"<timestamp>.<raw body>\"). Verify the signature over the raw\nrequest body with a timing-safe compare and reject deliveries whose timestamp is older\nthan your replay tolerance (e.g. 5 minutes):\n\n```js\n\nconst crypto = require('crypto');\n\nconst expected = crypto.createHmac('sha256', secret).update(`${req.headers['x-stockhub-timestamp']}.${rawBody}`).digest('hex');\n\nconst valid = crypto.timingSafeEqual(Buffer.from(`sha256=${expected}`), Buffer.from(req.headers['x-stockhub-signature']));\n\n```\n\n**Delivery and retries:** answer with a `2xx` status within 10 seconds. A delivery that\nfails is retried after 1 minute and again after 5 minutes; after three failed attempts the\nevent is dropped. While an event is waiting for its retry, later events for the same\nsubscription wait behind it so they arrive in order. A retried event keeps its\n`X-Stockhub-Event-Id`, so use that id to ignore duplicates.\n\nBecause an event can be dropped when your endpoint is down for longer, run a periodic poll\nas a safety net (`GET /api/products/stock?lastChangedSince=...`, `GET /api/shipments`).\n","tags":["Webhooks"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"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":["stock.changed","shipment.confirmed"]}}}}}}},"responses":{"201":{"description":"Subscription created. This is the only time the secret is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"subscription":{"$ref":"#/components/schemas/WebhookSubscriptionWithSecret"}}}}}},"400":{"description":"Validation error (invalid url or events)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"get":{"operationId":"listWebhooks","summary":"List webhook subscriptions","description":"List the active webhook subscriptions of your account. Secrets are not included.","tags":["Webhooks"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"subscriptions":{"type":"array","items":{"$ref":"#/components/schemas/WebhookSubscription"}}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/webhooks/{id}":{"put":{"operationId":"updateWebhook","summary":"Update a webhook subscription","description":"Change the url and/or events of a subscription. The signing secret stays the same.","tags":["Webhooks"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Subscription id","schema":{"type":"integer"}}],"requestBody":{"required":true,"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":["stock.changed","shipment.confirmed"]}}}}}}},"responses":{"200":{"description":"Subscription updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"subscription":{"$ref":"#/components/schemas/WebhookSubscription"}}}}}},"400":{"description":"Validation error (invalid url or events)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"description":"Subscription not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}},"delete":{"operationId":"deleteWebhook","summary":"Delete a webhook subscription","description":"Delete a subscription. Events that were not delivered yet are dropped.","tags":["Webhooks"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Subscription id","schema":{"type":"integer"}}],"responses":{"200":{"description":"Subscription deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"description":"Subscription not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/inbounds":{"get":{"operationId":"listInbounds","summary":"List inbounds","description":"List all inbounds with filters (paginated)","tags":["Inbounds"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":true,"description":"Results page index","schema":{"type":"integer","example":5,"minimum":1,"maximum":"totalPages","default":1}},{"name":"size","in":"query","required":true,"description":"Results per page","schema":{"type":"integer","example":50,"default":20,"minimum":1,"maximum":100}},{"name":"barcode","in":"query","required":false,"description":"Unique barcode of the inbound (Exact match)","schema":{"type":"string","example":"INSL-1"}},{"name":"reference","in":"query","required":false,"description":"Reference of the inbound (Full-text search)","schema":{"type":"string","example":"RFM-123"}},{"name":"state","in":"query","required":false,"description":"Inbound state (comma separated).\n- active = Not yet received\n- fullyreceived = All products are counted and are complete, stock not yet available\n- completed = Products are now available stock for orders\n","schema":{"type":"string","example":"active,fullyreceived,completed","default":"all states"}},{"name":"lastChangedSince","in":"query","required":false,"description":"Filter on inbounds and inboundlines that have changed since this date/time","schema":{"type":"datetime","example":"2025-08-19T10:43:39.068Z"}}],"responses":{"200":{"description":"Success. List of inbounds","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedSuccessResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Inbound"}}}}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/inbounds/add":{"post":{"operationId":"createInbound","summary":"Create a new inbound","description":"Add a new inbound to the warehouse management system.\n\n**Batch, Lot, and Serial Number Requirements:**\n- If a product has `batchRequired` set to true, you must provide a `batch` value for that product\n- If a product has `lotRequired` set to true, you must provide a `lot` value for that product\n- If a product has `serialNumberRequired` set to true, you must provide `serialNumbers` array with the exact number of serial numbers matching the `amount`\n- The `bbDate` field is optional and can be used with either batch or lot to track expiration dates","tags":["Inbounds"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundCreate"},"examples":{"basic":{"summary":"Basic inbound without batch/lot/serial","value":{"reference":"INB-2025-001","shipmentDate":"2025-12-20","pallets":2,"colli":10,"inboundLines":[{"sku":"PRODUCT-001","amount":100}],"shipments":["TRACK001","TRACK002"]}},"with_batch":{"summary":"Inbound with batch tracking","value":{"reference":"INB-2025-002","shipmentDate":"2025-12-20","pallets":1,"colli":5,"inboundLines":[{"sku":"FOOD-PRODUCT-001","amount":50,"batch":"BATCH-2025-001","bbDate":"2026-12-31"}],"shipments":["TRACK003"]}},"with_lot":{"summary":"Inbound with lot tracking","value":{"reference":"INB-2025-003","shipmentDate":"2025-12-20","pallets":1,"colli":3,"inboundLines":[{"sku":"PHARMA-PRODUCT-001","amount":30,"lot":"LOT-2025-001","bbDate":"2026-06-30"}],"shipments":["TRACK004"]}},"with_serial_numbers":{"summary":"Inbound with serial number tracking","value":{"reference":"INB-2025-004","shipmentDate":"2025-12-20","pallets":1,"colli":1,"inboundLines":[{"sku":"ELECTRONICS-001","amount":3,"serialNumbers":["SN001","SN002","SN003"]}],"shipments":["TRACK005"]}},"mixed":{"summary":"Inbound with mixed tracking methods","value":{"reference":"INB-2025-005","shipmentDate":"2025-12-20","pallets":3,"colli":15,"inboundLines":[{"sku":"FOOD-PRODUCT-001","amount":100,"batch":"BATCH-2025-002","bbDate":"2026-12-31"},{"sku":"PHARMA-PRODUCT-001","amount":50,"lot":"LOT-2025-002","bbDate":"2026-06-30"},{"sku":"ELECTRONICS-001","amount":2,"serialNumbers":["SN004","SN005"]},{"sku":"REGULAR-PRODUCT-001","amount":200}],"shipments":["TRACK006","TRACK007"]}}}}}},"responses":{"201":{"description":"Inbound created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"barcode":{"type":"string","description":"The generated barcode for the inbound","example":"INSL-123"},"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Inbound created successfully"}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/inbounds/{barcode}":{"put":{"operationId":"updateInbound","summary":"Update an inbound","description":"Change an announced inbound without cancelling and re-creating it: the expected delivery\ndate, reference, pallets, colli, tracking numbers and the products and amounts.\n\n**When can an inbound be updated?** Under the same condition as cancelling: only while its\nstate is `active`, so before the warehouse has received anything on it. After that the\nrequest is rejected with a `400`.\n\n**Partial update:** send only the fields you want to change. `inboundLines` and `shipments`\nare each replaced as a whole when given: send the complete new list, not just the changes.\nThe batch, lot and serial number requirements are the same as when creating an inbound.\n\nThe update is applied as a whole or not at all.","tags":["Inbounds"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"barcode","in":"path","required":true,"description":"Inbound barcode","schema":{"type":"string","example":"INSL-1"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundUpdate"},"examples":{"date_only":{"summary":"Move the expected delivery date","value":{"shipmentDate":"2025-12-27"}},"lines":{"summary":"Replace the products and amounts","value":{"inboundLines":[{"sku":"PRODUCT-001","amount":120},{"sku":"PRODUCT-002","amount":40}]}},"everything":{"summary":"Change date, packaging, tracking numbers and lines at once","value":{"shipmentDate":"2025-12-27","pallets":3,"colli":12,"shipments":["TRACK008"],"inboundLines":[{"sku":"FOOD-PRODUCT-001","amount":80,"batch":"BATCH-2025-003","bbDate":"2026-12-31"}]}}}}}},"responses":{"200":{"description":"Inbound updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"barcode":{"type":"string","description":"The barcode of the updated inbound","example":"INSL-123"},"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Inbound updated successfully"}}}}}},"400":{"description":"Validation error, or the inbound cannot be updated anymore (state is not `active`),\nor the new reference is already used by another inbound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"description":"Inbound not found, or a SKU in `inboundLines` does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}},"delete":{"operationId":"cancelInbound","summary":"Cancel an inbound","description":"Cancel an existing inbound by barcode. Only possible while its state is `active`, so before\nthe warehouse has received anything on it.","tags":["Inbounds"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"barcode","in":"path","required":true,"description":"Inbound barcode","schema":{"type":"string","example":"INSL-1"}}],"responses":{"200":{"description":"Inbound cancelled successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Inbound cancelled successfully"}}}}}},"400":{"description":"Inbound cannot be cancelled anymore","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"description":"Inbound not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/returns":{"get":{"operationId":"listReturns","summary":"List returns","description":"List all returns with filters (paginated)","tags":["Returns"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":true,"description":"Results page index","schema":{"type":"integer","example":1,"minimum":1,"default":1}},{"name":"size","in":"query","required":true,"description":"Results per page","schema":{"type":"integer","example":20,"default":20,"minimum":1,"maximum":100}},{"name":"reference","in":"query","required":false,"description":"Return reference (Full-text search)","schema":{"type":"string","example":"R-O25-6325"}},{"name":"name","in":"query","required":false,"description":"Customer name (Full-text search)","schema":{"type":"string","example":"John Doe"}},{"name":"barcode","in":"query","required":false,"description":"Filter returns by product barcode or SKU. Returns all returns that contain products matching this barcode (Exact match)","schema":{"type":"string","example":"0195950643787"}}],"responses":{"200":{"description":"Success. List of returns","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedSuccessResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Return"}}}}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/returns/add":{"post":{"operationId":"createReturn","summary":"Create a new return","description":"Add a new return to the warehouse management system.\n\n**Product Barcode Matching:**\n- The barcode field in returnLines can match either the product SKU or any barcode associated with the product\n- Products are looked up using the barcodes array which includes the SKU and all additional barcodes","tags":["Returns"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnCreate"},"examples":{"basic":{"summary":"Basic return with product barcodes","value":{"orderId":123,"name":"John Doe","email":"john.doe@example.com","reference":"RET-2025-001","returnLines":[{"barcode":"0195950643787","amount":1,"remark":"Defective item","returnreasonId":5},{"barcode":"8719327545409","amount":2,"remark":"Wrong size"}]}},"byOrderBarcode":{"summary":"Return identified by order barcode","value":{"orderBarcode":"O25-6325","name":"John Doe","email":"john.doe@example.com","returnLines":[{"barcode":"0195950643787","amount":1}]}}}}}},"responses":{"201":{"description":"Return created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","description":"The reference for the created return","example":"R-O25-6325"},"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Return created successfully"}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/returns/{reference}":{"put":{"operationId":"updateReturn","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.","tags":["Returns"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"reference","in":"path","required":true,"description":"Return reference","schema":{"type":"string","example":"R-O25-6325"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnUpdate"},"examples":{"remark":{"summary":"Update only the remark","value":{"remark":"Customer changed mind"}}}}}},"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":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"description":"Return not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"operationId":"deleteReturn","summary":"Delete a return","description":"Delete an existing return by reference.\n\n**Deletion Rules:**\n- Returns with state 'processed' cannot be deleted\n- Returns created from the return portal (no externalId, shipperProfileId > 0, createdByFulfilment = false) cannot be deleted\n- All associated data (return lines, photos, mollie payments, shipments) will be deleted","tags":["Returns"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"reference","in":"path","required":true,"description":"Return reference","schema":{"type":"string","example":"R-O25-6325"}}],"responses":{"200":{"description":"Return deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Return deleted successfully"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"description":"Return cannot be deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"processed":{"value":{"error":"Cannot delete processed return","success":false}},"portal":{"value":{"error":"Cannot delete return portal return","success":false}}}}}},"404":{"description":"Return not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/returns/{reference}/complete":{"post":{"operationId":"completeReturn","summary":"Complete a processed return","description":"Complete a return after the warehouse has processed it. This is the same as the\n\"Afronden\" action in the software.\n\n- Only returns with state 'processed' can be completed; their state becomes 'completed'\n- When several processed returns share the reference, all of them are completed","tags":["Returns"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"reference","in":"path","required":true,"description":"Return reference","schema":{"type":"string","example":"R-O25-6325"}}],"responses":{"200":{"description":"Return completed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Return completed successfully"},"completedCount":{"type":"integer","description":"Number of returns completed","example":1}}}}}},"400":{"description":"Return is not processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Only processed returns can be completed","success":false}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"description":"Return not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"tags":[{"name":"Authentication","description":"This API uses **token-based authentication**. You must include your API key as a Bearer token in the `Authorization` header.\n\nExample:\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n\nTo obtain an API key, follow the step-by-step guide here:\n👉 [Create an API key](https://support.stockhub.nl/hc/nl)\n\nYou can verify your token using the `/api/me` endpoint, which returns the authenticated user’s information.\n\nAll endpoints are protected and require authentication unless stated otherwise.\n"},{"name":"Products","description":"Product management operations"},{"name":"Stock","description":"Inventory and stock level operations"},{"name":"Orders","description":"Order management operations"},{"name":"Shipments","description":"Shipment list operations across orders"},{"name":"Inbounds","description":"Inbound inventory management operations"},{"name":"Returns","description":"Return management operations"},{"name":"Webhooks","description":"Subscribe an endpoint to push notifications, such as stock changes and confirmed shipments"}]}