{"openapi":"3.0.3","info":{"title":"LaundryOS API","version":"1.0.0","description":"Build your own storefront on LaundryOS. Authenticate every request with your tenant API key (created in the Business Portal under Developers). Send it as `X-API-Key: <key>` or `Authorization: Bearer <key>`. Keys are scoped; each endpoint below lists the scope it needs. Keys come in `test` and `live` modes (prefix `los_test_` / `los_live_`)."},"servers":[{"url":"https://api.laundryosapp.com/api/v1","description":"Production"}],"security":[{"ApiKeyHeader":[]},{"BearerKey":[]}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"},"BearerKey":{"type":"http","scheme":"bearer","bearerFormat":"LaundryOS API key"}},"schemas":{"Error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"Customer":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"externalId":{"type":"string","nullable":true},"fullName":{"type":"string"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"CreateCustomer":{"type":"object","properties":{"externalId":{"type":"string","description":"Your own user id. Create-or-link is idempotent on it."},"fullName":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"locale":{"type":"string"}}},"CreateOrder":{"type":"object","required":["customerId","serviceId","serviceType","slotId","date"],"properties":{"customerId":{"type":"string","format":"uuid"},"serviceId":{"type":"string","format":"uuid"},"serviceType":{"type":"string","enum":["self_wash","drop_off","pickup_delivery"]},"slotId":{"type":"string","format":"uuid"},"date":{"type":"string","example":"2026-10-22"},"branch":{"type":"string","description":"Branch id or slug; omit for the default branch."},"items":{"type":"array","items":{"type":"object","properties":{"garmentId":{"type":"string"},"quantity":{"type":"number"},"colour":{"type":"string"}}}},"estimatedWeightKg":{"type":"number","description":"For per-kg services."},"addons":{"type":"array","items":{"type":"object","properties":{"addonId":{"type":"string"},"quantity":{"type":"number"}}}},"express":{"type":"boolean"},"deliveryAreaId":{"type":"string"},"pickupAddress":{"type":"object"},"deliveryAddress":{"type":"object"},"notes":{"type":"string"}}},"Order":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"status":{"type":"string"},"estimatedTotalMinor":{"type":"integer"},"currency":{"type":"string"},"serviceName":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"Checkout":{"type":"object","required":["customerId"],"properties":{"customerId":{"type":"string","format":"uuid"}}},"CheckoutResult":{"type":"object","properties":{"authorizationUrl":{"type":"string"},"reference":{"type":"string"},"paymentId":{"type":"string"}}},"PaymentStatus":{"type":"object","properties":{"orderId":{"type":"string"},"code":{"type":"string"},"amountMinor":{"type":"integer"},"currency":{"type":"string"},"dueMinor":{"type":"integer"},"paid":{"type":"boolean"},"status":{"type":"string"}}}}},"paths":{"/public/catalog":{"get":{"summary":"List services, add-ons and delivery areas","x-scope":"catalog:read","parameters":[{"name":"branch","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Catalogue","content":{"application/json":{"schema":{"type":"object","properties":{"services":{"type":"array","items":{"type":"object"}},"addons":{"type":"array","items":{"type":"object"}},"areas":{"type":"array","items":{"type":"object"}}}}}}}}}},"/public/availability":{"get":{"summary":"Open booking slots for a day","x-scope":"catalog:read","parameters":[{"name":"date","in":"query","required":true,"schema":{"type":"string"}},{"name":"branch","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Slots"}}}},"/public/estimate":{"post":{"summary":"Price preview (final total with fees, express and discounts, without creating an order)","x-scope":"catalog:read","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrder"}}}},"responses":{"200":{"description":"Price breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"},"subtotalMinor":{"type":"integer"},"feesTotalMinor":{"type":"integer"},"taxTotalMinor":{"type":"integer"},"discountTotalMinor":{"type":"integer"},"totalMinor":{"type":"integer"},"isEstimate":{"type":"boolean"},"feeLines":{"type":"array","items":{"type":"object"}}}}}}}}}},"/public/customers":{"post":{"summary":"Create or link a customer","x-scope":"customers:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomer"}}}},"responses":{"200":{"description":"Customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/customers/{id}":{"get":{"summary":"Get a customer","x-scope":"customers:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"404":{"description":"Not found"}}}},"/public/customers/{id}/orders":{"get":{"summary":"List a customer's orders (newest first)","x-scope":"orders:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Order summaries","content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}}}}},"404":{"description":"Not found"}}}},"/public/promotions":{"get":{"summary":"Active promotions to display (name + description)","x-scope":"catalog:read","responses":{"200":{"description":"Active promotions","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"}}}}}}}}}},"/public/orders":{"post":{"summary":"Create an order for a customer","x-scope":"orders:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrder"}}}},"responses":{"201":{"description":"Order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"description":"Validation error"}}}},"/public/orders/{id}":{"get":{"summary":"Get an order with its status timeline","x-scope":"orders:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Order detail"},"404":{"description":"Not found"}}}},"/public/orders/{id}/checkout":{"post":{"summary":"Open a hosted checkout for an order","x-scope":"payments:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Checkout"}}}},"responses":{"200":{"description":"Authorization URL to redirect the payer to","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutResult"}}}}}}},"/public/orders/{id}/payment":{"get":{"summary":"Current payment balance for an order","x-scope":"payments:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"reference","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Payment status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentStatus"}}}}}}}}}