Work with subscribers, which Smartrr models as customer relationships. List and retrieve customers by Smartrr or Shopify ID, read their payment methods and orders, import customers and payment methods from Shopify, fetch a customer's referral code and link, and add loyalty points.
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.