{"openapi":"3.1.0","info":{"title":"Merchant House Admin API","version":"1.0.0","description":"Server-to-server REST API for a single Merchant House store.\n\n**Authentication.** Create a secret key in Dashboard → Settings → Developers and send it as `Authorization: Bearer mh_sk_...`. Each key belongs to one store and carries a set of scopes.\n\n**Rate limits.** 120 requests per minute per key. Over the limit you get HTTP 429 with a `Retry-After` header (seconds).\n\n**Money.** Every amount is an integer in the currency's minor unit (1999 = $19.99), in requests and responses.\n\n**Pagination.** List endpoints accept `page` (1-based) and `limit` (max 100) and return `{ object: \"list\", data, page, has_more }`.\n\n**Requests.** JSON only (`Content-Type: application/json`), bodies up to 1 MB. Every response carries an `X-Request-Id`. CORS is not supported: never call the API from a browser.\n\n**Webhooks.** Each delivery is a POST signed with `Merchant-House-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256>` where the HMAC is computed over `<t>.<raw body>` with the endpoint's signing secret (`whsec_...`). Reject timestamps older than 5 minutes and compare in constant time.","contact":{"name":"Merchant House","url":"https://api.merchanthouse.app"}},"servers":[{"url":"https://api.merchanthouse.app","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Store"},{"name":"Products"},{"name":"Collections"},{"name":"Inventory"},{"name":"Orders"},{"name":"Customers"}],"paths":{"/v1/store":{"get":{"operationId":"getStore","tags":["Store"],"summary":"Retrieve the store","description":"Required scope: `store.read`.","x-required-scope":"store.read","responses":{"200":{"description":"The store this key belongs to.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/products":{"get":{"operationId":"listProducts","tags":["Products"],"summary":"List products","description":"Most recently updated first.\n\nRequired scope: `products.read`.","x-required-scope":"products.read","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"1-based page number."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Items per page (max 100)."},{"name":"status","in":"query","schema":{"type":"string","enum":["any","draft","active","archived"],"default":"any"}},{"name":"q","in":"query","schema":{"type":"string","maxLength":200},"description":"Case-insensitive match on product name."}],"responses":{"200":{"description":"A page of products.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"type":"object","required":["object","data","page","has_more"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"page":{"type":"integer","minimum":1},"has_more":{"type":"boolean","description":"True when another page is available (request page + 1)."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"operationId":"createProduct","tags":["Products"],"summary":"Create a product","description":"Required scope: `products.write`.","x-required-scope":"products.write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Optional. Retrying a POST with the same key (and identical body) within 24 hours returns the original response with `Idempotent-Replayed: true`. Best-effort: keys are held in memory per server instance."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductCreate"}}}},"responses":{"201":{"description":"The created product.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/products/{id}":{"get":{"operationId":"getProduct","tags":["Products"],"summary":"Retrieve a product","description":"Required scope: `products.read`.","x-required-scope":"products.read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Product id"}],"responses":{"200":{"description":"The product.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}},"patch":{"operationId":"updateProduct","tags":["Products"],"summary":"Update a product","description":"Merge update: omitted fields keep their current values. Variant ids are preserved when you pass them back.\n\nRequired scope: `products.write`.","x-required-scope":"products.write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Product id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductUpdate"}}}},"responses":{"200":{"description":"The updated product.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}},"delete":{"operationId":"deleteProduct","tags":["Products"],"summary":"Delete a product","description":"Permanently deletes the product and its variants. Past orders keep their line items.\n\nRequired scope: `products.write`.","x-required-scope":"products.write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Product id"}],"responses":{"200":{"description":"Deletion confirmation.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedProduct"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/collections":{"get":{"operationId":"listCollections","tags":["Collections"],"summary":"List collections","description":"Alphabetical.\n\nRequired scope: `products.read`.","x-required-scope":"products.read","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"1-based page number."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Items per page (max 100)."}],"responses":{"200":{"description":"A page of collections.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"type":"object","required":["object","data","page","has_more"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"page":{"type":"integer","minimum":1},"has_more":{"type":"boolean","description":"True when another page is available (request page + 1)."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/locations":{"get":{"operationId":"listLocations","tags":["Inventory"],"summary":"List inventory locations","description":"Default location first.\n\nRequired scope: `inventory.read`.","x-required-scope":"inventory.read","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"1-based page number."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Items per page (max 100)."}],"responses":{"200":{"description":"A page of locations.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"type":"object","required":["object","data","page","has_more"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Location"}},"page":{"type":"integer","minimum":1},"has_more":{"type":"boolean","description":"True when another page is available (request page + 1)."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/inventory_levels":{"get":{"operationId":"listInventoryLevels","tags":["Inventory"],"summary":"List inventory levels","description":"One row per variant that tracks inventory, lowest stock first. Without `location_id`, `available` is the total across locations and `location_id` is null.\n\nRequired scope: `inventory.read`.","x-required-scope":"inventory.read","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"1-based page number."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Items per page (max 100)."},{"name":"location_id","in":"query","schema":{"type":"string"},"description":"Report stock at this location."},{"name":"sku","in":"query","schema":{"type":"string"},"description":"Exact SKU match (case-insensitive)."},{"name":"q","in":"query","schema":{"type":"string","maxLength":200},"description":"Match on product name or SKU."}],"responses":{"200":{"description":"A page of inventory levels.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"type":"object","required":["object","data","page","has_more"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/InventoryLevel"}},"page":{"type":"integer","minimum":1},"has_more":{"type":"boolean","description":"True when another page is available (request page + 1)."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/inventory_levels/set":{"post":{"operationId":"setInventoryLevel","tags":["Inventory"],"summary":"Set an inventory level","description":"Sets the absolute available quantity of a variant at a location (the default location when `location_id` is omitted). Records an adjustment in the inventory history and emits `inventory.updated`.\n\nRequired scope: `inventory.write`.","x-required-scope":"inventory.write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Optional. Retrying a POST with the same key (and identical body) within 24 hours returns the original response with `Idempotent-Replayed: true`. Best-effort: keys are held in memory per server instance."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryLevelSet"}}}},"responses":{"200":{"description":"The new level.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryLevelSetResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/orders":{"get":{"operationId":"listOrders","tags":["Orders"],"summary":"List orders","description":"Newest first.\n\nRequired scope: `orders.read`.","x-required-scope":"orders.read","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"1-based page number."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Items per page (max 100)."},{"name":"status","in":"query","schema":{"type":"string","enum":["all","unfulfilled","fulfilled","unpaid","cancelled"],"default":"all"},"description":"`unfulfilled` = open orders with items left to ship."},{"name":"q","in":"query","schema":{"type":"string","maxLength":200},"description":"Order number (e.g. 1001 or #1001) or part of the customer email."}],"responses":{"200":{"description":"A page of orders.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"type":"object","required":["object","data","page","has_more"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"page":{"type":"integer","minimum":1},"has_more":{"type":"boolean","description":"True when another page is available (request page + 1)."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/orders/{id}":{"get":{"operationId":"getOrder","tags":["Orders"],"summary":"Retrieve an order","description":"Required scope: `orders.read`.","x-required-scope":"orders.read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Order id (not the order number)"}],"responses":{"200":{"description":"The order.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/orders/{id}/fulfillments":{"post":{"operationId":"createFulfillment","tags":["Orders"],"summary":"Fulfill an order","description":"Marks items as shipped. Without `line_items`, every remaining shippable item is fulfilled. The customer receives a shipping confirmation email unless `notify_customer` is false. Emits `order.fulfilled`.\n\nRequired scope: `orders.write`.","x-required-scope":"orders.write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Order id"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Optional. Retrying a POST with the same key (and identical body) within 24 hours returns the original response with `Idempotent-Replayed: true`. Best-effort: keys are held in memory per server instance."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentCreate"}}}},"responses":{"201":{"description":"The new fulfillment and the updated order.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/customers":{"get":{"operationId":"listCustomers","tags":["Customers"],"summary":"List customers","description":"Most recently updated first.\n\nRequired scope: `customers.read`.","x-required-scope":"customers.read","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"1-based page number."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Items per page (max 100)."},{"name":"q","in":"query","schema":{"type":"string","maxLength":200},"description":"Match on email, first or last name."}],"responses":{"200":{"description":"A page of customers.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"type":"object","required":["object","data","page","has_more"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"page":{"type":"integer","minimum":1},"has_more":{"type":"boolean","description":"True when another page is available (request page + 1)."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/customers/{id}":{"get":{"operationId":"getCustomer","tags":["Customers"],"summary":"Retrieve a customer","description":"Includes saved addresses.\n\nRequired scope: `customers.read`.","x-required-scope":"customers.read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Customer id"}],"responses":{"200":{"description":"The customer.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}}},"webhooks":{"order.created":{"post":{"summary":"An order was placed (online or POS)","description":"Delivered as a signed POST to your endpoint. Verify `Merchant-House-Signature` before trusting the body, and respond 2xx within 10 seconds.","parameters":[{"name":"Merchant-House-Event","in":"header","required":true,"schema":{"const":"order.created"}},{"name":"Merchant-House-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery id; identical across retries. Use it to de-duplicate."},{"name":"Merchant-House-Signature","in":"header","required":true,"schema":{"type":"string","example":"t=1767225600,v1=5f2b..."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","created_at","data"],"properties":{"id":{"type":"string"},"type":{"const":"order.created"},"created_at":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/Order"}}}}}},"responses":{"2XX":{"description":"Acknowledge receipt. Any other status (or a timeout) is retried."}}}},"order.fulfilled":{"post":{"summary":"Items in an order were fulfilled","description":"Delivered as a signed POST to your endpoint. Verify `Merchant-House-Signature` before trusting the body, and respond 2xx within 10 seconds.","parameters":[{"name":"Merchant-House-Event","in":"header","required":true,"schema":{"const":"order.fulfilled"}},{"name":"Merchant-House-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery id; identical across retries. Use it to de-duplicate."},{"name":"Merchant-House-Signature","in":"header","required":true,"schema":{"type":"string","example":"t=1767225600,v1=5f2b..."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","created_at","data"],"properties":{"id":{"type":"string"},"type":{"const":"order.fulfilled"},"created_at":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/Order"}}}}}},"responses":{"2XX":{"description":"Acknowledge receipt. Any other status (or a timeout) is retried."}}}},"order.refunded":{"post":{"summary":"An order was (partially) refunded","description":"Delivered as a signed POST to your endpoint. Verify `Merchant-House-Signature` before trusting the body, and respond 2xx within 10 seconds.","parameters":[{"name":"Merchant-House-Event","in":"header","required":true,"schema":{"const":"order.refunded"}},{"name":"Merchant-House-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery id; identical across retries. Use it to de-duplicate."},{"name":"Merchant-House-Signature","in":"header","required":true,"schema":{"type":"string","example":"t=1767225600,v1=5f2b..."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","created_at","data"],"properties":{"id":{"type":"string"},"type":{"const":"order.refunded"},"created_at":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/Order"}}}}}},"responses":{"2XX":{"description":"Acknowledge receipt. Any other status (or a timeout) is retried."}}}},"order.cancelled":{"post":{"summary":"An order was cancelled","description":"Delivered as a signed POST to your endpoint. Verify `Merchant-House-Signature` before trusting the body, and respond 2xx within 10 seconds.","parameters":[{"name":"Merchant-House-Event","in":"header","required":true,"schema":{"const":"order.cancelled"}},{"name":"Merchant-House-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery id; identical across retries. Use it to de-duplicate."},{"name":"Merchant-House-Signature","in":"header","required":true,"schema":{"type":"string","example":"t=1767225600,v1=5f2b..."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","created_at","data"],"properties":{"id":{"type":"string"},"type":{"const":"order.cancelled"},"created_at":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/Order"}}}}}},"responses":{"2XX":{"description":"Acknowledge receipt. Any other status (or a timeout) is retried."}}}},"product.created":{"post":{"summary":"A product was created","description":"Delivered as a signed POST to your endpoint. Verify `Merchant-House-Signature` before trusting the body, and respond 2xx within 10 seconds.","parameters":[{"name":"Merchant-House-Event","in":"header","required":true,"schema":{"const":"product.created"}},{"name":"Merchant-House-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery id; identical across retries. Use it to de-duplicate."},{"name":"Merchant-House-Signature","in":"header","required":true,"schema":{"type":"string","example":"t=1767225600,v1=5f2b..."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","created_at","data"],"properties":{"id":{"type":"string"},"type":{"const":"product.created"},"created_at":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/Product"}}}}}},"responses":{"2XX":{"description":"Acknowledge receipt. Any other status (or a timeout) is retried."}}}},"product.updated":{"post":{"summary":"A product was updated","description":"Delivered as a signed POST to your endpoint. Verify `Merchant-House-Signature` before trusting the body, and respond 2xx within 10 seconds.","parameters":[{"name":"Merchant-House-Event","in":"header","required":true,"schema":{"const":"product.updated"}},{"name":"Merchant-House-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery id; identical across retries. Use it to de-duplicate."},{"name":"Merchant-House-Signature","in":"header","required":true,"schema":{"type":"string","example":"t=1767225600,v1=5f2b..."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","created_at","data"],"properties":{"id":{"type":"string"},"type":{"const":"product.updated"},"created_at":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/Product"}}}}}},"responses":{"2XX":{"description":"Acknowledge receipt. Any other status (or a timeout) is retried."}}}},"product.deleted":{"post":{"summary":"A product was deleted","description":"Delivered as a signed POST to your endpoint. Verify `Merchant-House-Signature` before trusting the body, and respond 2xx within 10 seconds.","parameters":[{"name":"Merchant-House-Event","in":"header","required":true,"schema":{"const":"product.deleted"}},{"name":"Merchant-House-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery id; identical across retries. Use it to de-duplicate."},{"name":"Merchant-House-Signature","in":"header","required":true,"schema":{"type":"string","example":"t=1767225600,v1=5f2b..."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","created_at","data"],"properties":{"id":{"type":"string"},"type":{"const":"product.deleted"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"object":{"const":"product"},"id":{"type":"string"}}}}}}}},"responses":{"2XX":{"description":"Acknowledge receipt. Any other status (or a timeout) is retried."}}}},"inventory.updated":{"post":{"summary":"An inventory level was set","description":"Delivered as a signed POST to your endpoint. Verify `Merchant-House-Signature` before trusting the body, and respond 2xx within 10 seconds.","parameters":[{"name":"Merchant-House-Event","in":"header","required":true,"schema":{"const":"inventory.updated"}},{"name":"Merchant-House-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"Delivery id; identical across retries. Use it to de-duplicate."},{"name":"Merchant-House-Signature","in":"header","required":true,"schema":{"type":"string","example":"t=1767225600,v1=5f2b..."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","created_at","data"],"properties":{"id":{"type":"string"},"type":{"const":"inventory.updated"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"object":{"const":"inventory_level"},"variant_id":{"type":"string"},"product_id":{"type":"string"},"sku":{"type":["string","null"]},"location_id":{"type":["string","null"]},"available_total":{"type":"integer","description":"Total across all locations after the change."}}}}}}}},"responses":{"2XX":{"description":"Acknowledge receipt. Any other status (or a timeout) is retried."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"mh_sk_...","description":"Secret API key from Dashboard → Settings → Developers. Scopes: `store.read`, `products.read`, `products.write`, `inventory.read`, `inventory.write`, `orders.read`, `orders.write`, `customers.read`."}},"headers":{"X-Request-Id":{"description":"Unique id for this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f1c9a0e2b7d4c6a8e9f0a1b"}},"X-RateLimit-Remaining":{"description":"Requests left in the current one-minute window.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"responses":{"BadRequest":{"description":"Invalid request (`invalid_request_error` or `idempotency_error`). `param` names the offending field when known.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing, malformed, invalid or revoked API key (`authentication_error`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The key lacks the required scope (`permission_error`, code `missing_scope`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The resource does not exist in this store (`invalid_request_error`, code `resource_missing`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflicts with existing data (e.g. a duplicate handle), or an Idempotency-Key still in flight.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PayloadTooLarge":{"description":"Request body larger than 1 MB.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnsupportedMediaType":{"description":"Request body is not `application/json`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded (`rate_limit_error`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"Unexpected server error (`api_error`). Retry with backoff and quote the request id to support.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["type","message","request_id"],"properties":{"type":{"type":"string","enum":["authentication_error","permission_error","rate_limit_error","invalid_request_error","idempotency_error","api_error"]},"code":{"type":"string","description":"Machine-readable detail, e.g. `resource_missing`, `parameter_invalid`, `parameter_missing`, `missing_scope`, `route_not_found`."},"message":{"type":"string","description":"Human-readable; safe to log."},"param":{"type":"string","description":"Dotted path of the offending field, e.g. `variants.0.price`."},"request_id":{"type":"string"}}}},"example":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"variants.0.price: price must be an integer amount in minor units, e.g. 1999 for $19.99","param":"variants.0.price","request_id":"req_3f1c9a0e2b7d4c6a8e9f0a1b"}}},"Store":{"type":"object","properties":{"object":{"const":"store"},"id":{"type":"string"},"name":{"type":"string"},"subdomain":{"type":"string"},"url":{"type":"string","format":"uri","description":"Primary storefront URL (custom domain when verified)."},"currency":{"type":"string","description":"ISO 4217, lowercase (e.g. `usd`)."},"timezone":{"type":"string"},"status":{"type":"string"},"description":{"type":["string","null"]},"contact_email":{"type":["string","null"]},"logo_url":{"type":["string","null"]},"published_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Variant":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string","description":"Option values joined with \" / \", or \"Default\"."},"sku":{"type":["string","null"]},"barcode":{"type":["string","null"]},"price":{"type":"integer","minimum":0,"description":"Amount in integer minor units (e.g. 1999 = $19.99 USD)."},"compare_at_price":{"type":["integer","null"],"minimum":0,"description":"Amount in integer minor units, or null."},"inventory_quantity":{"type":"integer","description":"Total available across all locations."},"track_inventory":{"type":"boolean"},"allow_backorder":{"type":"boolean"},"weight_grams":{"type":["integer","null"]},"option1":{"type":["string","null"]},"option2":{"type":["string","null"]},"option3":{"type":["string","null"]}}},"Product":{"type":"object","properties":{"object":{"const":"product"},"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"vendor":{"type":["string","null"]},"product_type":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"requires_shipping":{"type":"boolean"},"seo":{"type":"object","properties":{"title":{"type":["string","null"]},"description":{"type":["string","null"]}}},"currency":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}}}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}},"images":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"alt":{"type":"string"}}}},"category_ids":{"type":"array","items":{"type":"string"},"description":"API responses only (not in webhook payloads)."},"collection_ids":{"type":"array","items":{"type":"string"},"description":"API responses only (not in webhook payloads)."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"VariantInput":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"PATCH only: id of an existing variant of this product to update in place. Omit to create a new variant."},"option1":{"type":["string","null"],"maxLength":120},"option2":{"type":["string","null"],"maxLength":120},"option3":{"type":["string","null"],"maxLength":120},"price":{"type":"integer","minimum":0,"description":"Required for new variants. Integer minor units."},"compare_at_price":{"type":["integer","null"],"minimum":0,"description":"Amount in integer minor units, or null."},"cost":{"type":["integer","null"],"minimum":0,"description":"Unit cost in minor units (private; not returned)."},"sku":{"type":["string","null"],"maxLength":100},"barcode":{"type":["string","null"],"maxLength":100},"inventory_quantity":{"type":"integer","minimum":-100000,"maximum":10000000,"description":"Available quantity at the default location. New variants default to 0."},"track_inventory":{"type":"boolean","default":true},"allow_backorder":{"type":"boolean","default":false},"weight_grams":{"type":["number","null"],"minimum":0},"weight_unit":{"type":"string","enum":["g","kg","oz","lb"],"description":"Unit the dashboard displays the weight in (storage is always grams)."}}},"ProductCreate":{"type":"object","additionalProperties":false,"required":["name","variants"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"handle":{"type":"string","maxLength":200,"description":"URL handle (/products/{handle}). Generated from the name when omitted."},"description":{"type":"string","maxLength":50000,"description":"HTML description."},"status":{"type":"string","enum":["draft","active","archived"],"default":"draft"},"vendor":{"type":["string","null"],"maxLength":120},"product_type":{"type":["string","null"],"maxLength":120},"tags":{"type":"array","items":{"type":"string","maxLength":60},"maxItems":50},"requires_shipping":{"type":"boolean","default":true},"seo":{"type":"object","additionalProperties":false,"properties":{"title":{"type":["string","null"],"maxLength":120},"description":{"type":["string","null"],"maxLength":320}}},"options":{"type":"array","maxItems":3,"items":{"type":"object","required":["name","values"],"additionalProperties":false,"properties":{"name":{"type":"string"},"values":{"type":"array","items":{"type":"string"},"minItems":1}}}},"variants":{"type":"array","minItems":1,"maxItems":250,"items":{"$ref":"#/components/schemas/VariantInput"},"description":"At least one variant with a price."},"category_ids":{"type":"array","items":{"type":"string"},"description":"Category ids from this store (unknown ids are ignored)."},"collection_ids":{"type":"array","items":{"type":"string"},"description":"Manual collection ids from this store (unknown and rule-based ids are ignored)."}}},"ProductUpdate":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"handle":{"type":"string","maxLength":200,"description":"URL handle (/products/{handle}). Generated from the name when omitted."},"description":{"type":"string","maxLength":50000,"description":"HTML description."},"status":{"type":"string","enum":["draft","active","archived"],"default":"draft"},"vendor":{"type":["string","null"],"maxLength":120},"product_type":{"type":["string","null"],"maxLength":120},"tags":{"type":"array","items":{"type":"string","maxLength":60},"maxItems":50},"requires_shipping":{"type":"boolean","default":true},"seo":{"type":"object","additionalProperties":false,"properties":{"title":{"type":["string","null"],"maxLength":120},"description":{"type":["string","null"],"maxLength":320}}},"options":{"type":"array","maxItems":3,"items":{"type":"object","required":["name","values"],"additionalProperties":false,"properties":{"name":{"type":"string"},"values":{"type":"array","items":{"type":"string"},"minItems":1}}}},"variants":{"type":"array","minItems":1,"maxItems":250,"items":{"$ref":"#/components/schemas/VariantInput"},"description":"When given, the complete list of variants: listed ids are updated in place, entries without an id are created, and unlisted variants are deleted. Omit to leave variants unchanged."},"category_ids":{"type":"array","items":{"type":"string"},"description":"Category ids from this store (unknown ids are ignored)."},"collection_ids":{"type":"array","items":{"type":"string"},"description":"Manual collection ids from this store (unknown and rule-based ids are ignored)."}}},"DeletedProduct":{"type":"object","properties":{"object":{"const":"product"},"id":{"type":"string"},"deleted":{"const":true}}},"Collection":{"type":"object","properties":{"object":{"const":"collection"},"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"type":{"type":"string","enum":["manual","rule"]},"published":{"type":"boolean"},"image_url":{"type":["string","null"]},"products_count":{"type":"integer","description":"Manually assigned products."}}},"Location":{"type":"object","properties":{"object":{"const":"location"},"id":{"type":"string"},"name":{"type":"string"},"is_default":{"type":"boolean"},"address":{"type":["object","null"],"properties":{"line1":{"type":["string","null"]},"line2":{"type":["string","null"]},"city":{"type":["string","null"]},"region":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"country":{"type":["string","null"]},"phone":{"type":["string","null"]}}},"available_total":{"type":"integer","description":"Units available at this location across all variants."}}},"InventoryLevel":{"type":"object","properties":{"object":{"const":"inventory_level"},"variant_id":{"type":"string"},"product_id":{"type":"string"},"product_name":{"type":"string"},"variant_title":{"type":"string"},"sku":{"type":["string","null"]},"location_id":{"type":["string","null"],"description":"Null when the level is the total across locations."},"available":{"type":"integer"}}},"InventoryLevelSet":{"type":"object","required":["variant_id","available"],"additionalProperties":false,"properties":{"variant_id":{"type":"string"},"location_id":{"type":["string","null"],"description":"Defaults to the store's default location."},"available":{"type":"integer","minimum":-100000,"maximum":10000000,"description":"The new absolute quantity."}}},"InventoryLevelSetResult":{"allOf":[{"$ref":"#/components/schemas/InventoryLevel"},{"type":"object","properties":{"available_total":{"type":"integer","description":"Total across all locations after the change."}}}]},"Address":{"type":"object","properties":{"name":{"type":"string"},"line1":{"type":"string"},"line2":{"type":["string","null"]},"city":{"type":"string"},"region":{"type":["string","null"]},"postal_code":{"type":"string"},"country":{"type":"string"},"phone":{"type":["string","null"]}}},"LineItem":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":["string","null"]},"variant_id":{"type":["string","null"]},"name":{"type":"string"},"variant_title":{"type":["string","null"]},"sku":{"type":["string","null"]},"price":{"type":"integer","minimum":0,"description":"Unit price in minor units."},"quantity":{"type":"integer"},"total":{"type":"integer","minimum":0,"description":"Amount in integer minor units (e.g. 1999 = $19.99 USD)."},"fulfilled_quantity":{"type":"integer"},"requires_shipping":{"type":"boolean"}}},"Fulfillment":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"carrier":{"type":["string","null"]},"tracking_number":{"type":["string","null"]},"tracking_url":{"type":["string","null"]},"lines":{"type":"array","items":{"type":"object","properties":{"line_item_id":{"type":"string"},"quantity":{"type":"integer"}}}},"created_at":{"type":"string","format":"date-time"}}},"Order":{"type":"object","properties":{"object":{"const":"order"},"id":{"type":"string"},"order_number":{"type":"integer","description":"Human-facing number, e.g. 1001 (shown as #1001)."},"email":{"type":"string"},"phone":{"type":["string","null"]},"currency":{"type":"string"},"source":{"type":"string","description":"e.g. `online` or `pos`."},"status":{"type":"string","description":"`open` or `cancelled`."},"payment_status":{"type":"string"},"fulfillment_status":{"type":"string","description":"`unfulfilled`, `partially_fulfilled` or `fulfilled`."},"subtotal":{"type":"integer","minimum":0,"description":"Amount in integer minor units (e.g. 1999 = $19.99 USD)."},"discount_total":{"type":"integer","minimum":0,"description":"Amount in integer minor units (e.g. 1999 = $19.99 USD)."},"shipping_total":{"type":"integer","minimum":0,"description":"Amount in integer minor units (e.g. 1999 = $19.99 USD)."},"tax_total":{"type":"integer","minimum":0,"description":"Amount in integer minor units (e.g. 1999 = $19.99 USD)."},"total":{"type":"integer","minimum":0,"description":"Amount in integer minor units (e.g. 1999 = $19.99 USD)."},"gift_card_total":{"type":"integer","minimum":0,"description":"Amount in integer minor units (e.g. 1999 = $19.99 USD)."},"refunded_total":{"type":"integer","minimum":0,"description":"Amount in integer minor units (e.g. 1999 = $19.99 USD)."},"discount_codes":{"type":"array","items":{"type":"string"}},"shipping_method":{"type":["string","null"]},"customer_id":{"type":["string","null"]},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"shipping_address":{"oneOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"fulfillments":{"type":"array","items":{"$ref":"#/components/schemas/Fulfillment"}},"refunds":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"integer","minimum":0,"description":"Amount in integer minor units (e.g. 1999 = $19.99 USD)."},"reason":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}}},"placed_at":{"type":"string","format":"date-time"},"cancelled_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"FulfillmentCreate":{"type":"object","additionalProperties":false,"properties":{"carrier":{"type":["string","null"],"maxLength":60,"example":"UPS"},"tracking_number":{"type":["string","null"],"maxLength":120},"tracking_url":{"type":["string","null"],"format":"uri","description":"Guessed from carrier + tracking number for common carriers when omitted."},"notify_customer":{"type":"boolean","default":true},"line_items":{"type":"array","minItems":1,"items":{"type":"object","required":["id","quantity"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Order line item id."},"quantity":{"type":"integer","minimum":1}}},"description":"Partial fulfillment. Omit to fulfill everything remaining."}}},"FulfillmentResult":{"allOf":[{"$ref":"#/components/schemas/Fulfillment"},{"type":"object","properties":{"object":{"const":"fulfillment"},"order_id":{"type":"string"},"order":{"$ref":"#/components/schemas/Order"}}}]},"Customer":{"type":"object","properties":{"object":{"const":"customer"},"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"phone":{"type":["string","null"]},"accepts_marketing":{"type":"boolean"},"orders_count":{"type":"integer"},"total_spent":{"type":"integer","minimum":0,"description":"Amount in integer minor units (e.g. 1999 = $19.99 USD)."},"last_order_at":{"type":["string","null"],"format":"date-time"},"tags":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CustomerDetail":{"allOf":[{"$ref":"#/components/schemas/Customer"},{"type":"object","properties":{"addresses":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"id":{"type":"string"},"is_default":{"type":"boolean"}}}]}}}}]}}},"x-webhook-signature":{"header":"Merchant-House-Signature","format":"t=<unix seconds>,v1=<hex HMAC-SHA256>","signed_payload":"<t>.<raw request body>","key":"The endpoint signing secret (whsec_...), shown in Dashboard → Settings → Developers when you add a webhook endpoint.","tolerance_seconds":300,"events":["order.created","order.fulfilled","order.refunded","order.cancelled","product.created","product.updated","product.deleted","inventory.updated"],"retries":"Failed deliveries are retried after 1 min, 5 min, 30 min, 2 h, 12 h and 24 h; an endpoint is disabled after 50 consecutive failures."}}