Build and drive checkout - create and update carts, add / update / remove items, apply coupons and gift cards, set shipping methods and gifting dates, process checkout and purchase, and handle payment intents with 3DS verification. The client-side SubblyCart.js widget (loaded from assets.subbly.co) and the Subbly.js SDK are documented; the server-side REST endpoints they call are not published and are modeled here.
openapi: 3.0.3
info:
title: Subbly Storefront API (Modeled)
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).
- name: Cart
description: Cart and checkout operations (modeled from the SDK and SubblyCart.js).
- name: Customers
description: Customer accounts, addresses, and payment methods (modeled from the SDK).
- name: Subscriptions
description: Customer subscriptions and preferences (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'
/carts:
post:
operationId: createCart
tags:
- Cart
summary: Create a cart
description: Creates a new cart. Modeled from the SDK / SubblyCart.js.
responses:
'201':
description: The created cart.
content:
application/json:
schema:
$ref: '#/components/schemas/Cart'
/carts/{id}:
parameters:
- $ref: '#/components/parameters/Id'
get:
operationId: getCart
tags:
- Cart
summary: Get a cart
description: Loads a cart by ID. Modeled from the SDK.
responses:
'200':
description: The requested cart.
content:
application/json:
schema:
$ref: '#/components/schemas/Cart'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: updateCart
tags:
- Cart
summary: Update a cart
description: Updates a cart (items, coupons, gift cards, shipping method, gifting date). Modeled from the SDK.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CartInput'
responses:
'200':
description: The updated cart.
content:
application/json:
schema:
$ref: '#/components/schemas/Cart'
/carts/{id}/items:
parameters:
- $ref: '#/components/parameters/Id'
post:
operationId: addCartItem
tags:
- Cart
summary: Add a cart item
description: Adds an item to the cart. Modeled from the SDK / SubblyCart.js addItem.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CartItemInput'
responses:
'200':
description: The updated cart.
content:
application/json:
schema:
$ref: '#/components/schemas/Cart'
/checkout:
post:
operationId: checkout
tags:
- Cart
summary: Checkout and purchase
description: >-
Processes checkout and purchase for a cart, including payment intent
handling with 3DS verification. Modeled from the SDK purchase flow.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutInput'
responses:
'200':
description: The resulting order / purchase confirmation.
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
'402':
description: Payment required or requires further (3DS) action.
/customers:
post:
operationId: registerCustomer
tags:
- Customers
summary: Register a customer
description: Registers a new customer. Modeled from the SDK auth methods.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerInput'
responses:
'201':
description: The created customer.
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
/customers/sessions:
post:
operationId: authenticateCustomer
tags:
- Customers
summary: Authenticate a customer
description: >-
Authenticates a customer (password login, OTP, social login) and returns
an access token. Modeled from the SDK auth methods.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AuthInput'
responses:
'200':
description: An access token and customer.
content:
application/json:
schema:
type: object
properties:
accessToken:
type: string
customer:
$ref: '#/components/schemas/Customer'
/customers/{id}:
parameters:
- $ref: '#/components/parameters/Id'
get:
operationId: getCustomer
tags:
- Customers
summary: Get a customer
description: Retrieves a customer profile. Modeled from the SDK.
responses:
'200':
description: The requested customer.
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: updateCustomer
tags:
- Customers
summary: Update a customer
description: Updates a customer profile. Modeled from the SDK.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerInput'
responses:
'200':
description: The updated customer.
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
/customers/{id}/addresses:
parameters:
- $ref: '#/components/parameters/Id'
get:
operationId: listCustomerAddresses
tags:
- Customers
summary: List customer addresses
description: Lists a customer's saved addresses. Modeled from the SDK.
responses:
'200':
description: A list of addresses.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Address'
post:
operationId: createCustomerAddress
tags:
- Customers
summary: Create a customer address
description: Adds a saved address to a customer. Modeled from the SDK.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Address'
responses:
'201':
description: The created address.
content:
application/json:
schema:
$ref: '#/components/schemas/Address'
/customers/{id}/payment-methods:
parameters:
- $ref: '#/components/parameters/Id'
get:
operationId: listCustomerPaymentMethods
tags:
- Customers
summary: List customer payment methods
description: Lists a customer's stored payment methods / wallet. Modeled from the SDK.
responses:
'200':
description: A list of payment methods.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/PaymentMethod'
/subscriptions:
get:
operationId: listSubscriptions
tags:
- Subscriptions
summary: List subscriptions
description: Lists the authenticated customer's subscriptions. Modeled from the SDK.
responses:
'200':
description: A list of subscriptions.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Subscription'
'401':
$ref: '#/components/responses/Unauthorized'
/subscriptions/{id}:
parameters:
- $ref: '#/components/parameters/Id'
get:
operationId: getSubscription
tags:
- Subscriptions
summary: Get a subscription
description: Loads a subscription by ID. Modeled from the SDK.
responses:
'200':
description: The requested subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: updateSubscription
tags:
- Subscriptions
summary: Update a subscription
description: >-
Updates a subscription, including bundle selections and survey /
preference management. Modeled from the SDK.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionInput'
responses:
'200':
description: The updated subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
components:
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.
parameters:
Id:
name: id
in: path
required: true
description: The resource identifier.
schema:
type: string
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:
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
Bundle:
type: object
description: A bundle product (modeled).
properties:
id:
type: string
name:
type: string
minItems:
type: integer
maxItems:
type: integer
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
Quote:
type: object
description: A computed price quote (modeled).
properties:
total:
type: integer
currency:
type: string
Cart:
type: object
description: A shopping cart (modeled).
properties:
id:
type: string
items:
type: array
items:
$ref: '#/components/schemas/CartItemInput'
couponCode:
type: string
giftCardCode:
type: string
shippingMethodId:
type: string
total:
type: integer
currency:
type: string
CartInput:
type: object
description: Updatable cart fields (modeled).
properties:
couponCode:
type: string
giftCardCode:
type: string
shippingMethodId:
type: string
giftingDate:
type: string
format: date
CartItemInput:
type: object
description: A cart line item (modeled).
properties:
productId:
type: string
quantity:
type: integer
CheckoutInput:
type: object
description: Checkout / purchase request (modeled).
properties:
cartId:
type: string
customerId:
type: string
paymentMethodId:
type: string
Order:
type: object
description: A resulting order / purchase (modeled).
properties:
id:
type: string
status:
type: string
total:
type: integer
currency:
type: string
Customer:
type: object
description: A customer account (modeled).
properties:
id:
type: string
email:
type: string
firstName:
type: string
lastName:
type: string
CustomerInput:
type: object
description: Customer create / update fields (modeled).
properties:
email:
type: string
password:
type: string
firstName:
type: string
lastName:
type: string
AuthInput:
type: object
description: Customer authentication request (modeled).
properties:
email:
type: string
password:
type: string
otp:
type: string
provider:
type: string
description: For social login, for example google or facebook.
Address:
type: object
description: A customer address (modeled).
properties:
id:
type: string
line1:
type: string
line2:
type: string
city:
type: string
region:
type: string
postalCode:
type: string
country:
type: string
PaymentMethod:
type: object
description: A stored payment method / wallet entry (modeled).
properties:
id:
type: string
brand:
type: string
last4:
type: string
expMonth:
type: integer
expYear:
type: integer
Subscription:
type: object
description: A customer subscription (modeled).
properties:
id:
type: string
status:
type: string
productId:
type: string
nextBillingDate:
type: string
format: date
interval:
type: string
SubscriptionInput:
type: object
description: Subscription update fields (modeled).
properties:
status:
type: string
bundleSelections:
type: array
items:
type: object
properties:
productId:
type: string
quantity:
type: integer
surveyAnswers:
type: object
additionalProperties: true
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string