Subbly Products API
Storefront products and bundles (modeled from the SDK).
OpenAPI Specification
openapi: 3.0.3
info:
title: Subbly Storefront API (Modeled) Cart Products API
description: MODELED OpenAPI for Subbly's storefront developer surface. Subbly is a subscription-first commerce platform. Its documented developer tools are the client-side SubblyCart.js cart widget and the Subbly.js SDK (@subbly/sdk), which call Subbly's REST backend to manage products, bundles, carts, checkout, customers, and subscriptions. Subbly does NOT publish concrete REST endpoint paths, a base API host, or an official OpenAPI definition - the SDK abstracts them. The paths and schemas below are therefore MODELED from the documented SDK operations to give the catalog a workable shape; they are illustrative and are not an official Subbly REST contract. The public Orders API (3PL integration) is documented by Subbly on request and is not modeled here, and Subbly's webhooks are configured in the admin without a published payload schema. Authentication for the storefront SDK uses an apiKey issued in the Subbly admin (Shop Settings), optionally with a per-customer access token.
version: 0.1.0-modeled
contact:
name: Subbly Developers
url: https://www.subbly.dev/
servers:
- url: https://api.subbly.example/v1
description: Modeled placeholder base URL. Subbly does not publish its REST API host; the Subbly.js SDK resolves the real host internally. Do not treat this as a live endpoint.
security:
- apiKey: []
tags:
- name: Products
description: Storefront products and bundles (modeled from the SDK).
paths:
/products:
get:
operationId: listProducts
tags:
- Products
summary: List products
description: Lists storefront products. Modeled from the Subbly.js SDK products methods.
responses:
'200':
description: A list of products.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Product'
'401':
$ref: '#/components/responses/Unauthorized'
/products/{id}:
parameters:
- $ref: '#/components/parameters/Id'
get:
operationId: getProduct
tags:
- Products
summary: Get a product
description: Retrieves a product (including parent products / variants). Modeled from the SDK.
responses:
'200':
description: The requested product.
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
'404':
$ref: '#/components/responses/NotFound'
/products/{id}/variants:
parameters:
- $ref: '#/components/parameters/Id'
get:
operationId: listProductVariants
tags:
- Products
summary: List product variants
description: Lists the variants of a product. Modeled from the SDK.
responses:
'200':
description: A list of variants.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Product'
/bundles:
get:
operationId: listBundles
tags:
- Products
summary: List bundles
description: Lists bundle products. Modeled from the SDK bundle methods.
responses:
'200':
description: A list of bundles.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Bundle'
/bundles/{id}/items:
parameters:
- $ref: '#/components/parameters/Id'
get:
operationId: getBundleItems
tags:
- Products
summary: Get bundle items
description: Retrieves the items available for a bundle. Modeled from the SDK.
responses:
'200':
description: Bundle items.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Product'
/bundles/{id}/quote:
parameters:
- $ref: '#/components/parameters/Id'
post:
operationId: quoteBundle
tags:
- Products
summary: Generate a bundle quote
description: Generates a price quote for a configured bundle. Modeled from the SDK.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BundleQuoteInput'
responses:
'200':
description: The bundle quote.
content:
application/json:
schema:
$ref: '#/components/schemas/Quote'
components:
responses:
Unauthorized:
description: Missing or invalid API key / access token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Bundle:
type: object
description: A bundle product (modeled).
properties:
id:
type: string
name:
type: string
minItems:
type: integer
maxItems:
type: integer
Quote:
type: object
description: A computed price quote (modeled).
properties:
total:
type: integer
currency:
type: string
BundleQuoteInput:
type: object
description: Selected items to quote for a bundle (modeled).
properties:
items:
type: array
items:
type: object
properties:
productId:
type: string
quantity:
type: integer
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
Product:
type: object
description: A storefront product or variant (modeled).
properties:
id:
type: string
name:
type: string
type:
type: string
description: For example one_time or subscription.
price:
type: integer
description: Price in the smallest currency unit.
currency:
type: string
parameters:
Id:
name: id
in: path
required: true
description: The resource identifier.
schema:
type: string
securitySchemes:
apiKey:
type: apiKey
in: header
name: X-Subbly-Api-Key
description: Modeled. Subbly's storefront SDK is configured with an apiKey issued in the Subbly admin (Shop Settings). The exact header/parameter name is not published by Subbly.