{"components":{"responses":{},"schemas":{"Account":{"additionalProperties":false,"properties":{"country":{"nullable":true,"type":"string"},"created_at":{"format":"date-time","type":"string"},"currency":{"nullable":true,"type":"string"},"id":{"format":"uuid","type":"string"},"language":{"nullable":true,"type":"string"},"name":{"type":"string"},"owner":{"allOf":[{"$ref":"#/components/schemas/User"}],"nullable":true},"payment_method_on_file":{"type":"boolean"},"slug":{"type":"string"},"status":{"enum":["lead","active","inactive","test"],"type":"string"},"timezone":{"nullable":true,"type":"string"},"website":{"nullable":true,"type":"string"}},"title":"Account","type":"object"},"Address":{"additionalProperties":false,"properties":{"city":{"type":"string"},"company":{"nullable":true,"type":"string"},"country":{"description":"ISO 3166-1 alpha-2","example":"AU","type":"string"},"line1":{"type":"string"},"line2":{"nullable":true,"type":"string"},"postcode":{"type":"string"},"state":{"description":"Required for AU, US, CA, IN, BR, MX","nullable":true,"type":"string"}},"required":["line1","city","postcode","country"],"title":"Address","type":"object"},"CollectionRef":{"additionalProperties":false,"properties":{"id":{"format":"uuid","type":"string"},"name":{"type":"string"}},"title":"CollectionRef","type":"object"},"CustomDomain":{"additionalProperties":false,"properties":{"activated_at":{"format":"date-time","nullable":true,"type":"string"},"canonical":{"type":"boolean"},"domain":{"type":"string"},"id":{"format":"uuid","type":"string"},"status":{"enum":["pending_dns","validating","active","failed","disabled"],"type":"string"},"verified_at":{"format":"date-time","nullable":true,"type":"string"}},"title":"CustomDomain","type":"object"},"CustomerInput":{"additionalProperties":false,"description":"Who the order is for. Matched by email within your account: an existing customer is reused, otherwise one is created.","properties":{"company":{"type":"string"},"email":{"format":"email","type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"}},"required":["first_name","last_name","email"],"title":"CustomerInput","type":"object"},"Design":{"additionalProperties":false,"description":"Fields from `description` onward are only present on single-design responses.","properties":{"collections":{"items":{"$ref":"#/components/schemas/CollectionRef"},"type":"array"},"colours":{"items":{"type":"string"},"type":"array"},"created_at":{"format":"date-time","type":"string"},"currency":{"nullable":true,"type":"string"},"delivery_type":{"enum":["delivery","pickup","delivery_and_pickup"],"nullable":true,"type":"string"},"description":{"nullable":true,"type":"string"},"id":{"description":"Public design id (nano id)","example":"d8Xk2mQz","type":"string"},"name":{"type":"string"},"personalisation_zones":{"description":"Text zones an order line can fill; empty for designs without personalisation","items":{"$ref":"#/components/schemas/PersonalisationZone"},"type":"array"},"preorder_enabled":{"type":"boolean"},"previews":{"additionalProperties":{"type":"string"},"description":"Placement name → current mockup URL","type":"object"},"product":{"allOf":[{"$ref":"#/components/schemas/DesignProduct"}],"nullable":true},"purchase_breakdown":{"allOf":[{"$ref":"#/components/schemas/PurchaseBreakdown"}],"description":"Null whenever `purchase_price` is null","nullable":true},"purchase_price":{"allOf":[{"$ref":"#/components/schemas/Money"}],"description":"What your account pays Merchable per unit, ex tax, when it places an account order for one unit. Quotes apply quantity tiers on top. Null for gift cards and designs that cannot be priced for your account's country","nullable":true},"purchase_tax":{"allOf":[{"$ref":"#/components/schemas/Money"}],"description":"Tax on `purchase_price` for one unit","nullable":true},"quantity_tiers":{"description":"The product's quantity breaks for your account's country, lowest quantity first; empty when the product has flat pricing","items":{"$ref":"#/components/schemas/QuantityTier"},"type":"array"},"retail_price":{"allOf":[{"$ref":"#/components/schemas/Money"}],"description":"The tax-inclusive retail price the design sells for in your shops. Null when the design has no price set","nullable":true},"sizes":{"items":{"type":"string"},"type":"array"},"status":{"enum":["draft","active","inactive"],"type":"string"},"stock_control_enabled":{"type":"boolean"},"thumbnail_url":{"nullable":true,"type":"string"},"updated_at":{"format":"date-time","type":"string"},"variants":{"items":{"$ref":"#/components/schemas/DesignVariant"},"type":"array"}},"title":"Design","type":"object"},"DesignProduct":{"additionalProperties":false,"properties":{"id":{"format":"uuid","type":"string"},"thumbnail_url":{"nullable":true,"type":"string"},"title":{"type":"string"}},"title":"DesignProduct","type":"object"},"DesignVariant":{"additionalProperties":false,"properties":{"active":{"type":"boolean"},"colour":{"nullable":true,"type":"string"},"id":{"description":"Use as `variant_id` on order lines","format":"uuid","type":"string"},"purchase_price":{"allOf":[{"$ref":"#/components/schemas/Money"}],"description":"What your account pays Merchable for one unit of this variant, ex tax, at quantity 1 (quotes apply quantity tiers). Not the retail price shown in your shops. Null when the design cannot be priced for your account's country","nullable":true},"purchase_tax":{"allOf":[{"$ref":"#/components/schemas/Money"}],"description":"Tax on `purchase_price` for one unit","nullable":true},"quantity":{"description":"Sellable units on the shelf; null for made-to-order variants","nullable":true,"type":"integer"},"size":{"nullable":true,"type":"string"},"sku":{"nullable":true,"type":"string"},"status":{"description":"available: orderable now; preorder: nothing on the shelf but preorders are accepted; out_of_stock: nothing on the shelf; unavailable: the design, product or variant is inactive","enum":["available","preorder","out_of_stock","unavailable"],"type":"string"}},"title":"DesignVariant","type":"object"},"Money":{"additionalProperties":false,"properties":{"amount":{"description":"Decimal string","example":"49.00","type":"string"},"currency":{"example":"AUD","type":"string"}},"required":["amount","currency"],"title":"Money","type":"object"},"NotificationSettings":{"additionalProperties":false,"properties":{"suppress_business_emails":{"description":"Do not email the account about order milestones (you handle it)","type":"boolean"},"suppress_customer_emails":{"description":"Do not email the order's customer about milestones","type":"boolean"}},"title":"NotificationSettings","type":"object"},"Order":{"additionalProperties":false,"properties":{"currency":{"nullable":true,"type":"string"},"customer":{"allOf":[{"$ref":"#/components/schemas/OrderCustomer"}],"nullable":true},"delivery":{"$ref":"#/components/schemas/OrderDelivery"},"external_reference":{"nullable":true,"type":"string"},"id":{"description":"Short order reference","example":"A1B2C3D4-E5F6","type":"string"},"is_pre_order":{"type":"boolean"},"item_count":{"description":"Units across all lines","type":"integer"},"items":{"items":{"$ref":"#/components/schemas/OrderItem"},"type":"array"},"metadata":{"additionalProperties":true,"type":"object"},"notifications":{"$ref":"#/components/schemas/NotificationSettings"},"payment_method":{"enum":["online_payment","bank_transfer"],"type":"string"},"placed_at":{"format":"date-time","type":"string"},"shipments":{"items":{"$ref":"#/components/schemas/Shipment"},"type":"array"},"source":{"enum":["web","mcp","api","shopify"],"type":"string"},"status":{"enum":["pending","pre_order","processing","production","shipped","complete","cancelled"],"type":"string"},"status_explained":{"nullable":true,"type":"string"},"timeline":{"$ref":"#/components/schemas/OrderTimeline"},"total":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"totals":{"$ref":"#/components/schemas/OrderTotals"},"uuid":{"format":"uuid","type":"string"},"webhook":{"$ref":"#/components/schemas/OrderWebhook"}},"title":"Order","type":"object"},"OrderCustomer":{"additionalProperties":false,"properties":{"company":{"nullable":true,"type":"string"},"email":{"nullable":true,"type":"string"},"first_name":{"nullable":true,"type":"string"},"last_name":{"nullable":true,"type":"string"},"name":{"type":"string"},"phone":{"nullable":true,"type":"string"}},"title":"OrderCustomer","type":"object"},"OrderDelivery":{"additionalProperties":false,"properties":{"address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_method":{"enum":["none","standard","express"],"type":"string"},"shipping_type":{"enum":["local","international"],"type":"string"},"type":{"enum":["delivery","pickup"],"type":"string"}},"title":"OrderDelivery","type":"object"},"OrderDesignRef":{"additionalProperties":false,"properties":{"id":{"description":"Design id (nano id)","type":"string"},"name":{"type":"string"},"thumbnail_url":{"nullable":true,"type":"string"}},"title":"OrderDesignRef","type":"object"},"OrderEvent":{"additionalProperties":false,"properties":{"data":{"additionalProperties":true,"description":"Event-specific details (e.g. tracking for order.shipped)","type":"object"},"id":{"format":"uuid","type":"string"},"occurred_at":{"format":"date-time","type":"string"},"previous_status":{"nullable":true,"type":"string"},"status":{"nullable":true,"type":"string"},"type":{"example":"order.shipped","type":"string"}},"title":"OrderEvent","type":"object"},"OrderInput":{"properties":{"customer":{"$ref":"#/components/schemas/CustomerInput"},"delivery":{"properties":{"address":{"$ref":"#/components/schemas/Address"},"shipping_method":{"default":"standard","enum":["standard","express"],"type":"string"},"type":{"default":"delivery","enum":["delivery","pickup"],"type":"string"}},"type":"object"},"external_reference":{"maxLength":120,"type":"string"},"items":{"items":{"$ref":"#/components/schemas/OrderLineInput"},"minItems":1,"type":"array"},"metadata":{"additionalProperties":true,"type":"object"},"notifications":{"$ref":"#/components/schemas/NotificationSettings"},"payment":{"properties":{"method":{"default":"default_card","description":"`default_card` charges the account's default saved card after any account credit","enum":["default_card"],"type":"string"}},"type":"object"},"webhook_secret":{"description":"HMAC secret for this order's deliveries; omit to sign with the account signing secret","maxLength":255,"type":"string"},"webhook_url":{"description":"Where to POST every lifecycle event for this order (https, public host). See the Webhooks guide","format":"uri","maxLength":2048,"type":"string"}},"required":["items"],"title":"OrderInput","type":"object"},"OrderItem":{"additionalProperties":false,"properties":{"colour":{"nullable":true,"type":"string"},"design":{"allOf":[{"$ref":"#/components/schemas/OrderDesignRef"}],"nullable":true},"id":{"format":"uuid","type":"string"},"personalisation":{"description":"Zone text on this line; empty when the line is not personalised","items":{"$ref":"#/components/schemas/OrderItemPersonalisation"},"type":"array"},"quantity":{"type":"integer"},"size":{"nullable":true,"type":"string"},"status":{"description":"Pickup progress; null for delivered lines","enum":["awaiting_collection","complete"],"nullable":true,"type":"string"},"total_price":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"unit_price":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"variant_id":{"format":"uuid","nullable":true,"type":"string"}},"title":"OrderItem","type":"object"},"OrderItemPersonalisation":{"additionalProperties":false,"properties":{"label":{"nullable":true,"type":"string"},"placement":{"nullable":true,"type":"string"},"text":{"type":"string"},"zone_id":{"format":"uuid","type":"string"}},"title":"OrderItemPersonalisation","type":"object"},"OrderLineInput":{"description":"Identify the variant by `variant_id`, or by `colour` and/or `size`","properties":{"colour":{"type":"string"},"design_id":{"example":"d8Xk2mQz","type":"string"},"personalisation":{"description":"Text for the design's personalisation zones. A personalised line is always its own order line; every required zone must be filled. Omit to order the design with its zones empty (not printed, not charged)","items":{"$ref":"#/components/schemas/PersonalisationInput"},"type":"array"},"quantity":{"minimum":1,"type":"integer"},"size":{"type":"string"},"variant_id":{"format":"uuid","type":"string"}},"required":["design_id","quantity"],"title":"OrderLineInput","type":"object"},"OrderQuote":{"additionalProperties":false,"properties":{"currency":{"type":"string"},"delivery":{"additionalProperties":false,"properties":{"shipping_method":{"enum":["none","standard","express"],"nullable":true,"type":"string"},"type":{"enum":["delivery","pickup"],"type":"string"}},"type":"object"},"items":{"items":{"additionalProperties":false,"properties":{"design_id":{"nullable":true,"type":"string"},"personalisation":{"items":{"$ref":"#/components/schemas/OrderItemPersonalisation"},"type":"array"},"quantity":{"type":"integer"},"total_price":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"total_tax":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"unit_price":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"unit_tax":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"variant_id":{"format":"uuid","nullable":true,"type":"string"}},"type":"object"},"type":"array"},"minimum_quantity_violations":{"description":"Human-readable MOQ shortfalls; placing the order fails while non-empty","items":{"type":"string"},"type":"array"},"totals":{"additionalProperties":false,"properties":{"payment_processing_fee_ex_tax":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"payment_processing_fee_tax":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"products_ex_tax":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"products_tax":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"shipping_ex_tax":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"shipping_tax":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"tax":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"total":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"total_ex_tax":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true}},"type":"object"}},"title":"OrderQuote","type":"object"},"OrderTimeline":{"additionalProperties":false,"properties":{"approved_at":{"format":"date-time","nullable":true,"type":"string"},"completed_at":{"format":"date-time","nullable":true,"type":"string"},"delivered_at":{"format":"date-time","nullable":true,"type":"string"},"placed_at":{"format":"date-time","nullable":true,"type":"string"},"sent_to_production_at":{"format":"date-time","nullable":true,"type":"string"},"shipped_at":{"format":"date-time","nullable":true,"type":"string"}},"title":"OrderTimeline","type":"object"},"OrderTotals":{"additionalProperties":false,"properties":{"credit_applied":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"currency":{"nullable":true,"type":"string"},"discount":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"payment_processing_fee_ex_tax":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"payment_processing_fee_tax":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"platform_fee_ex_tax":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"platform_fee_tax":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"products_ex_tax":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"products_tax":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"shipping_ex_tax":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"shipping_tax":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"tax":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"total":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true},"total_ex_tax":{"allOf":[{"$ref":"#/components/schemas/Money"}],"nullable":true}},"title":"OrderTotals","type":"object"},"OrderWebhook":{"additionalProperties":false,"description":"The order's webhook target; the secret is never returned","properties":{"configured":{"description":"True when the order carries its own signing secret","type":"boolean"},"url":{"nullable":true,"type":"string"}},"title":"OrderWebhook","type":"object"},"PageInfo":{"additionalProperties":false,"properties":{"has_more":{"type":"boolean"},"next_cursor":{"nullable":true,"type":"string"},"total":{"nullable":true,"type":"integer"}},"required":["has_more"],"title":"PageInfo","type":"object"},"PersonalisationInput":{"properties":{"text":{"description":"The customer's text, within the zone's character limits","example":"SMITH","type":"string"},"zone_id":{"description":"A `personalisation_zones[].id` from `GET /v1/designs/{id}`","format":"uuid","type":"string"}},"required":["zone_id","text"],"title":"PersonalisationInput","type":"object"},"PersonalisationZone":{"additionalProperties":false,"description":"A text zone on the design a customer's own words print into (a name on the back, for example). Fill it on an order line with `personalisation`","properties":{"id":{"description":"Use as `zone_id` on order lines","format":"uuid","type":"string"},"label":{"description":"What the customer sees, e.g. \"Player name\"","type":"string"},"max_characters":{"type":"integer"},"min_characters":{"type":"integer"},"placeholder":{"nullable":true,"type":"string"},"placement":{"description":"Placement the text prints on, e.g. `back`","nullable":true,"type":"string"},"required":{"description":"A personalised line must fill this zone (lines without personalisation leave every zone empty)","type":"boolean"}},"title":"PersonalisationZone","type":"object"},"Problem":{"additionalProperties":false,"description":"RFC 9457 problem details (application/problem+json)","properties":{"detail":{"type":"string"},"errors":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"description":"Field-level messages keyed by dotted request path, e.g. `items.0.quantity`. Present only on validation failures attributable to specific fields.","type":"object"},"request_id":{"nullable":true,"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"example":"https://api.merchable.co/docs/errors#validation","type":"string"}},"required":["type","title","status","detail"],"title":"Problem","type":"object"},"PurchaseBreakdown":{"additionalProperties":false,"description":"How the design's `purchase_price` — what your account pays Merchable per unit, ex tax — is made up. The three parts sum to `purchase_price`.","properties":{"extra_placement_fees":{"allOf":[{"$ref":"#/components/schemas/Money"}],"description":"Fees for print placements beyond the one the product includes"},"print_method_premium":{"allOf":[{"$ref":"#/components/schemas/Money"}],"description":"Premium for the design's print method"},"product_base":{"allOf":[{"$ref":"#/components/schemas/Money"}],"description":"The blank product at quantity 1 (the first quantity tier, if any)"}},"title":"PurchaseBreakdown","type":"object"},"QuantityTier":{"additionalProperties":false,"description":"A quantity break on the product's purchase price. The tier that covers the summed quantity of a product across an order sets the per-unit product price; quotes and orders apply it automatically.","properties":{"max_quantity":{"description":"Last quantity the tier covers; null for an open-ended tier","nullable":true,"type":"integer"},"min_quantity":{"description":"First quantity the tier covers","type":"integer"},"price":{"allOf":[{"$ref":"#/components/schemas/Money"}],"description":"Per-unit product price your account pays Merchable at this tier, ex tax, before extra placement fees and print method premium"}},"title":"QuantityTier","type":"object"},"Shipment":{"additionalProperties":false,"properties":{"carrier":{"nullable":true,"type":"string"},"delivered_at":{"format":"date-time","nullable":true,"type":"string"},"id":{"format":"uuid","type":"string"},"shipped_at":{"format":"date-time","nullable":true,"type":"string"},"supplier":{"nullable":true,"type":"string"},"tracking_number":{"nullable":true,"type":"string"},"tracking_url":{"nullable":true,"type":"string"}},"title":"Shipment","type":"object"},"ShippingDestinationInput":{"properties":{"city":{"nullable":true,"type":"string"},"country":{"description":"ISO 3166-1 alpha-2","example":"AU","type":"string"},"postcode":{"nullable":true,"type":"string"},"state":{"nullable":true,"type":"string"}},"required":["country"],"title":"ShippingDestinationInput","type":"object"},"ShippingEstimate":{"additionalProperties":false,"properties":{"currency":{"type":"string"},"destination":{"additionalProperties":false,"properties":{"city":{"nullable":true,"type":"string"},"country":{"type":"string"},"postcode":{"nullable":true,"type":"string"},"state":{"nullable":true,"type":"string"}},"type":"object"},"international":{"type":"boolean"},"items":{"items":{"additionalProperties":false,"properties":{"design_id":{"type":"string"},"quantity":{"type":"integer"},"requires_shipping":{"type":"boolean"},"variant_id":{"format":"uuid","nullable":true,"type":"string"}},"type":"object"},"type":"array"},"methods":{"items":{"additionalProperties":false,"properties":{"amount_ex_tax":{"$ref":"#/components/schemas/Money"},"delivery_estimate":{"nullable":true,"type":"string"},"method":{"enum":["standard","express"],"type":"string"},"tax":{"$ref":"#/components/schemas/Money"},"total":{"$ref":"#/components/schemas/Money"}},"type":"object"},"type":"array"},"origin_country":{"type":"string"},"requires_shipping":{"type":"boolean"}},"title":"ShippingEstimate","type":"object"},"ShippingEstimateInput":{"properties":{"destination":{"$ref":"#/components/schemas/ShippingDestinationInput"},"items":{"items":{"$ref":"#/components/schemas/OrderLineInput"},"minItems":1,"type":"array"},"shipping_method":{"enum":["standard","express"],"nullable":true,"type":"string"}},"required":["items","destination"],"title":"ShippingEstimateInput","type":"object"},"Shop":{"additionalProperties":false,"description":"Fields from `description` onward are only present on single-shop responses.","properties":{"banner_text":{"nullable":true,"type":"string"},"banner_url":{"nullable":true,"type":"string"},"colour_overrides":{"allOf":[{"$ref":"#/components/schemas/ThemeColours"}],"description":"Only the colours the shop overrides; the rest inherit from the theme"},"created_at":{"format":"date-time","type":"string"},"custom_domains":{"items":{"$ref":"#/components/schemas/CustomDomain"},"type":"array"},"description":{"nullable":true,"type":"string"},"footer_text":{"nullable":true,"type":"string"},"id":{"format":"uuid","type":"string"},"logo_url":{"nullable":true,"type":"string"},"name":{"type":"string"},"published":{"type":"boolean"},"resolved_colours":{"$ref":"#/components/schemas/ThemeColours"},"seo":{"additionalProperties":false,"properties":{"meta_description":{"nullable":true,"type":"string"},"meta_title":{"nullable":true,"type":"string"}},"type":"object"},"slug":{"type":"string"},"status":{"enum":["active","inactive"],"type":"string"},"theme":{"allOf":[{"$ref":"#/components/schemas/Theme"}],"nullable":true},"type":{"enum":["brand","event","staff","loyalty"],"type":"string"},"updated_at":{"format":"date-time","type":"string"},"url":{"type":"string"}},"title":"Shop","type":"object"},"ShopCollection":{"additionalProperties":false,"properties":{"active":{"description":"Hidden from the storefront when false","type":"boolean"},"design_count":{"nullable":true,"type":"integer"},"id":{"format":"uuid","type":"string"},"name":{"type":"string"},"order":{"type":"integer"}},"title":"ShopCollection","type":"object"},"Theme":{"additionalProperties":false,"properties":{"colours":{"$ref":"#/components/schemas/ThemeColours"},"description":{"nullable":true,"type":"string"},"id":{"format":"uuid","type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"type":{"enum":["preset","custom"],"type":"string"}},"title":"Theme","type":"object"},"ThemeColours":{"additionalProperties":false,"properties":{"header_text_color":{"nullable":true,"type":"string"},"overlay_color":{"nullable":true,"type":"string"},"overlay_opacity":{"maximum":100,"minimum":0,"nullable":true,"type":"integer"},"primary_color":{"example":"#FF5A1F","nullable":true,"type":"string"},"secondary_color":{"nullable":true,"type":"string"}},"title":"ThemeColours","type":"object"},"User":{"additionalProperties":false,"properties":{"email":{"type":"string"},"name":{"type":"string"}},"title":"User","type":"object"}},"securitySchemes":{"bearerAuth":{"description":"An `mchp_` account API key or an `mcho_` OAuth access token.","scheme":"bearer","type":"http"},"oauth2":{"flows":{"authorizationCode":{"authorizationUrl":"https://app.merchable.co/oauth/authorize","refreshUrl":"https://app.merchable.co/oauth/token","scopes":{"account:read":"Read your account profile","designs:read":"Read your designs, their variants, prices and stock","mcp":"Full access for AI chat clients connected over MCP","orders:read":"Read orders, shipments and order events","orders:write":"Place, quote and cancel orders","shops:read":"Read your shops, their designs and collections"},"tokenUrl":"https://app.merchable.co/oauth/token"}},"type":"oauth2"}}},"info":{"description":"Place account orders from your own systems: read your designs (with the\nvariant ids, unit prices and stock an order line needs), quote and place\norders, track fulfilment, and receive webhooks. Account, shop and design\ndata are read-only in v1.\n\nAll requests need a Bearer credential: an account API key (`mchp_…`)\nfrom **Settings → Developer** in app.merchable.co, or an OAuth 2.1 access\ntoken (`mcho_…`). See the guides for authentication, webhooks, pagination\nand errors.\n","title":"Merchable Account API","version":"1.0.0"},"openapi":"3.0.0","paths":{"/v1/account":{"get":{"callbacks":{},"description":"The account the credential belongs to.","operationId":"ApiWeb.V1.AccountController.show","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Account"}},"required":["data"],"type":"object"}}},"description":"OK"},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Missing or invalid credential"},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Insufficient scope"},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Rate limited"}},"security":[{"bearerAuth":[]},{"oauth2":["account:read"]}],"summary":"Get the account","tags":["Account"]}},"/v1/designs":{"get":{"callbacks":{},"description":"The account's designs (archived designs excluded). Designs are read-only in the API; use `GET /v1/designs/{id}` for the variants, prices and stock an order needs.","operationId":"ApiWeb.V1.DesignController.index","parameters":[{"description":"draft | active | inactive","in":"query","name":"status","required":false,"schema":{"type":"string"}},{"description":"1–100, default 25","in":"query","name":"limit","required":false,"schema":{"type":"integer"}},{"description":"`page.next_cursor` from the previous page","in":"query","name":"cursor","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/Design"},"type":"array"},"page":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page"],"type":"object"}}},"description":"OK"},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Missing or invalid credential"},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Insufficient scope"},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Rate limited"}},"security":[{"bearerAuth":[]},{"oauth2":["designs:read"]}],"summary":"List designs","tags":["Designs"]}},"/v1/designs/{id}":{"get":{"callbacks":{},"description":"The design with what your account pays Merchable per unit (`purchase_price`, its breakdown and quantity tiers) alongside the `retail_price` it sells for in your shops, and every variant inline: option names, purchase price and tax for one unit, and the stock status — everything an order line needs in one read.","operationId":"ApiWeb.V1.DesignController.show","parameters":[{"description":"Design id","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Design"}},"required":["data"],"type":"object"}}},"description":"OK"},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Missing or invalid credential"},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Insufficient scope"},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Not found"},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Rate limited"}},"security":[{"bearerAuth":[]},{"oauth2":["designs:read"]}],"summary":"Get a design","tags":["Designs"]}},"/v1/orders":{"get":{"callbacks":{},"description":"Newest first. Drafts are never included.","operationId":"ApiWeb.V1.OrderController.index","parameters":[{"description":"pending | pre_order | processing | production | shipped | complete | cancelled","in":"query","name":"status","required":false,"schema":{"type":"string"}},{"description":"web | mcp | api | shopify","in":"query","name":"source","required":false,"schema":{"type":"string"}},{"description":"","in":"query","name":"external_reference","required":false,"schema":{"type":"string"}},{"description":"ISO 8601 — placed at or after","in":"query","name":"since","required":false,"schema":{"type":"string"}},{"description":"ISO 8601 — placed at or before","in":"query","name":"until","required":false,"schema":{"type":"string"}},{"description":"1–100, default 25","in":"query","name":"limit","required":false,"schema":{"type":"integer"}},{"description":"`page.next_cursor` from the previous page","in":"query","name":"cursor","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/Order"},"type":"array"},"page":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page"],"type":"object"}}},"description":"OK"},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Missing or invalid credential"},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Insufficient scope"},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Rate limited"}},"security":[{"bearerAuth":[]},{"oauth2":["orders:read"]}],"summary":"List orders","tags":["Orders"]},"post":{"callbacks":{},"description":"Places an account order: the account buys stock from Merchable at production\ncost. Payment is the account's default saved card (`payment.method:\n\"default_card\"`, the only method) after any account credit; without a saved\ncard the request fails with `422`.\n\nRequires an `Idempotency-Key` header. Repeating a request with the same key\nand body replays the original response instead of placing a second order.\n","operationId":"ApiWeb.V1.OrderController.create","parameters":[{"description":"Unique per order attempt","in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderInput"}}},"description":"Order","required":true},"responses":{"201":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Order"}},"required":["data"],"type":"object"}}},"description":"Created"},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Malformed request"},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Missing or invalid credential"},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Insufficient scope"},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Idempotency conflict"},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Validation failed"},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Rate limited"}},"security":[{"bearerAuth":[]},{"oauth2":["orders:write"]}],"summary":"Place an order","tags":["Orders"]}},"/v1/orders/quote":{"post":{"callbacks":{},"description":"Prices the order exactly as `POST /v1/orders` would, without placing it.","operationId":"ApiWeb.V1.OrderController.quote","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderInput"}}},"description":"Order","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/OrderQuote"}},"required":["data"],"type":"object"}}},"description":"OK"},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Missing or invalid credential"},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Insufficient scope"},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Validation failed"},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Rate limited"}},"security":[{"bearerAuth":[]},{"oauth2":["orders:write"]}],"summary":"Quote an order","tags":["Orders"]}},"/v1/orders/{id}":{"get":{"callbacks":{},"operationId":"ApiWeb.V1.OrderController.show","parameters":[{"description":"Order reference (A1B2C3D4-E5F6) or UUID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Order"}},"required":["data"],"type":"object"}}},"description":"OK"},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Missing or invalid credential"},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Insufficient scope"},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Not found"},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Rate limited"}},"security":[{"bearerAuth":[]},{"oauth2":["orders:read"]}],"summary":"Get an order","tags":["Orders"]}},"/v1/orders/{id}/cancel":{"post":{"callbacks":{},"description":"Only orders that have not entered production can be cancelled.","operationId":"ApiWeb.V1.OrderController.cancel","parameters":[{"description":"","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Order"}},"required":["data"],"type":"object"}}},"description":"OK"},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Missing or invalid credential"},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Insufficient scope"},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Not found"},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Not cancellable"},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Rate limited"}},"security":[{"bearerAuth":[]},{"oauth2":["orders:write"]}],"summary":"Cancel an order","tags":["Orders"]}},"/v1/orders/{id}/events":{"get":{"callbacks":{},"operationId":"ApiWeb.V1.OrderController.events","parameters":[{"description":"","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"1–100, default 25","in":"query","name":"limit","required":false,"schema":{"type":"integer"}},{"description":"`page.next_cursor` from the previous page","in":"query","name":"cursor","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/OrderEvent"},"type":"array"},"page":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page"],"type":"object"}}},"description":"OK"},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Missing or invalid credential"},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Insufficient scope"},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Not found"},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Rate limited"}},"security":[{"bearerAuth":[]},{"oauth2":["orders:read"]}],"summary":"List an order's lifecycle events","tags":["Orders"]}},"/v1/orders/{id}/shipments":{"get":{"callbacks":{},"operationId":"ApiWeb.V1.OrderController.shipments","parameters":[{"description":"","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"1–100, default 25","in":"query","name":"limit","required":false,"schema":{"type":"integer"}},{"description":"`page.next_cursor` from the previous page","in":"query","name":"cursor","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/Shipment"},"type":"array"},"page":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page"],"type":"object"}}},"description":"OK"},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Missing or invalid credential"},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Insufficient scope"},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Not found"},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Rate limited"}},"security":[{"bearerAuth":[]},{"oauth2":["orders:read"]}],"summary":"List an order's shipments","tags":["Orders"]}},"/v1/shipping/estimate":{"post":{"callbacks":{},"description":"Shipping cost for a set of items to a destination, priced exactly as an order\nwould be. Returns every shipping method available to the destination (or just\nthe one requested) with ex-tax, tax and total amounts plus a delivery estimate.\nNothing is persisted.\n","operationId":"ApiWeb.V1.ShippingController.estimate","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingEstimateInput"}}},"description":"Items and destination","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ShippingEstimate"}},"required":["data"],"type":"object"}}},"description":"OK"},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Missing or invalid credential"},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Insufficient scope"},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Validation failed"},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Rate limited"}},"security":[{"bearerAuth":[]},{"oauth2":["orders:read"]}],"summary":"Estimate shipping","tags":["Orders"]}},"/v1/shops":{"get":{"callbacks":{},"operationId":"ApiWeb.V1.ShopController.index","parameters":[{"description":"1–100, default 25","in":"query","name":"limit","required":false,"schema":{"type":"integer"}},{"description":"`page.next_cursor` from the previous page","in":"query","name":"cursor","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/Shop"},"type":"array"},"page":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page"],"type":"object"}}},"description":"OK"},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Missing or invalid credential"},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Insufficient scope"},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Rate limited"}},"security":[{"bearerAuth":[]},{"oauth2":["shops:read"]}],"summary":"List shops","tags":["Shops"]}},"/v1/shops/{id}":{"get":{"callbacks":{},"operationId":"ApiWeb.V1.ShopController.show","parameters":[{"description":"Shop id or slug","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Shop"}},"required":["data"],"type":"object"}}},"description":"OK"},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Missing or invalid credential"},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Insufficient scope"},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Not found"},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Rate limited"}},"security":[{"bearerAuth":[]},{"oauth2":["shops:read"]}],"summary":"Get a shop","tags":["Shops"]}},"/v1/shops/{id}/collections":{"get":{"callbacks":{},"description":"The collections shown on the shop's storefront, in storefront order.","operationId":"ApiWeb.V1.ShopController.collections","parameters":[{"description":"Shop id or slug","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"1–100, default 25","in":"query","name":"limit","required":false,"schema":{"type":"integer"}},{"description":"`page.next_cursor` from the previous page","in":"query","name":"cursor","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/ShopCollection"},"type":"array"},"page":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page"],"type":"object"}}},"description":"OK"},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Missing or invalid credential"},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Insufficient scope"},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Not found"},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Rate limited"}},"security":[{"bearerAuth":[]},{"oauth2":["shops:read"]}],"summary":"List a shop's collections","tags":["Shops"]}},"/v1/shops/{id}/designs":{"get":{"callbacks":{},"operationId":"ApiWeb.V1.ShopDesignController.index","parameters":[{"description":"Shop id or slug","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"1–100, default 25","in":"query","name":"limit","required":false,"schema":{"type":"integer"}},{"description":"`page.next_cursor` from the previous page","in":"query","name":"cursor","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/Design"},"type":"array"},"page":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page"],"type":"object"}}},"description":"OK"},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Missing or invalid credential"},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Insufficient scope"},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Not found"},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Rate limited"}},"security":[{"bearerAuth":[]},{"oauth2":["shops:read"]}],"summary":"List shop designs","tags":["Shops"]}}},"security":[{"bearerAuth":[]},{"oauth2":[]}],"servers":[{"url":"https://api.merchable.co","variables":{}}],"tags":[{"description":"The account the credential belongs to","name":"Account"},{"description":"Designs and their orderable variants (read-only)","name":"Designs"},{"description":"Shops, their designs and collections (read-only)","name":"Shops"},{"description":"Quote, place, track and cancel account orders","name":"Orders"}]}