openapi: 3.1.0
info:
  title: Acuity Brands Catalog Orders API
  description: B2B REST APIs for Acuity Brands distributors covering inventory availability, order status tracking, product catalog, and web content. Enables integration of Acuity Brands data into distributor ERP, e-commerce, and ordering systems.
  version: 1.0.0
  contact:
    name: Acuity Brands Developer Portal
    url: https://api-docs.acuitybrands.com/
servers:
- url: https://api.acuitybrands.com/v1
  description: Acuity Brands production API
security:
- BasicAuth: []
tags:
- name: Orders
  description: Order status and shipment tracking
paths:
  /orders:
    get:
      operationId: listOrders
      summary: Acuity Brands List Orders
      description: Retrieve a list of orders with their current status, estimated ship dates, and tracking information.
      tags:
      - Orders
      parameters:
      - name: status
        in: query
        description: Filter by order status (pending, processing, shipped, delivered)
        schema:
          type: string
          enum:
          - pending
          - processing
          - shipped
          - delivered
      - name: fromDate
        in: query
        description: Filter orders placed on or after this date (ISO 8601)
        schema:
          type: string
          format: date
      - name: toDate
        in: query
        description: Filter orders placed on or before this date (ISO 8601)
        schema:
          type: string
          format: date
      - name: limit
        in: query
        description: Maximum number of results
        schema:
          type: integer
          default: 50
      - name: cursor
        in: query
        description: Pagination cursor
        schema:
          type: string
      responses:
        '200':
          description: Order list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderList'
        '401':
          description: Unauthorized
  /orders/{orderId}:
    get:
      operationId: getOrder
      summary: Acuity Brands Get Order
      description: Retrieve full order status details including line items, estimated ship dates, actual shipment dates, carrier, and pro number.
      tags:
      - Orders
      parameters:
      - name: orderId
        in: path
        required: true
        description: Acuity Brands order identifier
        schema:
          type: string
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          description: Unauthorized
        '404':
          description: Order not found
  /orders/{orderId}/shipments:
    get:
      operationId: getOrderShipments
      summary: Acuity Brands Get Order Shipments
      description: Retrieve all shipment records for an order including carrier, pro number, and tracking URLs.
      tags:
      - Orders
      parameters:
      - name: orderId
        in: path
        required: true
        description: Acuity Brands order identifier
        schema:
          type: string
      responses:
        '200':
          description: Shipment list for order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentList'
        '401':
          description: Unauthorized
        '404':
          description: Order not found
components:
  schemas:
    OrderList:
      type: object
      description: Paginated list of orders
      properties:
        orders:
          type: array
          items:
            $ref: '#/components/schemas/Order'
        total:
          type: integer
          example: 200
        cursor:
          type: string
    Order:
      type: object
      description: An Acuity Brands order with status and shipment information
      properties:
        orderId:
          type: string
          description: Acuity Brands order number
          example: ACB-2026-001234
        purchaseOrderNumber:
          type: string
          description: Distributor purchase order number
          example: PO-55678
        status:
          type: string
          enum:
          - pending
          - processing
          - shipped
          - delivered
          - cancelled
          example: shipped
        orderDate:
          type: string
          format: date
          description: Date order was placed
          example: '2026-04-15'
        estimatedShipDate:
          type: string
          format: date
          description: Estimated ship date
          example: '2026-04-20'
        actualShipDate:
          type: string
          format: date
          description: Actual ship date
          example: '2026-04-19'
        lineItems:
          type: array
          description: Order line items
          items:
            type: object
            properties:
              lineNumber:
                type: integer
                example: 1
              productNumber:
                type: string
                example: LBL4 48L ADP
              description:
                type: string
                example: 4FT LED Wrap Light
              quantity:
                type: integer
                example: 10
              unitPrice:
                type: number
                example: 45.5
              status:
                type: string
                example: shipped
        totalAmount:
          type: number
          description: Total order amount
          example: 455.0
        shipToAddress:
          type: object
          properties:
            name:
              type: string
              example: ABC Electrical Distributors
            street:
              type: string
              example: 123 Main St
            city:
              type: string
              example: Atlanta
            state:
              type: string
              example: GA
            zip:
              type: string
              example: '30301'
    Shipment:
      type: object
      description: Shipment record for an order
      properties:
        shipmentId:
          type: string
          description: Shipment identifier
          example: SHP-001
        orderId:
          type: string
          description: Associated order ID
          example: ACB-2026-001234
        carrier:
          type: string
          description: Shipping carrier name
          example: UPS Freight
        proNumber:
          type: string
          description: Carrier PRO/tracking number
          example: 1Z999AA10123456784
        trackingUrl:
          type: string
          description: Carrier tracking URL
          example: https://www.ups.com/track?tracknum=1Z999AA10123456784
        shipDate:
          type: string
          format: date
          example: '2026-04-19'
        estimatedDeliveryDate:
          type: string
          format: date
          example: '2026-04-22'
        weight:
          type: number
          description: Shipment weight in lbs
          example: 45.5
        lineItems:
          type: array
          description: Line items in this shipment
          items:
            type: object
            properties:
              lineNumber:
                type: integer
                example: 1
              productNumber:
                type: string
                example: LBL4 48L ADP
              quantityShipped:
                type: integer
                example: 10
    ShipmentList:
      type: object
      description: List of shipments for an order
      properties:
        shipments:
          type: array
          items:
            $ref: '#/components/schemas/Shipment'
        total:
          type: integer
          example: 2
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Auth using numeric User ID as username and API Key as password