openapi: 3.1.0
info:
  title: SAP Commerce Cloud Admin Addresses Customers API
  description: Administrative API for SAP Commerce Cloud providing system configuration, maintenance, monitoring, and health check capabilities. Enables programmatic access to system administration functions including cache management, CronJob execution, and system health monitoring.
  version: '1.0'
  contact:
    name: SAP Support
    url: https://support.sap.com/
  termsOfService: https://www.sap.com/about/legal/terms-of-use.html
servers:
- url: https://{tenant}.{region}.commercecloud.sap
  description: SAP Commerce Cloud Production
  variables:
    tenant:
      description: Tenant identifier
      default: my-tenant
    region:
      description: Deployment region
      default: us
security:
- oauth2: []
tags:
- name: Customers
  description: Customer lookup and 360 view
paths:
  /customers/search:
    get:
      operationId: searchCustomers
      summary: SAP Commerce Cloud Search customers
      description: Search for customers by name, email, or customer ID. Used by customer service agents to find customer accounts.
      tags:
      - Customers
      parameters:
      - name: query
        in: query
        required: true
        description: Search query (name, email, or customer ID)
        schema:
          type: string
      - name: baseSite
        in: query
        required: true
        description: Base site identifier
        schema:
          type: string
      - $ref: '#/components/parameters/currentPage'
      - $ref: '#/components/parameters/pageSize'
      responses:
        '200':
          description: Customer search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerSearchPage'
        '401':
          description: Unauthorized
        '403':
          description: Agent does not have required permissions
  /customers/{customerId}:
    get:
      operationId: getCustomer360
      summary: SAP Commerce Cloud Get customer 360 view
      description: Retrieve a comprehensive 360-degree view of a customer including profile information, recent orders, active carts, and support tickets.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/customerId'
      - name: baseSite
        in: query
        required: true
        description: Base site identifier
        schema:
          type: string
      responses:
        '200':
          description: Customer 360 data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer360Data'
        '404':
          description: Customer not found
  /InboundCustomer/Customers:
    get:
      operationId: listCustomers
      summary: SAP Commerce Cloud List customers
      description: Retrieve customer data through the inbound customer integration object.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/skip'
      responses:
        '200':
          description: Customer list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ODataCustomerCollection'
    post:
      operationId: createCustomer
      summary: SAP Commerce Cloud Create or update a customer
      description: Create or update customer data through the inbound integration layer.
      tags:
      - Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationCustomer'
      responses:
        '201':
          description: Customer created
        '400':
          description: Invalid customer data
components:
  parameters:
    customerId:
      name: customerId
      in: path
      required: true
      description: Customer unique identifier
      schema:
        type: string
    skip:
      name: $skip
      in: query
      description: Number of results to skip
      schema:
        type: integer
    pageSize:
      name: pageSize
      in: query
      description: Number of results per page
      schema:
        type: integer
        default: 20
    select:
      name: $select
      in: query
      description: Comma-separated list of properties to return
      schema:
        type: string
    currentPage:
      name: currentPage
      in: query
      description: Current page number (zero-based)
      schema:
        type: integer
        default: 0
    filter:
      name: $filter
      in: query
      description: OData filter expression
      schema:
        type: string
    top:
      name: $top
      in: query
      description: Maximum number of results to return
      schema:
        type: integer
  schemas:
    CartSummary:
      type: object
      properties:
        code:
          type: string
          description: Cart code
        totalItems:
          type: integer
          description: Number of items
        total:
          type: string
          description: Formatted cart total
        modified:
          type: string
          format: date-time
          description: Last modification time
    CustomerSearchPage:
      type: object
      properties:
        entries:
          type: array
          items:
            $ref: '#/components/schemas/CustomerSearchEntry'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Customer360Data:
      type: object
      properties:
        overview:
          type: object
          properties:
            name:
              type: string
              description: Customer name
            email:
              type: string
              description: Customer email
            signedUpDate:
              type: string
              format: date-time
              description: Registration date
            address:
              type: object
              properties:
                town:
                  type: string
                country:
                  type: string
        latestActivity:
          type: object
          properties:
            type:
              type: string
              description: Activity type
            description:
              type: string
              description: Activity description
            date:
              type: string
              format: date-time
        recentOrders:
          type: array
          items:
            $ref: '#/components/schemas/OrderSummary'
        activeCarts:
          type: array
          items:
            $ref: '#/components/schemas/CartSummary'
        supportTickets:
          type: array
          items:
            $ref: '#/components/schemas/TicketSummary'
    CustomerSearchEntry:
      type: object
      properties:
        uid:
          type: string
          description: Customer email or UID
        name:
          type: string
          description: Customer full name
        customerId:
          type: string
          description: Customer ID
        lastCartId:
          type: string
          description: ID of the customer's most recent cart
        hasOrder:
          type: boolean
          description: Whether the customer has placed orders
    Pagination:
      type: object
      properties:
        currentPage:
          type: integer
          description: Current page number
        pageSize:
          type: integer
          description: Number of results per page
        totalPages:
          type: integer
          description: Total number of pages
        totalResults:
          type: integer
          description: Total number of results
    ODataCustomerCollection:
      type: object
      properties:
        d:
          type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/IntegrationCustomer'
    TicketSummary:
      type: object
      properties:
        id:
          type: string
          description: Ticket identifier
        subject:
          type: string
          description: Ticket subject
        status:
          type: string
          description: Ticket status
        created:
          type: string
          format: date-time
          description: Ticket creation date
    IntegrationCustomer:
      type: object
      properties:
        uid:
          type: string
          description: Customer unique identifier
        name:
          type: string
          description: Customer full name
        customerID:
          type: string
          description: Customer ID
        addresses:
          type: array
          items:
            type: object
            properties:
              streetname:
                type: string
              streetnumber:
                type: string
              postalcode:
                type: string
              town:
                type: string
              country:
                type: string
          description: Customer addresses
        integrationKey:
          type: string
          description: Unique integration key
    OrderSummary:
      type: object
      properties:
        code:
          type: string
          description: Order code
        status:
          type: string
          description: Order status
        total:
          type: string
          description: Formatted order total
        placed:
          type: string
          format: date-time
          description: Order placement date
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication for SAP Commerce Cloud Admin API
      flows:
        clientCredentials:
          tokenUrl: https://{tenant}.{region}.commercecloud.sap/authorizationserver/oauth/token
          scopes:
            admin: Administrative access
externalDocs:
  description: SAP Commerce Cloud Administration Documentation
  url: https://help.sap.com/docs/SAP_COMMERCE_CLOUD_PUBLIC_CLOUD/