openapi: 3.0.3
info:
  title: SamCart Public Charges Products 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: Products
  description: Products sold through SamCart checkout pages.
paths:
  /products:
    get:
      operationId: listProducts
      tags:
      - Products
      summary: List products
      description: Returns the products in the marketplace.
      parameters:
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: A list of products.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /products/{product_id}:
    parameters:
    - $ref: '#/components/parameters/ProductId'
    get:
      operationId: getProduct
      tags:
      - Products
      summary: Get a product
      description: Retrieves an individual product by ID.
      responses:
        '200':
          description: The requested product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '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
    ProductId:
      name: product_id
      in: path
      required: true
      description: The ID of the product.
      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:
    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
    Product:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          enum:
          - one_time
          - subscription
          - payment_plan
        price:
          type: number
        currency:
          type: string
        created_at:
          type: string
          format: date-time
  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).