openapi: 3.0.3
info:
  title: CleanCloud Business and Reporting Pickup and Delivery 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: Pickup and Delivery
  description: Recurring pickups, routing, scheduling, and driver location.
paths:
  /repeatPickup:
    post:
      operationId: repeatPickup
      tags:
      - Pickup and Delivery
      summary: Create a recurring pickup
      description: Creates a scheduled recurring pickup for a customer.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AuthBody'
              - type: object
                required:
                - customerID
                properties:
                  customerID:
                    type: string
                  frequency:
                    type: string
                  dayOfWeek:
                    type: string
      responses:
        '200':
          description: The created recurring pickup.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /updateRepeatPickup:
    post:
      operationId: updateRepeatPickup
      tags:
      - Pickup and Delivery
      summary: Update a recurring pickup
      description: Modifies an existing recurring pickup schedule.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AuthBody'
              - type: object
                required:
                - pickupID
                properties:
                  pickupID:
                    type: string
                  frequency:
                    type: string
                  dayOfWeek:
                    type: string
      responses:
        '200':
          description: The updated recurring pickup.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /deletePickup:
    post:
      operationId: deletePickup
      tags:
      - Pickup and Delivery
      summary: Cancel a recurring pickup
      description: Cancels a recurring pickup.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AuthBody'
              - type: object
                required:
                - pickupID
                properties:
                  pickupID:
                    type: string
      responses:
        '200':
          description: Cancellation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getPickups:
    post:
      operationId: getPickups
      tags:
      - Pickup and Delivery
      summary: List recurring pickups
      description: Retrieves a customer's recurring pickups.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AuthBody'
              - type: object
                required:
                - customerID
                properties:
                  customerID:
                    type: string
      responses:
        '200':
          description: A list of recurring pickups.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Pickups:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getDates:
    post:
      operationId: getDates
      tags:
      - Pickup and Delivery
      summary: Get available dates
      description: Returns available pickup/delivery dates with remaining slot counts.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AuthBody'
              - type: object
                properties:
                  routeID:
                    type: string
      responses:
        '200':
          description: Available dates.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Dates:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getSlots:
    post:
      operationId: getSlots
      tags:
      - Pickup and Delivery
      summary: Get time slots
      description: Returns available time slots for a route on a given day.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AuthBody'
              - type: object
                properties:
                  routeID:
                    type: string
                  date:
                    type: string
      responses:
        '200':
          description: Available time slots.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Slots:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /getRoute:
    post:
      operationId: getRoute
      tags:
      - Pickup and Delivery
      summary: Resolve a route
      description: Determines the delivery route from coordinates or an address.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AuthBody'
              - type: object
                properties:
                  address:
                    type: string
                  lat:
                    type: number
                  lng:
                    type: number
      responses:
        '200':
          description: The resolved route.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /driverLocation:
    post:
      operationId: driverLocation
      tags:
      - Pickup and Delivery
      summary: Get driver location
      description: Returns the current driver location for an order.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AuthBody'
              - type: object
                required:
                - orderID
                properties:
                  orderID:
                    type: string
      responses:
        '200':
          description: The current driver location.
          content:
            application/json:
              schema:
                type: object
                properties:
                  lat:
                    type: number
                  lng:
                    type: number
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    SuccessResponse:
      type: object
      properties:
        Success:
          type: string
          description: Typically "True" on success.
    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.
  responses:
    Unauthorized:
      description: Missing or invalid api_token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'