openapi: 3.0.3
info:
  title: SamCart Public Charges Orders 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: Orders
  description: Orders placed in a SamCart marketplace.
paths:
  /orders:
    get:
      operationId: listOrders
      tags:
      - Orders
      summary: List orders
      description: Returns all orders within the specified parameters. Supports filtering by date range and by funnel / upsell source, plus pagination.
      parameters:
      - $ref: '#/components/parameters/StartDate'
      - $ref: '#/components/parameters/EndDate'
      - name: funnel_id
        in: query
        required: false
        description: Filter orders to a specific funnel / upsell source.
        schema:
          type: string
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: A list of orders.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /orders/{order_id}:
    parameters:
    - $ref: '#/components/parameters/OrderId'
    get:
      operationId: getOrder
      tags:
      - Orders
      summary: Get an order
      description: Retrieves an individual order by ID.
      responses:
        '200':
          description: The requested order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateOrderCustomFields
      tags:
      - Orders
      summary: Update order custom fields
      description: Updates order-level and upsell custom fields on an existing order.
      x-endpoint-modeled: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                custom_fields:
                  type: object
                  additionalProperties: true
                upsell_custom_fields:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: The updated order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '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
    OrderId:
      name: order_id
      in: path
      required: true
      description: The ID of the order.
      schema:
        type: string
    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
  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:
    Order:
      type: object
      properties:
        id:
          type: string
        created_at:
          type: string
          format: date-time
        customer_id:
          type: string
        products:
          type: array
          items:
            type: object
            additionalProperties: true
        total:
          type: number
        currency:
          type: string
        funnel_id:
          type: string
        custom_fields:
          type: object
          additionalProperties: true
        upsell_custom_fields:
          type: object
          additionalProperties: true
    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).