openapi: 3.0.3
info:
  title: CleanCloud Business and Reporting Customers API
  description: 'The CleanCloud API provides programmatic access to the CleanCloud point-of-sale and business-management platform for dry cleaners, laundromats, laundry services, and shoe repair businesses. It covers customers, orders and garments, products, price lists, inventory, pickup and delivery scheduling and routing, payments and subscriptions, invoices, promotions and loyalty, messaging, and reporting.


    All calls are HTTPS POST requests with a JSON body to https://cleancloudapp.com/api and return JSON. Authentication uses a per-account API token passed as the `api_token` field in the JSON request body (found in the CleanCloud admin under Settings > Admin > Pickup and Delivery > API). Because the token is a body field rather than an HTTP header or query parameter, it is modeled here as a required `api_token` property on each request schema rather than as an OpenAPI security scheme.


    API access requires a Grow or Grow+ subscription (Pro in Mexico) and is metered at 50,000 requests per month with a maximum of 3 requests per second; additional 25,000-request bundles are available. CleanCloud also emits outbound webhooks for order and customer events; those are documented in the provider apis.yml and review, not as request/response paths here.'
  version: '1.0'
  contact:
    name: CleanCloud
    url: https://cleancloudapp.com
  x-authentication:
    scheme: api_token
    location: request body (JSON field `api_token`)
    note: Every endpoint requires the api_token field. It is not sent as an Authorization header or query parameter.
servers:
- url: https://cleancloudapp.com/api
  description: CleanCloud production API
tags:
- name: Customers
  description: Customer accounts, authentication, and password reset.
paths:
  /addCustomer:
    post:
      operationId: addCustomer
      tags:
      - Customers
      summary: Create a customer
      description: Creates a new customer account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AuthBody'
              - $ref: '#/components/schemas/CustomerInput'
      responses:
        '200':
          description: The created customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /updateCustomer:
    post:
      operationId: updateCustomer
      tags:
      - Customers
      summary: Update a customer
      description: Updates fields on an existing customer identified by customerID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AuthBody'
              - type: object
                required:
                - customerID
                properties:
                  customerID:
                    type: string
              - $ref: '#/components/schemas/CustomerInput'
      responses:
        '200':
          description: The updated customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /deleteCustomer:
    post:
      operationId: deleteCustomer
      tags:
      - Customers
      summary: Delete a customer
      description: Deletes a customer account by customerID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AuthBody'
              - type: object
                required:
                - customerID
                properties:
                  customerID:
                    type: string
      responses:
        '200':
          description: Deletion result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getCustomer:
    post:
      operationId: getCustomer
      tags:
      - Customers
      summary: Get customer(s)
      description: Retrieves a single customer by customerID, or a set of customers by a created/updated date range.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AuthBody'
              - type: object
                properties:
                  customerID:
                    type: string
                    description: Retrieve a single customer by ID.
                  dateFrom:
                    type: string
                    description: Start of a created/updated date range (YYYY-MM-DD).
                  dateTo:
                    type: string
                    description: End of a created/updated date range (YYYY-MM-DD).
      responses:
        '200':
          description: One or more customers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Customers:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /loginCustomer:
    post:
      operationId: loginCustomer
      tags:
      - Customers
      summary: Authenticate a customer
      description: Authenticates a customer by email and password and returns the customer ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AuthBody'
              - type: object
                required:
                - customerEmail
                - customerPassword
                properties:
                  customerEmail:
                    type: string
                  customerPassword:
                    type: string
      responses:
        '200':
          description: Authentication result with customer ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /passwordCustomer:
    post:
      operationId: passwordCustomer
      tags:
      - Customers
      summary: Send password reset
      description: Triggers a password-reset email to the customer.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AuthBody'
              - type: object
                required:
                - customerEmail
                properties:
                  customerEmail:
                    type: string
      responses:
        '200':
          description: Reset email result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Customer:
      type: object
      properties:
        id:
          type: string
        customerName:
          type: string
        customerTel:
          type: string
        customerEmail:
          type: string
        customerAddress:
          type: string
        credit:
          type: number
        loyaltyPoints:
          type: integer
    Error:
      type: object
      properties:
        Error:
          type: string
        Success:
          type: string
    AuthBody:
      type: object
      required:
      - api_token
      properties:
        api_token:
          type: string
          description: Per-account API token from Settings > Admin > Pickup and Delivery > API. Required on every request.
    SuccessResponse:
      type: object
      properties:
        Success:
          type: string
          description: Typically "True" on success.
    CustomerInput:
      type: object
      properties:
        customerName:
          type: string
        customerTel:
          type: string
        customerEmail:
          type: string
        customerAddress:
          type: string
        customerPassword:
          type: string
    CustomerResponse:
      type: object
      properties:
        Success:
          type: string
        customerID:
          type: string
  responses:
    Unauthorized:
      description: Missing or invalid api_token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'