openapi: 3.0.0
info:
  title: 'SamCart Public API'
  description: "\n# Introduction\nWelcome to SamCart's Public API. This API is used for accessing the data inside your SamCart marketplace.\n## Private Beta\nThis API is currently in private beta. If you would like to be considered for our beta program, please contact support@samcart.com.\n## OpenAPI Specification\nThis API is documented in OpenAPI format and follows the practices of that specification.\n# Authentication\nThis API offers one form of authentication:\n<ul>\n<li>API Key</lil>\n</ul>\n\nYou can generate your own API key from the SamCart dashboard under <span class='code'>Settings > API Keys</span>. Creating a key requires a plan that includes API access.\n\n## Using the API Key\nTo be successfully authenticated, you must pass the header parameter <span class='code'>sc-api</span> with your provided API key. If your key is invalid or not supplied in the call, the API will return code <span class='code'>401 Unauthorized</a> with an additional message explaining the specifics of why that code was returned.\n## Security Scheme\nAll of our responses are secure via HTTPS.\n\nThis API will accept HTTPS or HTTP requests, but HTTP requests will result in a `301 Moved Permanently` response header to redirect the request to HTTPS. If you send an HTTP request, and your client supports automatic redirects, you will receive your payload back via HTTPS. If your client does not support automatic redirects, you will receive the response `301 Moved Permanently` and you will have to manually update your request to use HTTPS.\n\n# Headers\nAlong with the <span class='code'>sc-api</span> header, an <span class='code'>Accept</span> header needs to be set.\nThis should be set to <span class='code'>application/json</span> when using the API.\n\n# Rate Limiting\nRequests are rate-limited per marketplace. The limit is shared across every API key that belongs to a marketplace, so adding keys does not raise it. The window is a fixed 60 seconds that starts with your first request; when it expires your full allowance resets at once, so pace requests rather than bursting across a boundary. These limits apply to both API key and OAuth authentication. OAuth requests are additionally subject to a per-user cap of 100 requests per minute, so the effective limit for an OAuth integration is whichever is lower.\n\nLimits depend on your plan:\n\n| Plan | Limit |\n| ---- | ----- |\n| Core, Scaler | 120 requests per minute |\n| Pro, Scale, Enterprise | 240 requests per minute |\n| Older plans that include API access | 120 requests per minute |\n\n## Rate Limit Headers\nResponses to authenticated requests carry your current allowance, not just rejected ones, so you can pace your integration without waiting for a <span class='code'>429</span>:\n\n```\nRateLimit-Limit: 240\nRateLimit-Remaining: 187\nRateLimit-Reset: 22\n```\n\n<span class='code'>RateLimit-Limit</span> is the per-minute allowance for your plan, <span class='code'>RateLimit-Remaining</span> is what is left in the current window, and <span class='code'>RateLimit-Reset</span> is the number of seconds until the window resets.\n\n## Exceeding the Limit\nOnce the allowance is used up, further requests are rejected with <span class='code'>429 Too Many Requests</span>:\n\n```\nHTTP/1.1 429 Too Many Requests\nRateLimit-Limit: 240\nRateLimit-Remaining: 0\nRateLimit-Reset: 31\nRetry-After: 31\n\n{\"message\": \"Too many requests. Please try again later.\"}\n```\n\n<span class='code'>Retry-After</span> matches <span class='code'>RateLimit-Reset</span>. Wait that many seconds before retrying. Rejected requests do not count against your allowance, so a retry loop that honors <span class='code'>Retry-After</span> never pushes the reset further out.\n\nAPI access depends on your plan. If your plan does not include API access, endpoints return <span class='code'>403 Forbidden</span> with a <span class='code'>{\"message\": \"...\"}</span> body explaining that access is not available on your current plan. The same status is returned when the SamCart account itself is not active.\n# Pagination\nThe following bulk endpoints include pagination:\n<ul class='list'>\n<li><a href='https://developer.samcart.com/#operation/getCharges'>Charges</a></li>\n<li><a href='https://developer.samcart.com/#operation/getCustomers'>Customers</a></li>\n<li><a href='https://developer.samcart.com/#operation/getProducts'>Products</a></li>\n<li><a href='https://developer.samcart.com/#operation/getAllRefunds'>Refunds</a></li>\n</ul>\n\nWhen making a request to a paginated endpoint, the response will return a maximum of 100 results but can be adjusted using the <span class='code'>limit</span> query parameter. Included in the body of the response are links to subsequent pages of results. Using these links you are able to use to iterate through the various pages of results.\n# Response Codes\nThe following is a list of the response code that may be sent after an API request is made. Some response codes will provide additional messaging about why that response code was returned:\n<ul class='list'>\n<li class='code'>200 Success</li>\n<li class='code'>301 Moved Permanently</li>\n<li class='code'>404 Object could not be found</li>\n<li class='code'>401 Unauthorized</li>\n<li class='code'>403 Forbidden</li>\n<li class='code'>409 Conflict</li>\n<li class='code'>429 Too Many Requests</li>\n<li class='code'>504 Timeout</li>\n</ul>\n\n# Versioning and compatibility\nWe will try to maintain backward and future compatibility as much as we can. However, in case we need to introduce a backward-incompatible change, we will release a new version of the API. Currently, the API is on <span class='code'>Version 1</span>.\n## Changelog\n### 2022-06-06\nAdded upsell_custom_fields to Order object.\n### 2022-05-17\nAdded two new GET endpoints to retrieve all refunds for a marketplace, or to retreive an individual refund.\n### 2022-05-17\nAdded a new POST endpoint to fully refund an individual charge.\n### 2022-04-07\nAdded a new POST endpoint to schedule cancelation of individual subscription.\n### 2022-04-07\nAdded a new POST endpoint to cancel an individual subscription.\n### 2021-07-15\nFixed pagination URL protocol to match original request.\n### 2021-07-13\nAdded bulk endpoint for our Subscriptions object. Calls made to this endpoint will return all Subscriptions within the specified parameters.\n### 2021-06-22\nAdded bulk endpoint for our Orders object. Calls made to this endpoint will return all Orders within the specified parameters.\n### 2021-06-09\nIntroduced the <span class='code'>SKU</span> property to the Orders, Subscriptions, and Products endpoint.\nAdded indexes to improve performance.\n### 2021-06-02\nInitial API specification published and began private beta.\n# Feedback\nWe'd love your feedback! We're committed to growing our API product and want to ensure it meets your needs. Click on the link below to give us feedback on our API. While you're there, check out the other great initiatives on our roadmap.\n<a href='https://feedback.samcart.com/c/85-public-api'>SamCart Public API Feedback</a>\n"
  termsOfService: 'https://www.samcart.com/terms-and-conditions'
  contact:
    name: 'API Support'
    email: support@samcart.com
  license:
    name: 'Apache 2.0'
    url: 'https://www.apache.org/licenses/LICENSE-2.0.html'
  version: 1.0.0
  x-logo:
    url: 'https://developer.samcart.com/samcart-logo-primary.svg'
    altText: 'SamCart logo'
servers:
  -
    url: 'https://api.samcart.com/v1'
    description: 'Public API server'
paths:
  '/orders/{id}/add-to-order':
    post:
      tags:
        - Orders
      description: 'Charge a product to an existing order using the payment method already on the order. The charge is processed synchronously.'
      operationId: addToOrder
      parameters:
        -
          $ref: '#/components/parameters/order_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - product_id
              properties:
                product_id:
                  description: 'The ID of the product to add to the order. The product must belong to the same marketplace as the order.'
                  type: integer
                  example: 12345
              type: object
      responses:
        '200':
          description: 'Product was charged to the order'
        '404':
          description: 'Order or product could not be found'
        '409':
          description: 'The product could not be charged to the order'
        '422':
          description: 'Validation error'
        '500':
          description: 'An unexpected error occurred while charging the product to the order'
      security:
        -
          apiKeyAuth: []
  /orders/batch-add-to-order:
    post:
      tags:
        - Orders
      description: 'Charge products to existing orders in bulk. Every product provided will be charged to every order provided, using the payment method already on each order. Charges are processed asynchronously and large batches may take several minutes to complete. A 202 response returns a batch_id that can be polled with the batch status endpoint to see the outcome of each charge.'
      operationId: batchAddToOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - order_ids
                - product_ids
              properties:
                order_ids:
                  description: 'The IDs of the orders to charge. Maximum of 5000 orders per request.'
                  type: array
                  items: { type: integer }
                  maxItems: 5000
                  minItems: 1
                  uniqueItems: true
                  example: [12345, 12346]
                product_ids:
                  description: 'The IDs of the products to add to each order. Maximum of 25 products per request.'
                  type: array
                  items: { type: integer }
                  maxItems: 25
                  minItems: 1
                  uniqueItems: true
                  example: [678, 679]
              type: object
      responses:
        '202':
          description: 'Request accepted. Charges will be processed asynchronously. Poll the returned batch_id for results.'
        '404':
          description: 'One or more orders or products could not be found'
        '422':
          description: 'Validation error'
      security:
        -
          apiKeyAuth: []
  '/orders/batch-add-to-order/{batchId}':
    get:
      tags:
        - Orders
      description: 'Retrieve the progress and per-charge results of a batch add-to-order request. The batch is complete once processed equals total.'
      operationId: batchAddToOrderStatus
      parameters:
        -
          name: batchId
          in: path
          description: 'The batch_id returned by the batch-add-to-order endpoint.'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'The current status of the batch'
        '404':
          description: 'Batch could not be found'
      security:
        -
          apiKeyAuth: []
  /charges:
    get:
      tags:
        - Charges
      description: 'Retrieve all charges'
      operationId: getCharges
      parameters:
        -
          $ref: '#/components/parameters/created_at_min'
        -
          $ref: '#/components/parameters/created_at_max'
        -
          $ref: '#/components/parameters/test_mode'
        -
          $ref: '#/components/parameters/pagination_offset'
        -
          $ref: '#/components/parameters/pagination_limit'
        -
          $ref: '#/components/parameters/pagination_direction'
      responses:
        '200':
          description: 'Successful operation. Response will return an array of 0 or more charges'
          content:
            application/json:
              schema:
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/ChargeService' } }
                  pagination: { $ref: '#/components/schemas/Pagination' }
                type: object
      security:
        -
          apiKeyAuth: []
  '/charges/{id}':
    get:
      tags:
        - Charges
      description: 'Retrieve a charge'
      operationId: getByChargeId
      parameters:
        -
          $ref: '#/components/parameters/charge_id'
        -
          $ref: '#/components/parameters/created_at_min'
        -
          $ref: '#/components/parameters/created_at_max'
        -
          $ref: '#/components/parameters/test_mode'
      responses:
        '200':
          description: 'Successful operation'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeService'
        '404':
          description: 'Charge could not found'
      security:
        -
          apiKeyAuth: []
  '/charges/{id}/refunds':
    get:
      tags:
        - Charges
      description: 'Retrieve all refunds on a charge'
      operationId: getMultipleRefundsByChargeId
      parameters:
        -
          $ref: '#/components/parameters/charge_id'
      responses:
        '200':
          description: 'Successful operation. Response will return an array of 0 or more refunds'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RefundService'
        '404':
          description: 'Charge could not be found'
      security:
        -
          apiKeyAuth: []
  '/charges/{id}/refunds/{refund_id}':
    get:
      tags:
        - Charges
      description: 'Retrieve a refund on a charge'
      operationId: getRefundByChargeId
      parameters:
        -
          $ref: '#/components/parameters/charge_id'
        -
          $ref: '#/components/parameters/refund_id'
      responses:
        '200':
          description: 'Successful operation'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundService'
        '404':
          description: 'Charge or refund could not be found'
      security:
        -
          apiKeyAuth: []
  /customers:
    get:
      tags:
        - Customers
      description: 'Retrieve all customers'
      operationId: getCustomers
      parameters:
        -
          $ref: '#/components/parameters/customer_email'
        -
          $ref: '#/components/parameters/created_at_min'
        -
          $ref: '#/components/parameters/created_at_max'
        -
          $ref: '#/components/parameters/pagination_offset'
        -
          $ref: '#/components/parameters/pagination_limit'
        -
          $ref: '#/components/parameters/pagination_direction'
      responses:
        '200':
          description: 'Successful operation. Response will return an array of 0 or more customers'
          content:
            application/json:
              schema:
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/CustomerService' } }
                  pagination: { $ref: '#/components/schemas/Pagination' }
                type: object
      security:
        -
          apiKeyAuth: []
  '/customers/{id}':
    get:
      tags:
        - Customers
      description: 'Retrieve a customer'
      operationId: getByCustomerId
      parameters:
        -
          $ref: '#/components/parameters/customer_id'
        -
          $ref: '#/components/parameters/created_at_min'
        -
          $ref: '#/components/parameters/created_at_max'
      responses:
        '200':
          description: 'Successful operation'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerService'
        '404':
          description: 'Customer could not be found'
      security:
        -
          apiKeyAuth: []
  '/customers/{id}/addresses':
    get:
      tags:
        - Customers
      description: 'Retrieve all addresses for a customer'
      operationId: getAddressesByCustomerId
      parameters:
        -
          $ref: '#/components/parameters/customer_id'
      responses:
        '200':
          description: 'Successful operation. Response will return an array of 0 or more addresses'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AddressService'
        '404':
          description: 'Customer could not be found'
      security:
        -
          apiKeyAuth: []
  '/customers/{id}/charges':
    get:
      tags:
        - Customers
      description: 'Retrieve all charges for a customer'
      operationId: getChargesByCustomerId
      parameters:
        -
          $ref: '#/components/parameters/customer_id'
        -
          $ref: '#/components/parameters/created_at_min'
        -
          $ref: '#/components/parameters/created_at_max'
        -
          $ref: '#/components/parameters/test_mode'
      responses:
        '200':
          description: 'Successful operation. Response will return an array of 0 or more charges'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChargeService'
        '404':
          description: 'Customer could not be found'
      security:
        -
          apiKeyAuth: []
  '/customers/{id}/orders':
    get:
      tags:
        - Customers
      description: 'Retrieve all orders for a customer'
      operationId: getOrdersByCustomerId
      parameters:
        -
          $ref: '#/components/parameters/customer_id'
        -
          $ref: '#/components/parameters/created_at_min'
        -
          $ref: '#/components/parameters/created_at_max'
        -
          $ref: '#/components/parameters/test_mode'
      responses:
        '200':
          description: 'Successful operation. Response will return an array of 0 or more orders'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderService'
        '404':
          description: 'Customer could not be found'
      security:
        -
          apiKeyAuth: []
  '/customers/{id}/subscriptions':
    get:
      tags:
        - Customers
      description: 'Retrieve all subscriptions for a customer'
      operationId: getSubscriptionsByCustomerId
      parameters:
        -
          $ref: '#/components/parameters/customer_id'
        -
          $ref: '#/components/parameters/created_at_min'
        -
          $ref: '#/components/parameters/created_at_max'
        -
          $ref: '#/components/parameters/rebilling_at_min'
        -
          $ref: '#/components/parameters/rebilling_at_max'
        -
          $ref: '#/components/parameters/canceled_at_min'
        -
          $ref: '#/components/parameters/canceled_at_max'
        -
          $ref: '#/components/parameters/subscription_status'
        -
          $ref: '#/components/parameters/subscription_type'
        -
          $ref: '#/components/parameters/test_mode'
      responses:
        '200':
          description: 'Successful operation. Response will return an array of 0 or more subscriptions'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SubscriptionService'
        '404':
          description: 'Customer could not found'
      security:
        -
          apiKeyAuth: []
  /failed-charges:
    get:
      tags:
        - 'Failed Charges'
      description: 'Retrieve all failed charges'
      operationId: getFailedCharges
      parameters:
        -
          $ref: '#/components/parameters/created_at_min'
        -
          $ref: '#/components/parameters/created_at_max'
        -
          $ref: '#/components/parameters/test_mode'
        -
          $ref: '#/components/parameters/pagination_offset'
        -
          $ref: '#/components/parameters/pagination_limit'
        -
          $ref: '#/components/parameters/pagination_direction'
      responses:
        '200':
          description: 'Successful operation. Response will return an array of 0 or more failed charges'
          content:
            application/json:
              schema:
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/FailedChargeService' } }
                  pagination: { $ref: '#/components/schemas/Pagination' }
                type: object
      security:
        -
          apiKeyAuth: []
  '/failed-charges/{id}':
    get:
      tags:
        - 'Failed Charges'
      description: 'Retrieve a failed charge'
      operationId: getByFailedChargeId
      parameters:
        -
          $ref: '#/components/parameters/charge_id'
        -
          $ref: '#/components/parameters/created_at_min'
        -
          $ref: '#/components/parameters/created_at_max'
        -
          $ref: '#/components/parameters/test_mode'
      responses:
        '200':
          description: 'Successful operation'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedChargeService'
        '404':
          description: 'Failed charge could not found'
      security:
        -
          apiKeyAuth: []
  '/funnels/{id}/orders':
    get:
      tags:
        - Funnels
      description: 'Retrieve all orders associated with a specific funnel'
      operationId: getOrdersByFunnelId
      parameters:
        -
          name: id
          in: path
          description: 'The funnel ID'
          required: true
          schema:
            type: integer
        -
          $ref: '#/components/parameters/created_at_min'
        -
          $ref: '#/components/parameters/created_at_max'
        -
          $ref: '#/components/parameters/test_mode'
        -
          $ref: '#/components/parameters/pagination_offset'
        -
          $ref: '#/components/parameters/pagination_limit'
        -
          $ref: '#/components/parameters/pagination_direction'
      responses:
        '200':
          description: 'Successful operation. Response will return an array of 0 or more orders'
          content:
            application/json:
              schema:
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/OrderService' } }
                  pagination: { $ref: '#/components/schemas/Pagination' }
                type: object
        '404':
          description: 'Funnel could not be found'
      security:
        -
          apiKeyAuth: []
  /orders:
    get:
      tags:
        - Orders
      description: 'Retrieve all orders'
      operationId: getOrders
      parameters:
        -
          $ref: '#/components/parameters/created_at_min'
        -
          $ref: '#/components/parameters/created_at_max'
        -
          $ref: '#/components/parameters/test_mode'
        -
          $ref: '#/components/parameters/pagination_offset'
        -
          $ref: '#/components/parameters/pagination_limit'
        -
          $ref: '#/components/parameters/pagination_direction'
      responses:
        '200':
          description: 'Successful operation. Response will return an array of 0 or more orders'
          content:
            application/json:
              schema:
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/OrderService' } }
                  pagination: { $ref: '#/components/schemas/Pagination' }
                type: object
        '400':
          description: 'Bad request. Validation error on provided parameters'
          content:
            application/json:
              schema:
                properties:
                  success: { type: boolean, example: false }
                  error: { type: string, example: 'Validation error' }
                  data: { type: object, example: null, nullable: true }
                type: object
      security:
        -
          apiKeyAuth: []
  '/orders/{id}':
    get:
      tags:
        - Orders
      description: 'Retrieve an order'
      operationId: getByOrderId
      parameters:
        -
          $ref: '#/components/parameters/order_id'
        -
          $ref: '#/components/parameters/created_at_min'
        -
          $ref: '#/components/parameters/created_at_max'
        -
          $ref: '#/components/parameters/test_mode'
      responses:
        '200':
          description: 'Successful operation'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderService'
        '404':
          description: 'Order could not be found'
      security:
        -
          apiKeyAuth: []
    put:
      tags:
        - Orders
      description: 'Update order by ID'
      operationId: updateCustomFieldsByOrderId
      parameters:
        -
          $ref: '#/components/parameters/order_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                custom_field_slug:
                  description: 'Set this value to the slug of custom field'
                  type: string
                  example: custom_zL6FLFM3
                custom_field_data:
                  description: 'Set this value to the new data of the custom field'
                  type: string
                  example: America
              type: object
      responses:
        '200':
          description: 'Successful operation'
          content:
            application/json:
              schema:
                properties:
                  success: { description: 'True/False value if the request was successful', type: string, example: 'true' }
                  data: { description: 'The updated data', type: string, example: "custom_zL6FLFM3 updated to: 'America'" }
                type: object
        '404':
          description: 'Order could not be found'
      security:
        -
          apiKeyAuth: []
  '/orders/{id}/charges':
    get:
      tags:
        - Orders
      description: 'Retrieve all charges on an order'
      operationId: getChargesByOrderId
      parameters:
        -
          $ref: '#/components/parameters/order_id'
        -
          $ref: '#/components/parameters/created_at_min'
        -
          $ref: '#/components/parameters/created_at_max'
        -
          $ref: '#/components/parameters/test_mode'
      responses:
        '200':
          description: 'Successful operation. Response will return an array of 0 or more charges'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChargeService'
      security:
        -
          apiKeyAuth: []
  '/orders/{id}/customer':
    get:
      tags:
        - Orders
      description: 'Retrieve customer on an order'
      operationId: getCustomerByOrderId
      parameters:
        -
          $ref: '#/components/parameters/order_id'
      responses:
        '200':
          description: 'Successful operation'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerService'
        '404':
          description: 'Order or customer could not be found'
      security:
        -
          apiKeyAuth: []
  '/orders/{id}/subscriptions':
    get:
      tags:
        - Orders
      description: 'Retrieve all subscriptions on an order'
      operationId: getSubscriptionsByOrderId
      parameters:
        -
          $ref: '#/components/parameters/order_id'
        -
          $ref: '#/components/parameters/created_at_min'
        -
          $ref: '#/components/parameters/created_at_max'
        -
          $ref: '#/components/parameters/rebilling_at_min'
        -
          $ref: '#/components/parameters/rebilling_at_max'
        -
          $ref: '#/components/parameters/canceled_at_min'
        -
          $ref: '#/components/parameters/canceled_at_max'
        -
          $ref: '#/components/parameters/test_mode'
        -
          $ref: '#/components/parameters/subscription_status'
        -
          $ref: '#/components/parameters/subscription_type'
      responses:
        '200':
          description: 'Successful operation. Response will return an array of 0 or more subscriptions'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SubscriptionService'
      security:
        -
          apiKeyAuth: []
  /products:
    get:
      tags:
        - Products
      description: 'Retrieve all products'
      operationId: getProducts
      parameters:
        -
          $ref: '#/components/parameters/created_at_min'
        -
          $ref: '#/components/parameters/created_at_max'
        -
          $ref: '#/components/parameters/product_status'
        -
          $ref: '#/components/parameters/product_category'
        -
          $ref: '#/components/parameters/pricing_type'
        -
          $ref: '#/components/parameters/pagination_offset'
        -
          $ref: '#/components/parameters/pagination_limit'
        -
          $ref: '#/components/parameters/pagination_direction'
      responses:
        '200':
          description: 'Successful operation. Response will return an array of 0 or more products'
          content:
            application/json:
              schema:
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/ProductService' } }
                  pagination: { $ref: '#/components/schemas/Pagination' }
                type: object
      security:
        -
          apiKeyAuth: []
  '/products/{id}':
    get:
      tags:
        - Products
      description: 'Retrieve a product'
      operationId: getByProductId
      parameters:
        -
          $ref: '#/components/parameters/product_id'
        -
          $ref: '#/components/parameters/created_at_min'
        -
          $ref: '#/components/parameters/created_at_max'
        -
          $ref: '#/components/parameters/product_status'
        -
          $ref: '#/components/parameters/product_category'
        -
          $ref: '#/components/parameters/pricing_type'
      responses:
        '200':
          description: 'Successful operation'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductService'
        '404':
          description: 'Product could not be found'
      security:
        -
          apiKeyAuth: []
  '/products/{id}/orders':
    get:
      tags:
        - Products
      description: 'Retrieve all orders associated with a specific product'
      operationId: getOrdersByProductId
      parameters:
        -
          name: id
          in: path
          description: 'The product ID'
          required: true
          schema:
            type: integer
        -
          $ref: '#/components/parameters/created_at_min'
        -
          $ref: '#/components/parameters/created_at_max'
        -
          $ref: '#/components/parameters/test_mode'
        -
          $ref: '#/components/parameters/pagination_offset'
        -
          $ref: '#/components/parameters/pagination_limit'
        -
          $ref: '#/components/parameters/pagination_direction'
      responses:
        '200':
          description: 'Successful operation. Response will return an array of 0 or more orders'
          content:
            application/json:
              schema:
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/OrderService' } }
                  pagination: { $ref: '#/components/schemas/Pagination' }
                type: object
        '400':
          description: 'Bad request. Validation error on provided parameters'
          content:
            application/json:
              schema:
                properties:
                  success: { type: boolean, example: false }
                  error: { type: string, example: 'Validation error' }
                  data: { type: object, example: null, nullable: true }
                type: object
        '404':
          description: 'Product could not be found'
      security:
        -
          apiKeyAuth: []
  '/refunds/charges/{id}/':
    post:
      tags:
        - Refunds
      description: 'Refund an individual charge. Omit amount for full refund, or specify amount in cents for partial refund.'
      operationId: issueChargeRefund
      parameters:
        -
          $ref: '#/components/parameters/charge_id'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              properties:
                amount:
                  description: 'Refund amount in cents. Omit for full refund.'
                  type: integer
                  example: 2500
              type: object
      responses:
        '200':
          description: 'Successful operation'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundService'
        '400':
          description: 'Validation error (invalid amount, amount exceeds balance)'
        '404':
          description: 'Charge could not be found'
        '409':
          description: 'Charge has already been fully refunded'
      security:
        -
          apiKeyAuth: []
  /refunds:
    get:
      tags:
        - Refunds
      description: 'Get a paginated list of refunds for the marketplace. Custom sorting is not allowed, and results are sorted by Refund ID.'
      operationId: getAllRefunds
      parameters:
        -
          $ref: '#/components/parameters/pagination_offset'
        -
          $ref: '#/components/parameters/pagination_limit'
        -
          $ref: '#/components/parameters/pagination_direction'
      responses:
        '200':
          description: 'Successful operation'
          content:
            application/json:
              schema:
                properties:
                  data: { $ref: '#/components/schemas/RefundService' }
                  pagination: { $ref: '#/components/schemas/Pagination' }
                type: object
      security:
        -
          apiKeyAuth: []
  '/refunds/{id}':
    get:
      tags:
        - Refunds
      description: 'Get a single refund.'
      operationId: getRefund
      parameters:
        -
          $ref: '#/components/parameters/refund_id'
      responses:
        '200':
          description: 'Successful operation'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundService'
        '404':
          description: 'Refund could not be found'
      security:
        -
          apiKeyAuth: []
  '/subscriptions/{id}/cancel':
    post:
      tags:
        - Subscriptions
      description: 'Cancel an individual subscription. Only subscriptions with an active, delinquent, or paused status may be canceled.'
      operationId: cancelSubscription
      parameters:
        -
          $ref: '#/components/parameters/subscription_id'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              properties:
                silent_cancel:
                  description: 'Set this value to true so the Customer is not notified of the Subscription cancelation'
                  type: boolean
                  example: true
              type: object
      responses:
        '200':
          description: 'Successful operation'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionService'
        '404':
          description: 'Subscription could not be found'
        '409':
          description: 'Subscription status must be active, delinquent, or paused'
      security:
        -
          apiKeyAuth: []
  '/subscriptions/{id}/scheduleCancel':
    post:
      tags:
        - Subscriptions
      description: 'Schedule an individual subscription to be canceled. Only subscriptions with an active status may be scheduled.'
      operationId: scheduleCancelSubscription
      parameters:
        -
          $ref: '#/components/parameters/subscription_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                cancel_when:
                  description: 'Either custom or end. When selecting end, the Subscription will be canceled at the end of the current billing period. When selecting custom, the Subscription will be canceled on the date specified with the schedule_date parameter'
                  type: string
                  example: custom
                schedule_date:
                  description: 'The date at which the Subscription should cancel. If cancel_when is set to custom, this parameter is required.'
                  type: string
                  example: '2022-04-08'
              type: object
      responses:
        '200':
          description: 'Successful operation'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionService'
        '404':
          description: 'Subscription could not be found'
        '409':
          description: 'Subscription could not be canceled because it was either already canceled, scheduled to be canceled, or not active'
      security:
        -
          apiKeyAuth: []
  /subscriptions:
    get:
      tags:
        - Subscriptions
      description: 'Retrieve all subscriptions'
      operationId: getSubscriptions
      parameters:
        -
          $ref: '#/components/parameters/created_at_min'
        -
          $ref: '#/components/parameters/created_at_max'
        -
          $ref: '#/components/parameters/rebilling_at_min'
        -
          $ref: '#/components/parameters/rebilling_at_max'
        -
          $ref: '#/components/parameters/canceled_at_min'
        -
          $ref: '#/components/parameters/canceled_at_max'
        -
          $ref: '#/components/parameters/test_mode'
        -
          $ref: '#/components/parameters/subscription_status'
        -
          $ref: '#/components/parameters/subscription_type'
        -
          $ref: '#/components/parameters/pagination_offset'
        -
          $ref: '#/components/parameters/pagination_limit'
        -
          $ref: '#/components/parameters/pagination_direction'
      responses:
        '200':
          description: 'Successful operation. Response will return an array of 0 or more subscriptions'
          content:
            application/json:
              schema:
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/SubscriptionService' } }
                  pagination: { $ref: '#/components/schemas/Pagination' }
                type: object
      security:
        -
          apiKeyAuth: []
  '/subscriptions/{id}':
    get:
      tags:
        - Subscriptions
      description: 'Retrieve a subscription'
      operationId: getSubscriptionById
      parameters:
        -
          $ref: '#/components/parameters/subscription_id'
        -
          $ref: '#/components/parameters/created_at_min'
        -
          $ref: '#/components/parameters/created_at_max'
        -
          $ref: '#/components/parameters/rebilling_at_min'
        -
          $ref: '#/components/parameters/rebilling_at_max'
        -
          $ref: '#/components/parameters/canceled_at_min'
        -
          $ref: '#/components/parameters/canceled_at_max'
        -
          $ref: '#/components/parameters/test_mode'
        -
          $ref: '#/components/parameters/subscription_status'
        -
          $ref: '#/components/parameters/subscription_type'
      responses:
        '200':
          description: 'Successful operation'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionService'
        '404':
          description: 'Subscription could not be found'
      security:
        -
          apiKeyAuth: []
  '/subscriptions/{id}/charges':
    get:
      tags:
        - Subscriptions
      description: 'Retrieve charges on a subscription'
      operationId: getChargesBySubscriptionID
      parameters:
        -
          $ref: '#/components/parameters/subscription_id'
        -
          $ref: '#/components/parameters/created_at_min'
        -
          $ref: '#/components/parameters/created_at_max'
        -
          $ref: '#/components/parameters/test_mode'
      responses:
        '200':
          description: 'Successful operation. Response will return an array of 0 or more charges'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChargeService'
        '404':
          description: 'Subscription could not be found'
      security:
        -
          apiKeyAuth: []
  '/subscriptions/{id}/customer':
    get:
      tags:
        - Subscriptions
      description: 'Retrieve a customer on a subscription'
      operationId: getCustomerBySubscriptionID
      parameters:
        -
          $ref: '#/components/parameters/subscription_id'
      responses:
        '200':
          description: 'Successful operation'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerService'
        '404':
          description: 'Subscription or customer could not be found'
      security:
        -
          apiKeyAuth: []
  '/subscriptions/{id}/history':
    get:
      tags:
        - Subscriptions
      description: "Retrieve a subscription's history"
      operationId: getHistoriesBySubscriptionID
      parameters:
        -
          $ref: '#/components/parameters/subscription_id'
        -
          $ref: '#/components/parameters/created_at_min'
        -
          $ref: '#/components/parameters/created_at_max'
      responses:
        '200':
          description: 'Successful operation. Response will return an array of 0 or more history entries'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SubscriptionHistoryService'
        '404':
          description: 'Subscription could not be found'
      security:
        -
          apiKeyAuth: []
  '/subscriptions/{id}/plan':
    get:
      tags:
        - Subscriptions
      description: 'Retrieve a plan for a subscription'
      operationId: getPlanBySubscriptionID
      parameters:
        -
          $ref: '#/components/parameters/subscription_id'
        -
          $ref: '#/components/parameters/created_at_min'
        -
          $ref: '#/components/parameters/created_at_max'
      responses:
        '200':
          description: 'Successful operation'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionPlanService'
        '404':
          description: 'Subscription could not be found'
      security:
        -
          apiKeyAuth: []
  '/subscriptions/{id}/update':
    post:
      tags:
        - Subscriptions
      description: 'Update a subscription. Currently supports updating the next rebilling date. Only subscriptions with an active or delinquent status may be updated.'
      operationId: updateSubscription
      parameters:
        -
          $ref: '#/components/parameters/subscription_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - next_rebilling_date
              properties:
                next_rebilling_date:
                  description: 'The new next rebilling date for the subscription in ISO 8601 format. Must be a future date. For Stripe-managed subscriptions, must be within 2 years.'
                  type: string
                  format: date-time
                  example: '2026-06-15T00:00:00Z'
              type: object
      responses:
        '200':
          description: 'Successful operation'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionService'
        '404':
          description: 'Subscription could not be found'
        '409':
          description: 'Subscription status must be active or delinquent'
        '422':
          description: 'Validation error - invalid date or date exceeds processor limits'
      security:
        -
          apiKeyAuth: []
  '/upsells/{id}/orders':
    get:
      tags:
        - Upsells
      description: 'Retrieve all orders associated with a specific upsell'
      operationId: getOrdersByUpsellId
      parameters:
        -
          name: id
          in: path
          description: 'The upsell ID'
          required: true
          schema:
            type: integer
        -
          $ref: '#/components/parameters/created_at_min'
        -
          $ref: '#/components/parameters/created_at_max'
        -
          $ref: '#/components/parameters/test_mode'
        -
          $ref: '#/components/parameters/pagination_offset'
        -
          $ref: '#/components/parameters/pagination_limit'
        -
          $ref: '#/components/parameters/pagination_direction'
      responses:
        '200':
          description: 'Successful operation. Response will return an array of 0 or more orders'
          content:
            application/json:
              schema:
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/OrderService' } }
                  pagination: { $ref: '#/components/schemas/Pagination' }
                type: object
        '400':
          description: 'Bad request. Validation error on provided parameters'
          content:
            application/json:
              schema:
                properties:
                  success: { type: boolean, example: false }
                  error: { type: string, example: 'Validation error' }
                  data: { type: object, example: null, nullable: true }
                type: object
        '404':
          description: 'Upsell could not be found'
      security:
        -
          apiKeyAuth: []
components:
  schemas:
    Pagination:
      description: 'Optional information for paginating large data sets.'
      properties:
        next:
          description: 'A URL to the next page of data to be retrieve. If current page is the last page this value will be null.'
          type: string
          format: uri
          example: 'https://example.samcart.com/v1/example?offset=1337&dir=next'
          nullable: true
        prev:
          description: 'A URL to the previous page of data to be retrieve. If current page is the first page this value will be null.'
          type: string
          format: uri
          example: null
          nullable: true
      type: object
    AddressService:
      title: Address
      description: Address
      properties:
        type:
          description: 'The type of address for the customer'
          enum:
            - shipping
            - billing
          example: shipping
        street:
          description: 'The street for the customer'
          type: string
          example: '221B Baker Street'
        postal_code:
          description: 'The postal code for the customer'
          type: string
          example: '1234'
        city:
          description: 'The city name for the customer'
          type: string
          example: Austin
        state:
          description: 'The 2-letter state code for US customers. For non-US addresses this value will be null.'
          type: string
          example: TX
          nullable: true
        region:
          description: 'The optional sub-divided area of a country for international customers. For US addresses this value will be null.'
          type: string
          example: Quebec
          nullable: true
        country:
          description: 'The country for the customer'
          type: string
          example: 'United States'
      type: object
    ChargeService:
      title: Charge
      description: Charge
      properties:
        id:
          description: 'The SamCart ID for the charge'
          type: integer
          example: 1337
        customer_id:
          description: 'The SamCart ID for the customer that created the charge'
          type: integer
          example: 1234
        affiliate_id:
          description: 'The SamCart ID of the affiliate credited for the order'
          type: integer
          example: 1001
          nullable: true
        order_id:
          description: 'The SamCart ID for the order. For subscriptions, this will be the order ID of the original purchase'
          type: integer
          example: 1001
        subscription_rebill_id:
          description: 'The SamCart ID for the subscription rebill. If the charge is for a non-subscription product, this will be null.'
          type: integer
          example: 1001
          nullable: true
        test_mode:
          description: 'Indicates whether the transaction was done while the product was in test mode'
          type: boolean
          example: true
        processor_name:
          description: 'The name of the processor for the order'
          type: string
          enum:
            - Stripe
            - Braintree
            - Authorize.net
            - PayPal
          example: Stripe
        processor_transaction_id:
          description: 'The processor ID generated for the charge'
          type: string
          example: 01234ABCD
        currency:
          description: 'The 3 letter identifier for the currency for the charge'
          type: string
          example: USD
        card_used:
          description: 'The last 4 digits of the card that was used. PayPal charges will have a null value.'
          type: number
          example: '4242'
          nullable: true
        charge_refund_status:
          description: 'Indicates whether a refund and the type of refund. If no refund was created the value will be null.'
          type: string
          enum:
            - refunded
            - partially_refunded
          example: partially_refunded
          nullable: true
        order_date:
          description: 'The UTC date and time for when the order was created'
          type: string
          format: date-time
          example: '2021-03-08 00:18:35'
        created_at:
          description: 'The UTC date and time that the charge was created'
          type: string
          format: date-time
          example: '2021-03-08 00:18:35'
        total:
          description: 'The total (in cents) for the charge including taxes and shipping fees'
          type: integer
          example: 10025
      type: object
    CustomerService:
      title: Customer
      description: Customer
      properties:
        id:
          description: 'The SamCart ID of the customer'
          type: integer
          example: 1337
        first_name:
          description: 'The first name of the customer'
          type: string
          example: John
          nullable: true
        last_name:
          description: 'The last name of the customer'
          type: string
          example: Doe
          nullable: true
        email:
          description: 'The email address of the customer'
          type: string
          format: email
          example: jdoe@gmail.com
        phone:
          description: 'The phone number of the customer'
          type: string
          example: '5555555555'
          nullable: true
        customer_tags:
          description: 'The tags applied to the customer'
          type: array
          items:
            properties:
              name:
                description: 'The name of the customer tag'
                type: string
                example: new
            type: object
        lifetime_value:
          description: 'The lifetime value (in cents) of the customer. Value is for live data only'
          type: integer
          example: 95025
        updated_at:
          description: 'The UTC date and time when the customer information was updated'
          type: string
          format: date-time
          example: '2020-03-04 00:18:35'
        created_at:
          description: 'The UTC date and time when the customer was created'
          type: string
          format: date-time
          example: '2020-03-04 00:18:35'
        addresses:
          description: 'Addresses associated with the customer'
          type: array
          items:
            $ref: '#/components/schemas/AddressService'
      type: object
    FailedChargeService:
      title: 'Failed Charge'
      description: 'Failed Charge'
      properties:
        id:
          description: 'The SamCart ID for the charge'
          type: integer
          example: 1337
        customer_id:
          description: 'The SamCart ID for the customer that created the charge'
          type: integer
          example: 1234
          nullable: true
        affiliate_id:
          description: 'The SamCart ID of the affiliate credited for the order'
          type: integer
          example: 1001
          nullable: true
        order_id:
          description: 'The SamCart ID for the order. For subscriptions, this will be the order ID of the original purchase'
          type: integer
          example: 1001
          nullable: true
        subscription_rebill_id:
          description: 'The SamCart ID for the subscription rebill. If the charge is for a non-subscription product, this will be null.'
          type: integer
          example: 1001
          nullable: true
        test_mode:
          description: 'Indicates whether the transaction was done while the product was in test mode'
          type: boolean
          example: true
        processor_name:
          description: 'The name of the processor for the order'
          type: string
          enum:
            - Stripe
            - Braintree
            - Authorize.net
            - PayPal
          example: Stripe
        processor_transaction_id:
          description: 'The processor ID generated for the charge'
          type: string
          example: 01234ABCD
        error:
          description: 'The error message provided by the payment processor'
          type: string
          example: 'Your card was declined'
          nullable: true
        currency:
          description: 'The 3 letter identifier for the currency for the charge'
          type: string
          example: USD
        card_used:
          description: 'The last 4 digits of the card that was used. PayPal charges will have a null value.'
          type: number
          example: '4242'
          nullable: true
        created_at:
          description: 'The UTC date and time that the charge was created'
          type: string
          format: date-time
          example: '2021-03-08 00:18:35'
        total:
          description: 'The total (in cents) for the charge including taxes and shipping fees'
          type: integer
          example: 10025
      type: object
    OrderService:
      title: Order
      description: Order
      properties:
        id:
          description: 'The SamCart ID of the order'
          type: integer
          example: 1337
        customer_id:
          description: 'The SamCart ID of the customer'
          type: integer
          example: 1234
        affiliate_id:
          description: 'The SamCart ID of the affiliate credited for the order'
          type: integer
          example: 1001
          nullable: true
        funnel_id:
          description: 'The funnel ID associated with this order. Null if the order was not placed through a funnel.'
          type: integer
          example: 12345
          nullable: true
        upsell_id:
          description: 'The upsell ID if this order contains upsell purchases. Null if the order has no upsell items. For orders with multiple upsells, returns the first upsell ID.'
          type: integer
          example: 5678
          nullable: true
        test_mode:
          description: 'Indicates whether the transaction was done while the product was in test mode'
          type: boolean
          example: true
        order_date:
          description: 'The UTC date and time for when the order was created'
          type: string
          format: date-time
          example: '2021-03-08 00:18:35'
        cart_items:
          description: 'A list of cart items on the order'
          type: array
          items:
            properties:
              id:
                description: 'The ID for the specific cart item'
                type: integer
                example: 1234
              product_id:
                description: 'The SamCart ID for the product'
                type: integer
                example: 1234
              subscription_id:
                description: 'The subscription ID for the product. If the cart item is for a non-subscription product the value will be null'
                type: integer
                example: 1234
                nullable: true
              upsell_id:
                description: 'The SamCart ID for the upsell. If the cart item is not from an upsell the value will be null'
                type: integer
                example: 5678
                nullable: true
              sku:
                description: 'The optional product SKU of the cart item purchased'
                type: string
                example: sku1234
                nullable: true
              internal_product_name:
                description: 'An optional product name displayed on the marketplace dashboard'
                type: string
                example: internal-book-product
                nullable: true
              product_name:
                description: 'The product name displayed to customers'
                type: string
                example: Book
                nullable: true
              charge_id:
                description: 'The SamCart ID for the charge'
                type: integer
                example: 1234
                nullable: true
              pricing_type:
                description: 'Indicates how the product is priced'
                type: string
                enum:
                  - one_time
                  - recurring_subscription
                  - limited_subscription
                  - pwyw_onetime
                  - pwyw_recurring_subscription
                  - pwyw_limited_subscription
                example: one_time
                nullable: true
              processor_transaction_id:
                description: 'The processor ID generated for the charge'
                type: string
                example: 01234ABCD
                nullable: true
              currency:
                description: 'The 3 letter identifier for the currency for the charge on the cart item'
                type: string
                example: USD
              quantity:
                description: 'The quantity of the cart item purchased'
                type: integer
                example: 2
              status:
                description: 'The current status of the charge on the cart item'
                type: string
                enum:
                  - pending
                  - charged
                  - declined
                  - refunded
                  - fulfilled
                  - reversed
                  - partially_refunded
                example: charged
              upgraded:
                description: 'Indicates if the item was upgraded to another item in the cart'
                type: boolean
                example: true
              initial_price:
                description: 'The pricing structure for one-time purchases and for the first charge on subscription products'
                properties:
                  subtotal: { description: 'The price for the cart item (in cents) excluding discount, taxes and shipping fees', type: integer, example: 10000 }
                  taxes: { description: 'The tax fees (in cents) for the cart item', type: integer, example: 500 }
                  shipping: { description: 'The shipping fees (in cents) for the cart item', type: integer, example: 300 }
                  total: { description: 'The price for the cart item (in cents) including discount, taxes and shipping fees', type: integer, example: 9800 }
                type: object
              recurring_price:
                description: 'The pricing structure for limited and recurring subscription products. This structure could differ from the initial price.'
                properties:
                  subtotal: { description: 'The recurring price for the cart item (in cents) excluding discount, taxes and shipping fees', type: integer, example: 10000 }
                  taxes: { description: 'The recurring tax fees (in cents) for the cart item', type: integer, example: 500 }
                  shipping: { description: 'The recurring shipping fees (in cents) for the cart item', type: integer, example: 300 }
                  total: { description: 'The recurring price for the cart item (in cents) including discount, taxes and shipping fees', type: integer, example: 10800 }
                type: object
              coupon:
                description: 'An optional coupon that was applied to the cart item'
                properties:
                  id: { description: 'The ID of the coupon that was used on the cart item', type: integer, example: '1234' }
                  charge_instance: { description: 'Whether the coupon applies only once or for recurring charges also', type: string, enum: [one_time, recurring], example: one_time }
                  code: { description: 'The code of the coupon used', type: string, example: summersale }
                  type: { description: 'The type of discount applied', type: string, enum: [flat_rate, percentage], example: flat_rate }
                  discount_amount: { description: 'The flat_rate discount amount (in cents) on the cart item', type: integer, example: null, nullable: true }
                  discount_percentage: { description: 'The percentage discount on the cart item', type: integer, example: 10, nullable: true }
                type: object
            type: object
        subtotal:
          description: 'The total price of the order (in cents) excluding discount, shipping and tax fees'
          type: integer
          example: 10000
        discount:
          description: 'The total discount (in cents) on the order'
          type: integer
          example: 1000
        taxes:
          description: 'The total of tax fees (in cents) of the order'
          type: integer
          example: 500
        shipping:
          description: 'The total of shipping fees (in cents) of the order'
          type: integer
          example: 300
        shipping_address:
          oneOf:
            -
              $ref: '#/components/schemas/AddressService'
          nullable: true
          description: 'The shipping address on the order'
        total:
          description: 'The total price of the order (in cents) including discount, shipping and tax fees'
          type: integer
          example: 9800
        card_used:
          description: 'The last 4 digits of the card that was used. PayPal charges will have a null value.'
          type: string
          example: '0123'
          nullable: true
        processor_name:
          description: 'The name of the processor for the order'
          type: string
          enum:
            - Stripe
            - Braintree
            - Authorize.net
            - PayPal
          example: Stripe
        custom_fields:
          description: 'Optional custom fields applied to the order'
          properties:
            Name:
              description: 'This will return the name given to this custom field'
              properties:
                value:
                  description: 'The value of this custom field'
                  type: string
                  example: Blue
                slug:
                  description: 'The slug associated with this custom field'
                  type: string
                  example: custom_zL6FLFM3
              type: object
          type: object
        upsell_custom_fields:
          description: 'Optional custom fields applied to the upsells for the order'
          type: object
        utm_parameters:
          description: 'UTM Parameters'
          properties:
            medium:
              description: 'UTM Medium'
              type: string
            source:
              description: 'UTM Source'
              type: string
            campaign:
              description: 'UTM Campaign'
              type: string
            content:
              description: 'UTM Content'
              type: string
            lead_source:
              description: 'UTM Lead Source'
              type: string
          type: object
        custom_parameters:
          description: 'Custom Parameters'
          properties:
            key:
              description: 'Custom Paramater Key'
              type: string
          type: object
      type: object
    ProductService:
      title: Product
      description: Product
      properties:
        id:
          description: 'The SamCart ID of the product'
          type: integer
          example: 1337
        sku:
          description: 'An optional product SKU displayed on the marketplace dashboard'
          type: string
          example: sku123
          nullable: true
        internal_product_name:
          description: 'An optional product name displayed on the marketplace dashboard'
          type: string
          example: internal-book-product
          nullable: true
        product_name:
          description: 'The product name displayed to customers'
          type: string
          example: Book
        description:
          description: 'The optional description of the product'
          type: string
          example: 'This is a good book'
          nullable: true
        currency:
          description: 'The 3 letter identifier for the currency currently configured on the product. This can be changed.'
          type: string
          example: USD
        price:
          description: 'The price of the product. For subscription products, it is the initial price (in cents)'
          type: number
          format: float
          example: 1025
        product_category:
          description: 'Indicates the type of product being sold'
          type: string
          enum:
            - physical
            - digital
          example: physical
        pricing_type:
          description: 'Indicates how the product will be priced'
          type: string
          enum:
            - one_time
            - limited
            - recurring
            - pwyw
          example: one_time
        status:
          description: 'Indicates the current status of the product'
          type: string
          enum:
            - live
            - test
            - archived
          example: live
        taxes:
          description: 'Indicates if the product is currently configured to have taxes. This can be changed.'
          type: boolean
          example: true
        upsell_funnel:
          description: 'The name of the upsell funnel attached to the product'
          type: string
          example: 'Additional Offer'
          nullable: true
        order_bumps:
          description: 'An optional list of additional products added with the product before checkout'
          type: array
          items:
            properties:
              product_id:
                description: 'The SamCart ID for the additional product'
                type: integer
                example: 1234
              product_name:
                description: 'The name of the additional product'
                type: string
                example: Binder
            type: object
        bundled_products:
          description: 'An optional list of products bundled to the product'
          type: array
          items:
            properties:
              product_id:
                description: 'The SamCart ID of the bundled product'
                type: integer
                example: 3423
              product_name:
                description: 'The bundled product name displayed to customers'
                type: string
                example: Magazine
            type: object
        slug:
          description: 'The URL slug for the product'
          type: string
          example: book
        custom_domain:
          description: 'An optional custom domain used for the product'
          type: string
          format: uri
          example: 'https://google.com'
          nullable: true
        product_tags:
          description: 'An optional list of product tags'
          type: array
          items:
            properties:
              name:
                description: 'The name of the product tag'
                type: string
                example: digital
            type: object
        created_at:
          description: 'The UTC date and time the product was created'
          type: string
          format: date-time
          example: '2021-01-14 18:03:59'
        updated_at:
          description: 'The UTC date and time the product was updated'
          type: string
          format: date-time
          example: '2021-01-14 18:03:59'
        archived_date:
          description: 'The UTC date and time the product was archived. If the product has not been archive the value will be null.'
          type: string
          format: date-time
          example: '2021-01-14 18:03:59'
          nullable: true
      type: object
    RefundService:
      title: Refund
      description: Refund
      properties:
        id:
          description: 'The SamCart ID for the refund'
          type: integer
          example: 1337
        charge_id:
          description: 'The SamCart ID for the charge'
          type: integer
          example: 1337
        cart_item_id:
          description: 'The ID for the refunded cart item'
          type: integer
          example: 1234
        created_at:
          description: 'The UTC date and time the refund was issued'
          type: string
          format: date-time
          example: '2020-03-04 00:18:35'
        test_mode:
          description: 'Indicates whether the transaction was done while the transaction was in test mode.'
          type: boolean
          example: true
        charge_refund_status:
          description: 'Indicates whether a refund and the type of refund. If no refund was created the value will be null.'
          type: string
          enum:
            - refunded
            - partially_refunded
          example: refunded
          nullable: true
        currency:
          description: 'This will match the currency that the original charge was created in and will be the currency of the created refund'
          type: string
          example: USD
        refund_amount:
          description: 'The total refund amount (in cents)'
          type: integer
          example: 1525
        remaining_refundable_amount:
          description: 'The remaining refundable amount on the charge after this refund (in cents)'
          type: integer
          example: 7500
        charge:
          $ref: '#/components/schemas/ChargeTransformer'
        order:
          $ref: '#/components/schemas/OrderTransformer'
      type: object
    SubscriptionCancelService:
      title: 'Subscription Cancel'
      description: 'Subscription Cancel'
      type: object
    SubscriptionHistoryService:
      title: 'Subscription History'
      description: 'Subscription History'
      properties:
        id:
          description: 'The SamCart ID for the subscription history record'
          type: integer
          example: 1337
        subscription_id:
          description: 'The SamCart ID for the subscription'
          type: integer
          example: 1001
        new_status:
          description: 'The status of the subscription'
          type: string
          enum:
            - active
            - canceled
            - delinquent
            - completed
            - paused
            - invalid_processor
            - sca_required
            - deleted
          example: active
        source:
          description: 'The source of the change'
          type: string
          example: dashboard
        type:
          description: 'The type of change'
          type: string
          example: status
        change_date:
          description: 'The UTC date and time that the change was made'
          type: string
          format: date-time
          example: '2021-03-08 00:18:35'
      type: object
    SubscriptionPlanService:
      title: 'Subscription Plan'
      description: 'Subscription Plan'
      properties:
        id:
          description: 'The SamCart ID for the subscription plan'
          type: integer
          example: 1337
        product_id:
          description: 'The SamCart ID for the product'
          type: integer
          example: 1234
        plan_status:
          description: 'The current status of the subscription plan'
          type: string
          enum:
            - active
            - archived
          example: active
        plan_archived_date:
          description: 'The UTC date and time for when the subscription plan was archived'
          type: string
          format: date-time
          example: '2021-03-02 01:23:34'
          nullable: true
        plan_duration:
          description: 'For a limited subscription, this indicates the number of rebills'
          type: integer
          example: 2
        plan_frequency:
          description: 'Indicates how frequently the subscription will rebill'
          type: string
          enum:
            - days
            - weekly
            - monthly
            - quarterly
            - yearly
          example: days
        plan_price:
          description: 'The recurring price of subscription exclusing tax and shipping fees'
          type: integer
          example: 9825
        trial_period:
          description: 'The number of days that the subscription has for a trial'
          type: integer
          example: 2
        rebill_days:
          description: "The number of days between each subscription rebill, used for 'days' frequency only"
          type: integer
          example: 15
        stripe_compatible:
          description: 'Indicates whether the subscription will be Stripe-managed'
          type: boolean
          example: true
        stripe_plan_id:
          description: 'For Stripe-managed subscriptions, this is the plan ID from within Stripe'
          type: string
          example: samcart_plan_1_12345
          nullable: true
        on_stripe_sandbox:
          description: 'Indicates whether the subscription is associated with a Stripe testing environment'
          type: boolean
          example: true
        recurring_shipping:
          description: 'Indicates whether the shipping prices for the subscription will be charged at every subscription rebill'
          type: boolean
          example: true
      type: object
    SubscriptionService:
      title: Subscription
      description: Subscription
      properties:
        id:
          description: 'The SamCart ID for the subscription'
          type: integer
          example: 1337
        customer_id:
          description: 'The SamCart ID for the customer that created the charge'
          type: integer
          example: 1234
        affiliate_id:
          description: 'The SamCart ID of the affiliate credited for the order.'
          type: integer
          example: 1001
          nullable: true
        order_id:
          description: 'The SamCart ID for the order. For subscriptions, this will be the order ID of the original purchase.'
          type: integer
          example: 1001
        product_id:
          description: 'The SamCart ID for a product in the cart'
          type: integer
          example: 1001
        sku:
          description: 'The optional product SKU for the subscription'
          type: string
          example: sku123
          nullable: true
        status:
          description: 'The status of the subscription'
          type: string
          enum:
            - active
            - canceled
            - delinquent
            - completed
            - paused
            - invalid_processor
            - sca_required
            - deleted
          example: active
        type:
          description: 'Indicates the format of the subscription'
          type: string
          enum:
            - limited_subscription
            - recurring_subscription
          example: recurring_subscription
        product_name:
          description: 'The name of the product for the subscription'
          type: string
          example: 'Cool Product'
        internal_product_name:
          description: 'An optional product name displayed on the marketplace dashboard for the subscription'
          type: string
          example: 'Cool Product'
          nullable: true
        initial_price:
          description: 'The pricing structure for the first charge of the subscription'
          properties:
            subtotal:
              description: 'The initial price (in cents) excluding discount, taxes and shipping fees'
              type: integer
              example: 10000
            taxes:
              description: 'The initial tax fees (in cents)'
              type: integer
              example: 500
            shipping:
              description: 'The initial shipping fees (in cents)'
              type: integer
              example: 300
            total:
              description: 'The initial price (in cents) including discount, taxes and shipping fees'
              type: integer
              example: 9800
          type: object
        recurring_price:
          description: 'The pricing structure for all the recurring charges of the subscription'
          properties:
            subtotal:
              description: 'The recurring price (in cents) excluding discount, taxes and shipping fees'
              type: integer
              example: 10000
            taxes:
              description: 'The recurring tax fees (in cents)'
              type: integer
              example: 500
            shipping:
              description: 'The recurring shipping fees (in cents)'
              type: integer
              example: 300
            total:
              description: 'The recurring price (in cents) including discount, taxes and shipping fees'
              type: integer
              example: 10800
          type: object
        coupon:
          description: 'An optional coupon that is applied to the subscription rebill'
          properties:
            id:
              description: 'The ID of the coupon that was used on the subscription'
              type: integer
              example: '1234'
            charge_instance:
              description: 'Whether the coupon applies only once or for recurring charges also'
              type: string
              enum:
                - one_time
                - recurring
              example: one_time
            code:
              description: 'The code of the coupon used'
              type: string
              example: summersale
            type:
              description: 'The type of discount applied'
              type: string
              enum:
                - flat_rate
                - percentage
              example: flat_rate
            discount_amount:
              description: 'The flat_rate discount amount (in cents) on the subscription'
              type: integer
              example: null
              nullable: true
            discount_percentage:
              description: 'The percentage discount on the subscription'
              type: integer
              example: 10
              nullable: true
          type: object
        cancel_schedule:
          $ref: '#/components/schemas/SubscriptionScheduledCancellationsTransformer'
        processor_name:
          description: 'The name of the processor for the order'
          type: string
          enum:
            - Stripe
            - Braintree
            - Authorize.net
            - PayPal
          example: Stripe
        test_mode:
          description: 'Indicates whether the transaction was done while the product was in test mode.'
          type: boolean
          example: true
        card_used:
          description: 'The last 4 digits of the card that was used. PayPal charges will have a null value.'
          type: number
          example: '4242'
          nullable: true
        created_at:
          description: 'The UTC date and time the subscription was created. This is also when the original order was created.'
          type: string
          format: date-time
          example: '2021-03-08 00:18:35'
        start_date:
          description: 'The UTC date and time the first rebill occurred. For subscriptions with trials, this will be the first rebill after the trial.'
          type: string
          format: date-time
          example: '2021-03-08 00:18:35'
        end_date:
          description: 'The UTC date and time that a limited subscription will end. Recurring subscriptions will not have a value.'
          type: string
          format: date-time
          example: '2021-03-08 00:18:35'
          nullable: true
        next_rebilling_date:
          description: 'The UTC date and time of the next rebill for the subscription'
          type: string
          format: date-time
          example: '2021-04-08 00:18:35'
        total_failed_charges:
          description: 'The number of unsuccessful charges for this subscription'
          type: integer
          example: 1
        subscription_interval:
          description: 'The billing interval for the subscription'
          type: string
          enum:
            - days
            - weekly
            - monthly
            - quarterly
            - yearly
          example: monthly
        stripe_plan_id:
          description: 'The Stripe plan ID associated with this subscription'
          type: string
          example: plan_abc123
          nullable: true
      type: object
    ChargeTransformer:
      title: Charges
      description: Charges
      properties:
        id:
          description: 'The id of the charge'
          type: integer
          example: '1'
        charge_date:
          description: 'The UTC date and time that the charge was applied.'
          type: string
          format: date-time
          example: '2021-03-08 00:18:35'
          nullable: true
        total:
          description: 'The total amount charged in cents.'
          type: integer
          example: '15000'
          nullable: true
        test_mode:
          description: 'Whether the charge was created in test mode or not.'
          type: boolean
          example: true
        processor_transaction_id:
          description: 'The transaction ID from the processor.'
          type: string
          example: H241L4ZX
        currency:
          description: 'The currency type used for the charge.'
          type: string
          example: USD
        card_used:
          description: 'The last 4 digits of the card used.'
          type: string
          example: '4242'
          nullable: true
        paypal_email:
          description: 'The paypal email used.'
          type: string
          example: my_paypal@email.com
          nullable: true
      type: object
    OrderTransformer:
      title: Orders
      description: Orders
      properties:
        id:
          description: 'The id of the order'
          type: integer
          example: '1'
        test_mode:
          description: 'Whether the order was created in test mode or not.'
          type: boolean
          example: true
        subtotal:
          description: 'The order subtotal in cents.'
          type: integer
          example: '100000'
        total:
          description: 'The order subtotal in cents.'
          type: integer
          example: '100000'
        shipping:
          description: 'The order shipping in cents.'
          type: integer
          example: '500'
        tax:
          description: 'The order tax in cents.'
          type: integer
          example: '100'
      type: object
    RefundTransformer:
      title: Refund
      description: Refund
      properties:
        id:
          description: 'The SamCart ID for the refund'
          type: integer
          example: 1337
        amount:
          description: 'The total refund amount (in cents)'
          type: integer
          example: 1525
        currency:
          description: 'This will match the currency that the original charge was created in and will be the currency of the created refund'
          type: string
          example: USD
        charge_refund_status:
          description: 'Indicates whether a refund and the type of refund. If no refund was created the value will be null.'
          type: string
          enum:
            - refunded
            - partially_refunded
          example: refunded
          nullable: true
        created_at:
          description: 'The UTC date and time the refund was issued'
          type: string
          format: date-time
          example: '2020-03-04 00:18:35'
      type: object
    SubscriptionScheduledCancellationsTransformer:
      title: 'Subscription Scheduled Cancelations'
      description: SubscriptionScheduledCancellations
      properties:
        status:
          description: 'The status of the cancelation'
          type: string
          example: scheduled
        cancel_date:
          description: 'The UTC date and time that a subscription is scheduled to end.'
          type: string
          format: date-time
          example: '2021-03-08 00:18:35'
          nullable: true
      type: object
  parameters:
    created_at_min:
      name: created_at_min
      in: query
      description: 'Filter by created at date/time at or after given value. Accepts ISO 8601/RFC 3339 format with timezone (e.g., 2025-01-16T14:30:00Z) or date-only (e.g., 2025-01-16). Date-only values use 00:00:00 UTC.'
      schema:
        type: string
        format: date-time
      example: '2025-01-16T14:30:00Z'
    created_at_max:
      name: created_at_max
      in: query
      description: 'Filter by created at date/time at or before given value. Accepts ISO 8601/RFC 3339 format with timezone (e.g., 2025-01-16T14:30:00Z) or date-only (e.g., 2025-01-16). Date-only values use 23:59:59 UTC.'
      schema:
        type: string
        format: date-time
      example: '2025-01-16T23:59:59Z'
    canceled_at_min:
      name: canceled_at_min
      in: query
      description: 'Filter by canceled date/time at or after given value. Accepts ISO 8601/RFC 3339 format with timezone (e.g., 2025-01-16T14:30:00Z) or date-only (e.g., 2025-01-16). Date-only values use 00:00:00 UTC.'
      schema:
        type: string
        format: date-time
      example: '2025-01-16T14:30:00Z'
    canceled_at_max:
      name: canceled_at_max
      in: query
      description: 'Filter by canceled date/time at or before given value. Accepts ISO 8601/RFC 3339 format with timezone (e.g., 2025-01-16T14:30:00Z) or date-only (e.g., 2025-01-16). Date-only values use 23:59:59 UTC.'
      schema:
        type: string
        format: date-time
      example: '2025-01-16T23:59:59Z'
    rebilling_at_min:
      name: rebilling_at_min
      in: query
      description: 'Filter by rebilling date/time at or after given value. Accepts ISO 8601/RFC 3339 format with timezone (e.g., 2025-01-16T14:30:00Z) or date-only (e.g., 2025-01-16). Date-only values use 00:00:00 UTC.'
      schema:
        type: string
        format: date-time
      example: '2025-01-16T14:30:00Z'
    rebilling_at_max:
      name: rebilling_at_max
      in: query
      description: 'Filter by rebilling date/time at or before given value. Accepts ISO 8601/RFC 3339 format with timezone (e.g., 2025-01-16T14:30:00Z) or date-only (e.g., 2025-01-16). Date-only values use 23:59:59 UTC.'
      schema:
        type: string
        format: date-time
      example: '2025-01-16T23:59:59Z'
    test_mode:
      name: test_mode
      in: query
      description: 'Filter by test mode'
      schema:
        type: boolean
    subscription_status:
      name: status
      in: query
      description: 'Filter subscriptions by status'
      schema:
        type: string
        enum:
          - active
          - canceled
          - delinquent
          - completed
          - paused
          - invalid_processor
          - sca_required
          - deleted
    product_status:
      name: status
      in: query
      description: 'Filter product by status'
      schema:
        type: string
        enum:
          - live
          - test
          - archived
    subscription_type:
      name: type
      in: query
      description: 'Filter subscriptions by type'
      schema:
        type: string
        enum:
          - limited_subscription
          - recurring_subscription
    product_category:
      name: product_category
      in: query
      description: 'Filter product by category'
      schema:
        type: string
        enum:
          - physical
          - digital
    pricing_type:
      name: pricing_type
      in: query
      description: 'Filter product by pricing type'
      schema:
        type: string
        enum:
          - one_time
          - limited_subscription
          - recurring_subscription
          - pwyw_one_time
          - pwyw_recurring_subscription
          - pwyw_limited_subscription
    charge_id:
      name: id
      in: path
      description: 'The SamCart ID for the charge'
      required: true
      schema:
        type: integer
    refund_id:
      name: refund_id
      in: path
      description: 'The SamCart ID for the refund'
      required: true
      schema:
        type: integer
    order_id:
      name: id
      in: path
      description: 'The SamCart ID for the order'
      required: true
      schema:
        type: integer
    subscription_id:
      name: id
      in: path
      description: 'The SamCart ID for the subscription'
      required: true
      schema:
        type: integer
    product_id:
      name: id
      in: path
      description: 'The SamCart ID for the product'
      required: true
      schema:
        type: integer
    customer_email:
      name: email
      in: query
      description: 'Filter customers by email address (case-insensitive, exact match). Accepts a single email or multiple comma-separated emails (maximum 25).'
      schema:
        type: string
      example: jdoe@gmail.com
    customer_id:
      name: id
      in: path
      description: 'The SamCart ID for the customer'
      required: true
      schema:
        type: integer
    pagination_offset:
      name: offset
      in: query
      description: 'The offset value used to paginate through a list of entries. If the dir query parameter is prev then the offset will be the id of the first record of the data set otherwise the offset will be the id of the last record'
      schema:
        type: integer
      example: 100
    pagination_limit:
      name: limit
      in: query
      description: 'An optional limit for the number of entries on a page with a maximum value of 100. Default value is 100 if not provided.'
      schema:
        type: integer
        maximum: 100
      example: 100
    pagination_direction:
      name: dir
      in: query
      description: 'The direction to paginate the next set of data. If dir is prev the page will return a data set before the offset otherwise the data set will be after the offset. Default value is next if not provided.'
      schema:
        type: string
        enum:
          - next
          - prev
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      name: sc-api
      in: header
tags:
  -
    name: Orders
    description: Orders
  -
    name: Charges
    description: Charges
  -
    name: Customers
    description: Customers
  -
    name: 'Failed Charges'
    description: 'Failed Charges'
  -
    name: Funnels
    description: Funnels
  -
    name: Products
    description: Products
  -
    name: Refunds
    description: Refunds
  -
    name: Subscriptions
    description: Subscriptions
  -
    name: Upsells
    description: Upsells
