List and retrieve the orders subscriptions generate, open and close orders, and manage the recurring bills (subscription transactions) behind them - read bills, inspect a bill's audit history, and retry or cancel bills individually or in bulk.
openapi: 3.0.3
info:
title: Smartrr Vendor API
description: >-
The Smartrr Vendor API is the programmatic surface behind Smartrr, a
subscription and loyalty platform for Shopify DTC brands. It lets a merchant
(vendor) read and manage the subscriptions ("purchase states") their
customers hold, the customers (subscribers) themselves, the orders and bills
those subscriptions generate, and the subscription programs / selling plans
that products are sold on. All requests are made against
https://api.smartrr.com and are authenticated with a per-organization API
access token generated in the Smartrr admin under the Integrations tab and
sent in the x-smartrr-access-token header. This description is authored by
API Evangelist from Smartrr's public OpenAPI document served at
https://api.smartrr.com/docs/spec.json (rendered at
https://api.smartrr.com/docs/redoc/); it is a curated subset of the full
116-operation surface covering the core Subscriptions, Subscribers, Orders,
Bills, Plans, and Webhooks resources. Endpoint paths and methods are taken
directly from that live specification; request and response bodies are
summarized.
version: '1.0.0'
contact:
name: Smartrr
url: https://smartrr.com
servers:
- url: https://api.smartrr.com
description: Smartrr production
security:
- smartrrAccessToken: []
tags:
- name: Subscriptions
description: >-
Customer subscriptions, modeled by Smartrr as "purchase states". Create,
read, and manage the lifecycle (skip, pause, cancel, reschedule, swap
line items) of a subscription.
- name: Subscribers
description: >-
Customer relationships (subscribers) - the Shopify customers who hold
subscriptions, their payment methods, loyalty points, and referral links.
- name: Orders
description: Orders generated by subscriptions.
- name: Bills
description: Recurring bills (subscription transactions) and their retry / cancel lifecycle.
- name: Plans
description: >-
Purchasables, selling plans, selling plan groups and subscription
programs - the products and the terms they are sold on.
- name: Webhooks
description: Register endpoints to receive Smartrr event notifications.
paths:
/vendor/purchase-state:
get:
tags: [Subscriptions]
summary: Get Purchase States
description: List subscriptions (purchase states) for the organization, with pagination and filtering.
operationId: getPurchaseStates
parameters:
- name: pageNumber
in: query
schema: { type: integer }
- name: pageSize
in: query
schema: { type: integer }
responses:
'200':
description: A paginated list of purchase states.
post:
tags: [Subscriptions]
summary: Create Purchase State
description: Create a new subscription (purchase state) for a customer.
operationId: createPurchaseState
requestBody:
required: true
content:
application/json:
schema:
type: object
description: Purchase state creation payload (customer, line items, selling plan, next billing date).
responses:
'201':
description: The created purchase state.
/vendor/purchase-state/{shopifySubscriptionId}:
get:
tags: [Subscriptions]
summary: Get Purchase State By Shopify Subscription ID
operationId: getPurchaseStateByShopifyId
parameters:
- name: shopifySubscriptionId
in: path
required: true
schema: { type: string }
responses:
'200':
description: A single purchase state.
/vendor/purchase-state/{shopifySubscriptionId}/orders:
get:
tags: [Subscriptions]
summary: Get Orders By Shopify Subscription ID
operationId: getPurchaseStateOrders
parameters:
- name: shopifySubscriptionId
in: path
required: true
schema: { type: string }
responses:
'200':
description: Orders associated with the subscription.
/vendor/purchase-state/{shopifySubscriptionId}/bills:
get:
tags: [Subscriptions]
summary: Get Bills By Shopify Subscription ID
operationId: getPurchaseStateBills
parameters:
- name: shopifySubscriptionId
in: path
required: true
schema: { type: string }
responses:
'200':
description: Bills associated with the subscription.
/vendor/purchase-state/{shopifySubscriptionId}/events:
get:
tags: [Subscriptions]
summary: Get Events by Shopify Subscription ID
description: Returns up to 250 most recent events for the subscription.
operationId: getPurchaseStateEvents
parameters:
- name: shopifySubscriptionId
in: path
required: true
schema: { type: string }
responses:
'200':
description: Recent subscription events.
/vendor/customer/{customerRelationshipId}/purchase-state/:
get:
tags: [Subscriptions]
summary: Get Purchase States By Customer ID
operationId: getPurchaseStatesByCustomer
parameters:
- name: customerRelationshipId
in: path
required: true
schema: { type: string }
responses:
'200':
description: The customer's purchase states.
/vendor/customer/{customerRelationshipId}/purchase-state/{customerPurchaseStateId}/skip:
put:
tags: [Subscriptions]
summary: Skip Purchase
description: Skip the next order on a subscription.
operationId: skipPurchase
parameters:
- name: customerRelationshipId
in: path
required: true
schema: { type: string }
- name: customerPurchaseStateId
in: path
required: true
schema: { type: string }
responses:
'200':
description: The updated purchase state.
/vendor/customer/{customerRelationshipId}/purchase-state/{customerPurchaseStateId}/unskip:
put:
tags: [Subscriptions]
summary: Unskip Purchase
operationId: unskipPurchase
parameters:
- name: customerRelationshipId
in: path
required: true
schema: { type: string }
- name: customerPurchaseStateId
in: path
required: true
schema: { type: string }
responses:
'200':
description: The updated purchase state.
/vendor/customer/{customerRelationshipId}/purchase-state/{customerPurchaseStateId}/pause:
put:
tags: [Subscriptions]
summary: Pause Purchase
operationId: pausePurchase
parameters:
- name: customerRelationshipId
in: path
required: true
schema: { type: string }
- name: customerPurchaseStateId
in: path
required: true
schema: { type: string }
requestBody:
content:
application/json:
schema:
type: object
properties:
unpauseDate:
type: string
description: Optional date to automatically resume the subscription.
responses:
'200':
description: The updated purchase state.
/vendor/customer/{customerRelationshipId}/purchase-state/{customerPurchaseStateId}/activate:
put:
tags: [Subscriptions]
summary: Activate Purchase
description: Resume / activate a paused subscription.
operationId: activatePurchase
parameters:
- name: customerRelationshipId
in: path
required: true
schema: { type: string }
- name: customerPurchaseStateId
in: path
required: true
schema: { type: string }
responses:
'200':
description: The updated purchase state.
/vendor/customer/{customerRelationshipId}/purchase-state/{customerPurchaseStateId}/cancel:
put:
tags: [Subscriptions]
summary: Cancel Purchase
operationId: cancelPurchase
parameters:
- name: customerRelationshipId
in: path
required: true
schema: { type: string }
- name: customerPurchaseStateId
in: path
required: true
schema: { type: string }
responses:
'200':
description: The cancelled purchase state.
/vendor/customer/{customerRelationshipId}/purchase-state/{customerPurchaseStateId}/next-billing-date:
put:
tags: [Subscriptions]
summary: Set Next Billing Date on Purchase
operationId: setNextBillingDate
parameters:
- name: customerRelationshipId
in: path
required: true
schema: { type: string }
- name: customerPurchaseStateId
in: path
required: true
schema: { type: string }
responses:
'200':
description: The updated purchase state.
/vendor/customer/{customerRelationshipId}/purchase-state/{customerPurchaseStateId}/selling-plan:
put:
tags: [Subscriptions]
summary: Set Selling Plan on Purchase
description: Change the selling plan (cadence / terms) a subscription is on.
operationId: setSellingPlanOnPurchase
parameters:
- name: customerRelationshipId
in: path
required: true
schema: { type: string }
- name: customerPurchaseStateId
in: path
required: true
schema: { type: string }
responses:
'200':
description: The updated purchase state.
/vendor/customer/{customerRelationshipId}/purchase-state/{customerPurchaseStateId}/line-item:
post:
tags: [Subscriptions]
summary: Add Line Item to Purchase
operationId: addLineItem
parameters:
- name: customerRelationshipId
in: path
required: true
schema: { type: string }
- name: customerPurchaseStateId
in: path
required: true
schema: { type: string }
responses:
'200':
description: The updated purchase state.
/vendor/customer/purchase-state/bulk-cancel:
put:
tags: [Subscriptions]
summary: Bulk Cancel Purchases
operationId: bulkCancelPurchases
responses:
'200':
description: Bulk cancel result.
/vendor/customer/purchase-state/bulk-pause:
put:
tags: [Subscriptions]
summary: Bulk Pause Purchases
operationId: bulkPausePurchases
responses:
'200':
description: Bulk pause result.
/vendor/customer-relationship:
get:
tags: [Subscribers]
summary: Get Customer Relationship
description: List subscribers (customer relationships) for the organization.
operationId: getCustomerRelationships
responses:
'200':
description: A paginated list of customer relationships.
/vendor/customer-relationship/{customerShopifyId}:
get:
tags: [Subscribers]
summary: Get Customer Relationship by Shopify ID
operationId: getCustomerRelationshipByShopifyId
parameters:
- name: customerShopifyId
in: path
required: true
schema: { type: string }
responses:
'200':
description: A single customer relationship.
/vendor/customer-relationship/{customerRelationshipId}/payment-methods:
get:
tags: [Subscribers]
summary: Get Payment methods
operationId: getPaymentMethods
parameters:
- name: customerRelationshipId
in: path
required: true
schema: { type: string }
responses:
'200':
description: The customer's payment methods.
/vendor/customer-relationship/{customerShopifyId}/referral-link:
get:
tags: [Subscribers]
summary: Get customer referral code and link
operationId: getReferralLink
parameters:
- name: customerShopifyId
in: path
required: true
schema: { type: string }
responses:
'200':
description: The customer's referral code and link.
/vendor/customer-relationship/{customerRelationshipId}/orgPoints:
put:
tags: [Subscribers]
summary: Add loyalty points to customer
operationId: addLoyaltyPoints
parameters:
- name: customerRelationshipId
in: path
required: true
schema: { type: string }
responses:
'200':
description: The updated loyalty points balance.
/vendor/customer-relationship/import:
post:
tags: [Subscribers]
summary: Import Customer Relationship from Shopify Customer
operationId: importCustomerRelationship
responses:
'200':
description: The imported customer relationship.
/vendor/customer/{custRelId}/orders:
get:
tags: [Subscribers]
summary: Get Orders by customer ID
operationId: getOrdersByCustomer
parameters:
- name: custRelId
in: path
required: true
schema: { type: string }
responses:
'200':
description: Orders for the customer.
/vendor/order:
get:
tags: [Orders]
summary: Get Orders
operationId: getOrders
parameters:
- name: pageNumber
in: query
schema: { type: integer }
- name: pageSize
in: query
schema: { type: integer }
responses:
'200':
description: A paginated list of orders.
/vendor/order/formatted:
get:
tags: [Orders]
summary: Get Formatted Orders
operationId: getFormattedOrders
responses:
'200':
description: Formatted orders.
/vendor/orders/{shopifyId}:
get:
tags: [Orders]
summary: Get Order by Shopify order ID
operationId: getOrderByShopifyId
parameters:
- name: shopifyId
in: path
required: true
schema: { type: string }
responses:
'200':
description: A single order.
/vendor/order/{orderId}/open:
post:
tags: [Orders]
summary: Open Order
operationId: openOrder
parameters:
- name: orderId
in: path
required: true
schema: { type: string }
responses:
'200':
description: The opened order.
/vendor/order/{orderId}:
delete:
tags: [Orders]
summary: Close Order
operationId: closeOrder
parameters:
- name: orderId
in: path
required: true
schema: { type: string }
responses:
'200':
description: The closed order.
/vendor/bill:
get:
tags: [Bills]
summary: Get Bills
operationId: getBills
responses:
'200':
description: A paginated list of bills (subscription transactions).
/vendor/bill/{billId}/history:
get:
tags: [Bills]
summary: Gets bill audit history
operationId: getBillHistory
parameters:
- name: billId
in: path
required: true
schema: { type: string }
responses:
'200':
description: The bill's audit history.
/vendor/bill/{billId}/retry:
post:
tags: [Bills]
summary: Retry a bill
operationId: retryBill
parameters:
- name: billId
in: path
required: true
schema: { type: string }
responses:
'200':
description: The retried bill.
/vendor/bill/{billId}/cancel:
post:
tags: [Bills]
summary: Cancels a bill
operationId: cancelBill
parameters:
- name: billId
in: path
required: true
schema: { type: string }
responses:
'200':
description: The cancelled bill.
/vendor/purchasable:
get:
tags: [Plans]
summary: Get Purchasables
description: List purchasable products available for subscription.
operationId: getPurchasables
responses:
'200':
description: A list of purchasables.
put:
tags: [Plans]
summary: Update Purchasable
operationId: updatePurchasable
requestBody:
content:
application/json:
schema:
type: object
properties:
purchasable:
type: object
responses:
'200':
description: The updated purchasable.
/vendor/purchasable/{id}:
get:
tags: [Plans]
summary: Get Purchasable by ID
operationId: getPurchasableById
parameters:
- name: id
in: path
required: true
schema: { type: string }
responses:
'200':
description: A single purchasable.
/vendor/purchasable-collection:
get:
tags: [Plans]
summary: Get Purchasable Collection
operationId: getPurchasableCollection
responses:
'200':
description: A list of purchasable collections.
/vendor/selling-plan-group:
get:
tags: [Plans]
summary: Get Selling Plan Groups
operationId: getSellingPlanGroups
responses:
'200':
description: The shop's selling plan groups.
/vendor/selling-plan-configs:
get:
tags: [Plans]
summary: Get all programs for a shop
operationId: getSellingPlanConfigs
responses:
'200':
description: The shop's subscription programs.
/vendor/webhook:
get:
tags: [Webhooks]
summary: Get webhooks for current organization
operationId: getWebhooks
responses:
'200':
description: The organization's webhooks.
post:
tags: [Webhooks]
summary: Create a new webhook
operationId: createWebhook
requestBody:
required: true
content:
application/json:
schema:
type: object
description: Webhook creation payload (topic, delivery URL).
responses:
'201':
description: The created webhook.
/vendor/webhook/{webhookId}:
put:
tags: [Webhooks]
summary: Edit existing webhook
operationId: editWebhook
parameters:
- name: webhookId
in: path
required: true
schema: { type: string }
responses:
'200':
description: The updated webhook.
delete:
tags: [Webhooks]
summary: Delete existing webhook
operationId: deleteWebhook
parameters:
- name: webhookId
in: path
required: true
schema: { type: string }
responses:
'200':
description: The webhook was deleted.
components:
securitySchemes:
smartrrAccessToken:
type: apiKey
in: header
name: x-smartrr-access-token
description: >-
Per-organization API access token generated in the Smartrr admin under
the Integrations tab (Add Key). Sent on every request in the
x-smartrr-access-token header.