openapi: 3.0.3
info:
  title: SamCart Public Charges Subscriptions 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: Subscriptions
  description: Recurring subscriptions and payment plans.
paths:
  /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'
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
    SubscriptionId:
      name: subscription_id
      in: path
      required: true
      description: The ID of the subscription.
      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:
    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
    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).