openapi: 3.0.3
info:
  title: SamCart Public Charges 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: Charges
  description: Individual charges, including failed charges.
paths:
  /charges:
    get:
      operationId: listCharges
      tags:
      - Charges
      summary: List charges
      description: Returns charges for the marketplace within the specified parameters, including failed charges when requested.
      parameters:
      - $ref: '#/components/parameters/StartDate'
      - $ref: '#/components/parameters/EndDate'
      - name: status
        in: query
        required: false
        description: Filter charges by status, for example to return failed charges.
        schema:
          type: string
          enum:
          - succeeded
          - failed
          - refunded
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: A list of charges.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Charge'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /charges/{charge_id}:
    parameters:
    - $ref: '#/components/parameters/ChargeId'
    get:
      operationId: getCharge
      tags:
      - Charges
      summary: Get a charge
      description: Retrieves an individual charge by ID.
      responses:
        '200':
          description: The requested charge.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Charge'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /charges/{charge_id}/refund:
    parameters:
    - $ref: '#/components/parameters/ChargeId'
    post:
      operationId: refundCharge
      tags:
      - Charges
      summary: Refund a charge
      description: Issues a full refund against an individual charge.
      x-endpoint-modeled: true
      responses:
        '200':
          description: The resulting refund.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
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
    EndDate:
      name: end_date
      in: query
      required: false
      description: End of the date range filter (ISO 8601).
      schema:
        type: string
        format: date
    StartDate:
      name: start_date
      in: query
      required: false
      description: Start of the date range filter (ISO 8601).
      schema:
        type: string
        format: date
    ChargeId:
      name: charge_id
      in: path
      required: true
      description: The ID of the charge.
      schema:
        type: string
  responses:
    ValidationError:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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:
    Refund:
      type: object
      properties:
        id:
          type: string
        charge_id:
          type: string
        amount:
          type: number
        currency:
          type: string
        created_at:
          type: string
          format: date-time
    Charge:
      type: object
      properties:
        id:
          type: string
        order_id:
          type: string
        subscription_id:
          type: string
        customer_id:
          type: string
        amount:
          type: number
        currency:
          type: string
        status:
          type: string
          enum:
          - succeeded
          - failed
          - refunded
        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).