Query subscriptions by customer email, status (ACTIVE, PAUSED, CANCELLED), and created date, retrieve a subscription by ID, and manage the subscription lifecycle - cancel, change frequency, update and remove line items, set the shipping address, add order notes, and attach metadata.
openapi: 3.1.0
info:
title: Stay AI API
version: '2.0'
description: >-
Documented public REST API for Stay AI (formerly Retextion), a subscription
retention and growth platform for Shopify DTC brands. All endpoints are
authenticated with an API key sent in the X-RETEXTION-ACCESS-TOKEN header.
Paths, methods, and query/path parameters are taken from the Stay AI
developer documentation at https://docs.stay.ai; request and response body
schemas are simplified representations - consult the live reference for full
payload details.
contact:
name: Stay AI
url: https://docs.stay.ai
servers:
- url: https://api.retextion.com/api/v2
components:
securitySchemes:
accessToken:
type: apiKey
in: header
name: X-RETEXTION-ACCESS-TOKEN
schemas:
Success:
type: object
properties:
success:
type: boolean
security:
- accessToken: []
paths:
/subscriptions:
get:
operationId: query-all-subscriptions
summary: Query All Subscriptions
tags:
- Subscriptions
parameters:
- name: email
in: query
description: Customer email
schema:
type: string
- name: status
in: query
description: Subscription status (ACTIVE or PAUSED or CANCELLED)
schema:
type: string
- name: createdAtMin
in: query
description: Created date min timestamp
schema:
type: integer
format: int64
- name: createdAtMax
in: query
description: Created date max timestamp
schema:
type: integer
format: int64
responses:
'200':
description: A list of subscriptions
/subscriptions/{subscriptionId}:
get:
operationId: query-subscription-by-id
summary: Query Subscription by ID
tags:
- Subscriptions
parameters:
- name: subscriptionId
in: path
required: true
description: Internal or external subscription ID
schema:
type: string
responses:
'200':
description: The requested subscription
/subscriptions/{subscriptionId}/cancel:
post:
operationId: cancel-subscription
summary: Cancel Subscription
tags:
- Subscriptions
parameters:
- name: subscriptionId
in: path
required: true
description: Internal or external subscription ID
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
cancellationReasons:
type: array
description: A list of reasons for cancellation of the subscription
items:
type: string
responses:
'200':
description: Cancellation result
content:
application/json:
schema:
$ref: '#/components/schemas/Success'
/subscriptions/{subscriptionId}/change-frequency:
post:
operationId: change-frequency
summary: Change Frequency
tags:
- Subscriptions
parameters:
- name: subscriptionId
in: path
required: true
description: Internal or external subscription ID
schema:
type: string
responses:
'200':
description: Frequency updated
content:
application/json:
schema:
$ref: '#/components/schemas/Success'
/subscriptions/{subscriptionId}/get-order-now:
post:
operationId: create-subscription-order
summary: Create Subscription Order
description: Initiates a new recurring charge for a single subscription.
tags:
- Orders
parameters:
- name: subscriptionId
in: path
required: true
description: Internal or external subscription ID
schema:
type: string
responses:
'200':
description: Order created
content:
application/json:
schema:
$ref: '#/components/schemas/Success'
/subscriptions/{subscriptionId}/lines/{lineId}:
put:
operationId: update-line
summary: Update Line
tags:
- Subscriptions
parameters:
- name: subscriptionId
in: path
required: true
schema:
type: string
- name: lineId
in: path
required: true
schema:
type: string
responses:
'200':
description: Line item updated
/subscriptions/{subscriptionId}/remove-lines:
post:
operationId: remove-lines
summary: Remove Lines
tags:
- Subscriptions
parameters:
- name: subscriptionId
in: path
required: true
schema:
type: string
responses:
'200':
description: Line items removed
/subscriptions/{subscriptionId}/order-notes:
put:
operationId: update-order-notes
summary: Update Order Notes
tags:
- Subscriptions
parameters:
- name: subscriptionId
in: path
required: true
schema:
type: string
responses:
'200':
description: Order notes updated
/subscriptions/{subscriptionId}/meta-data:
post:
operationId: add-meta-data
summary: Add Meta Data Field
tags:
- Subscriptions
parameters:
- name: subscriptionId
in: path
required: true
schema:
type: string
responses:
'200':
description: Metadata field added
/subscriptions/{subscriptionId}/set-shipping-address:
post:
operationId: set-shipping-address
summary: Set Shipping Address
tags:
- Subscriptions
parameters:
- name: subscriptionId
in: path
required: true
schema:
type: string
responses:
'200':
description: Shipping address updated
/subscriptions/generate-portal-link:
post:
operationId: generate-portal-link
summary: Generate Portal Link
tags:
- Customer Portal
requestBody:
content:
application/json:
schema:
type: object
properties:
email:
type: string
description: Customer email address
phone:
type: string
description: Customer phone number
responses:
'200':
description: A customer portal link
/orders:
get:
operationId: query-orders
summary: Query Orders
tags:
- Orders
parameters:
- name: createdAtMin
in: query
description: Created date min timestamp
schema:
type: integer
format: int64
- name: createdAtMax
in: query
description: Created date max timestamp
schema:
type: integer
format: int64
- name: updatedAtMin
in: query
description: Updated date min timestamp
schema:
type: integer
format: int64
responses:
'200':
description: A list of recurring orders
/selling-plan-groups:
get:
operationId: query-selling-plan-groups
summary: Query Selling Plan Groups
tags:
- Selling Plans
responses:
'200':
description: A list of selling plan groups
post:
operationId: create-selling-plan-group
summary: Create Selling Plan Group
tags:
- Selling Plans
responses:
'200':
description: Selling plan group created
/selling-plan-groups/{sellingPlanGroupId}:
get:
operationId: query-selling-plan-group-by-id
summary: Query Selling Plan Group by ID
tags:
- Selling Plans
parameters:
- name: sellingPlanGroupId
in: path
required: true
schema:
type: string
responses:
'200':
description: The requested selling plan group
put:
operationId: update-selling-plan-group
summary: Update Selling Plan Group
tags:
- Selling Plans
parameters:
- name: sellingPlanGroupId
in: path
required: true
schema:
type: string
responses:
'200':
description: Selling plan group updated
/products/catalog:
get:
operationId: get-catalog
summary: Query Entire Catalog
description: Retrieve the details for the products in your catalog.
tags:
- Catalog
responses:
'200':
description: The product catalog
/products/{productId}:
get:
operationId: get-catalog-product-by-id
summary: Query Product in Catalog
description: Retrieve details for a specific product and its variants from your catalog.
tags:
- Catalog
parameters:
- name: productId
in: path
required: true
description: Shopify Product ID
schema:
type: string
responses:
'200':
description: The requested product and its variants
/settings:
get:
operationId: query-account-settings
summary: Query Account Settings
tags:
- Account
responses:
'200':
description: Merchant account settings
/data/export:
post:
operationId: export-data
summary: Export Data
description: Trigger a bulk data export for subscriptions and orders.
tags:
- Data Export
responses:
'200':
description: Export job accepted
/webhooks:
get:
operationId: get-webhook-subscriptions
summary: Get Webhook Subscriptions
tags:
- Webhooks
responses:
'200':
description: A list of webhook subscriptions
post:
operationId: create-webhook-subscription
summary: Create Webhook Subscription
tags:
- Webhooks
requestBody:
content:
application/json:
schema:
type: object
required:
- event
- url
properties:
event:
type: string
description: >-
Event type to subscribe to, e.g. SUBSCRIPTION,
FAILED_PAYMENT, SUCCESSFUL_PAYMENT.
url:
type: string
description: Destination URL for webhook delivery
responses:
'200':
description: Webhook subscription created
/webhooks/{webhookId}:
delete:
operationId: delete-webhook-subscription
summary: Delete Webhook Subscription
tags:
- Webhooks
parameters:
- name: webhookId
in: path
required: true
schema:
type: string
responses:
'200':
description: Webhook subscription deleted