openapi: 3.0.3
info:
  title: SamCart Public Charges Customers API
  description: 'The SamCart Public API (v1) provides programmatic access to a SamCart marketplace''s commerce data - orders, products, customers, subscriptions, charges, and refunds - over REST at https://api.samcart.com/v1. Read endpoints return lists and individual records; write endpoints cancel or schedule cancellation of subscriptions, issue full refunds against charges, and update order custom fields. Authentication uses an API key passed in the `sc-api` header. API keys are provisioned by the SamCart Support team (contact support@samcart.com); the API is not fully self-serve.

    NOTE: This description is modeled by API Evangelist from SamCart''s public documentation, knowledge base, and third-party integration guides. Resource names, the base URL, the sc-api authentication header, and the presence of orders / products / customers / subscriptions / charges / refunds endpoints are grounded in those sources. Exact path segments, query parameters, and schema fields are honestly modeled to REST convention and should be verified against developer.samcart.com. Endpoints are marked with `x-endpoint-modeled` where the precise path or shape is inferred.'
  version: '1.0'
  contact:
    name: SamCart
    url: https://www.samcart.com/
  x-access-model: API keys are generated by the SamCart Support team on request (support@samcart.com); access has historically been gated to a beta program and higher plan tiers rather than being fully self-serve.
servers:
- url: https://api.samcart.com/v1
  description: SamCart Public API v1
security:
- scApiKey: []
tags:
- name: Customers
  description: Customers who have purchased in a marketplace.
paths:
  /customers:
    get:
      operationId: listCustomers
      tags:
      - Customers
      summary: List customers
      description: Returns the customers in the marketplace.
      parameters:
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: A list of customers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customers/{customer_id}:
    parameters:
    - $ref: '#/components/parameters/CustomerId'
    get:
      operationId: getCustomer
      tags:
      - Customers
      summary: Get a customer
      description: Retrieves an individual customer by ID.
      responses:
        '200':
          description: The requested customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum number of records to return per page.
      schema:
        type: integer
        default: 50
    Offset:
      name: offset
      in: query
      required: false
      description: Number of records to skip for pagination.
      schema:
        type: integer
        default: 0
    CustomerId:
      name: customer_id
      in: path
      required: true
      description: The ID of the customer.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid sc-api API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Customer:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        first_name:
          type: string
        last_name:
          type: string
        created_at:
          type: string
          format: date-time
    Pagination:
      type: object
      properties:
        limit:
          type: integer
        offset:
          type: integer
        total:
          type: integer
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
  securitySchemes:
    scApiKey:
      type: apiKey
      in: header
      name: sc-api
      description: API key passed in the `sc-api` header. Keys are generated by the SamCart Support team on request (support@samcart.com).