openapi: 3.0.3
info:
  title: SamCart Public 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.
  - name: Products
    description: Products sold through SamCart checkout pages.
  - name: Customers
    description: Customers who have purchased in a marketplace.
  - name: Subscriptions
    description: Recurring subscriptions and payment plans.
  - name: Charges
    description: Individual charges, including failed charges.
  - name: Refunds
    description: Refunds issued against charges.
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'
  /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'
  /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'
  /subscriptions:
    get:
      operationId: listSubscriptions
      tags:
        - Subscriptions
      summary: List subscriptions
      description: >-
        Returns all subscriptions within the specified parameters. This is the
        bulk subscriptions endpoint.
      parameters:
        - $ref: '#/components/parameters/StartDate'
        - $ref: '#/components/parameters/EndDate'
        - name: status
          in: query
          required: false
          description: Filter subscriptions by status.
          schema:
            type: string
            enum:
              - active
              - cancelled
              - past_due
              - completed
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: A list of subscriptions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Subscription'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /subscriptions/{subscription_id}:
    parameters:
      - $ref: '#/components/parameters/SubscriptionId'
    get:
      operationId: getSubscription
      tags:
        - Subscriptions
      summary: Get a subscription
      description: Retrieves an individual subscription by ID.
      responses:
        '200':
          description: The requested subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /subscriptions/{subscription_id}/cancel:
    parameters:
      - $ref: '#/components/parameters/SubscriptionId'
    post:
      operationId: cancelSubscription
      tags:
        - Subscriptions
      summary: Cancel a subscription
      description: Cancels a subscription immediately.
      x-endpoint-modeled: true
      responses:
        '200':
          description: The cancelled subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /subscriptions/{subscription_id}/schedule-cancellation:
    parameters:
      - $ref: '#/components/parameters/SubscriptionId'
    post:
      operationId: scheduleSubscriptionCancellation
      tags:
        - Subscriptions
      summary: Schedule a subscription cancellation
      description: >-
        Schedules a subscription to cancel at a future date, typically the end
        of the current billing period.
      x-endpoint-modeled: true
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                cancel_at:
                  type: string
                  format: date-time
                  description: When the cancellation should take effect.
      responses:
        '200':
          description: The subscription with a scheduled cancellation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /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'
  /refunds:
    get:
      operationId: listRefunds
      tags:
        - Refunds
      summary: List refunds
      description: Retrieves all refunds for the marketplace within the specified parameters.
      parameters:
        - $ref: '#/components/parameters/StartDate'
        - $ref: '#/components/parameters/EndDate'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: A list of refunds.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Refund'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /refunds/{refund_id}:
    parameters:
      - $ref: '#/components/parameters/RefundId'
    get:
      operationId: getRefund
      tags:
        - Refunds
      summary: Get a refund
      description: Retrieves an individual refund by ID.
      responses:
        '200':
          description: The requested refund.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  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).
  parameters:
    StartDate:
      name: start_date
      in: query
      required: false
      description: Start of the date range filter (ISO 8601).
      schema:
        type: string
        format: date
    EndDate:
      name: end_date
      in: query
      required: false
      description: End of the date range filter (ISO 8601).
      schema:
        type: string
        format: date
    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
    OrderId:
      name: order_id
      in: path
      required: true
      description: The ID of the order.
      schema:
        type: string
    ProductId:
      name: product_id
      in: path
      required: true
      description: The ID of the product.
      schema:
        type: string
    CustomerId:
      name: customer_id
      in: path
      required: true
      description: The ID of the customer.
      schema:
        type: string
    SubscriptionId:
      name: subscription_id
      in: path
      required: true
      description: The ID of the subscription.
      schema:
        type: string
    ChargeId:
      name: charge_id
      in: path
      required: true
      description: The ID of the charge.
      schema:
        type: string
    RefundId:
      name: refund_id
      in: path
      required: true
      description: The ID of the refund.
      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'
    ValidationError:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
    Pagination:
      type: object
      properties:
        limit:
          type: integer
        offset:
          type: integer
        total:
          type: integer
    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
    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
    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
    Subscription:
      type: object
      properties:
        id:
          type: string
        customer_id:
          type: string
        product_id:
          type: string
        status:
          type: string
          enum:
            - active
            - cancelled
            - past_due
            - completed
        amount:
          type: number
        currency:
          type: string
        billing_interval:
          type: string
        next_billing_date:
          type: string
          format: date-time
        cancel_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
    Refund:
      type: object
      properties:
        id:
          type: string
        charge_id:
          type: string
        amount:
          type: number
        currency:
          type: string
        created_at:
          type: string
          format: date-time