The VTEX Subscriptions API (v3) manages recurring purchase subscriptions for VTEX stores. It provides lifecycle management for subscription plans, subscriber management, subscription order scheduling, frequency configuration, and subscription address and payment updates.
openapi: 3.0.0
info:
title: VTex Subscriptions API (v3)
description: "\r\nA **Subscription** is a list of items (SKUs) tied to certain recurring purchase settings:\r\n\r\n- User profile\r\n- Address\r\n- Payment method\r\n- Frequency\r\n- Cycle\r\n\r\nOnce you have [configured subscriptions](https://help.vtex.com/tutorial/how-to-configure-subscriptions%20--1FA9dfE7vJqxBna9Nft5Sj) in your store, the Subscriptions API allows you to create, manage and monitor your customers' subscriptions.\r\n\r\n\r\n\r\nTo read more about the Subscriptions feature, check our article [How Subscription works](https://help.vtex.com/tutorial/how-subscriptions-work--frequentlyAskedQuestions_4453)."
contact: {}
version: '1.0'
servers:
- url: https://{accountName}.{environment}.com.br
description: VTEX server URL.
variables:
accountName:
description: Name of the VTEX account. Used as part of the URL.
default: apiexamples
environment:
description: Environment to use. Used as part of the URL.
enum:
- vtexcommercestable
default: vtexcommercestable
paths:
/api/rns/pub/cycles/{cycleId}:
get:
tags:
- Cycles
summary: VTex Get cycle details
description: Retrieve a specific cycle by its ID.
parameters:
- name: cycleId
in: path
description: ID from the desired cycle.
required: true
schema:
type: string
nullable: true
- name: Content-Type
in: header
description: Type of the content being sent.
required: true
style: simple
schema:
type: string
example: application/json
- name: Accept
in: header
description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
example: application/json
responses:
'200':
description: OK
content:
text/plain:
schema:
$ref: '#/components/schemas/SubscriptionCycleResponse'
application/json:
schema:
$ref: '#/components/schemas/SubscriptionCycleResponse'
text/json:
schema:
$ref: '#/components/schemas/SubscriptionCycleResponse'
/api/rns/pub/cycles:
get:
tags:
- Cycles
summary: VTex List cycles
description: List cycles filtering by some arguments.
parameters:
- name: beginDate
in: query
description: Lower limit for the date of creation of the cycle
schema:
type: string
nullable: true
- name: endDate
description: Upper limit for the date of creation of the cycle
in: query
schema:
type: string
nullable: true
- name: subscriptionId
description: Id from the subscription that generated the cycle
in: query
schema:
type: string
nullable: true
- name: customerEmail
in: query
description: Customer that owns the subscription. Defaults to the current logged user
schema:
type: string
nullable: true
- name: status
in: query
description: Current cycle status
schema:
type: string
nullable: true
- name: page
in: query
description: Page used for pagination
schema:
type: integer
format: int32
default: 1
- name: size
in: query
description: Page size used for pagination
schema:
type: integer
format: int32
default: 15
- name: Content-Type
in: header
description: Type of the content being sent.
required: true
style: simple
schema:
type: string
example: application/json
- name: Accept
in: header
description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
example: application/json
responses:
'200':
description: OK
content:
text/plain:
schema:
type: array
items:
$ref: '#/components/schemas/SubscriptionCycleResponse'
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SubscriptionCycleResponse'
text/json:
schema:
type: array
items:
$ref: '#/components/schemas/SubscriptionCycleResponse'
/api/rns/pub/cycles/{cycleId}/retry:
post:
tags:
- Cycles
summary: VTex Retry cycle
description: Every subscription order has an execution count called cycle, which determines the position of an order counting from when the shopper subscribed. This endpoint reruns a cycle that is currently in error state.
parameters:
- name: cycleId
in: path
description: Id from the cycle that will be retried
required: true
schema:
type: string
nullable: true
- name: Content-Type
in: header
description: Type of the content being sent.
required: true
style: simple
schema:
type: string
example: application/json
- name: Accept
in: header
description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
example: application/json
responses:
'200':
description: OK
/api/rns/pvt/plans:
get:
tags:
- Plans
summary: VTex List plans
description: List plans filtering by some arguments.
parameters:
- name: periodicity
in: query
description: Filter plans by available periodicity
schema:
type: string
nullable: true
- name: interval
in: query
description: Filter plans by available interval
schema:
type: string
nullable: true
- name: page
in: query
description: Page used for pagination
schema:
type: integer
format: int32
default: 1
- name: size
in: query
description: Page size used for pagination
schema:
type: integer
format: int32
default: 15
- name: Content-Type
in: header
description: Type of the content being sent.
required: true
style: simple
schema:
type: string
example: application/json
- name: Accept
in: header
description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
example: application/json
responses:
'200':
description: Requested plans
content:
text/plain:
schema:
type: array
items:
$ref: '#/components/schemas/StorePlan'
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/StorePlan'
text/json:
schema:
type: array
items:
$ref: '#/components/schemas/StorePlan'
/api/rns/pvt/plans/{id}:
get:
tags:
- Plans
summary: VTex Get plan details
description: This endpoint retrieves a specific plan by its ID.
parameters:
- name: id
in: path
description: Id from the desired plan
required: true
schema:
type: string
nullable: true
- name: Content-Type
in: header
description: Type of the content being sent.
required: true
style: simple
schema:
type: string
example: application/json
- name: Accept
in: header
description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
example: application/json
responses:
'200':
description: Requested plan
content:
text/plain:
schema:
$ref: '#/components/schemas/StorePlan'
application/json:
schema:
$ref: '#/components/schemas/StorePlan'
text/json:
schema:
$ref: '#/components/schemas/StorePlan'
/api/rns/pvt/reports:
get:
tags:
- Reports
summary: VTex List report templates
description: List all report templates available.
parameters:
- name: Content-Type
in: header
description: Type of the content being sent.
required: true
style: simple
schema:
type: string
example: application/json
- name: Accept
in: header
description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
example: application/json
responses:
'200':
description: Requested report templates
content:
text/plain:
schema:
type: array
items:
$ref: '#/components/schemas/SubscriptionReport'
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SubscriptionReport'
text/json:
schema:
type: array
items:
$ref: '#/components/schemas/SubscriptionReport'
/api/rns/pvt/reports/{reportName}/documents/{documentId}:
get:
tags:
- Reports
summary: VTex Get report document details
description: Retrieve a specific report document by its Id.
parameters:
- name: reportName
in: path
required: true
description: Name of the report
schema:
type: string
nullable: true
- name: documentId
in: path
required: true
description: Id from the desired report document
schema:
type: string
nullable: true
- name: Content-Type
in: header
description: Type of the content being sent.
required: true
style: simple
schema:
type: string
example: application/json
- name: Accept
in: header
description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
example: application/json
responses:
'200':
description: Requested report document
content:
text/plain:
schema:
$ref: '#/components/schemas/ReportResponse'
application/json:
schema:
$ref: '#/components/schemas/ReportResponse'
text/json:
schema:
$ref: '#/components/schemas/ReportResponse'
/api/rns/pvt/reports/{reportName}/documents:
post:
tags:
- Reports
summary: VTex Generate report
description: |-
This endpoint creates a new report in the format of a CSV file and sends it via email. You can generate one of the following reports:
- subscriptionsWithStatus
- subscriptionsScheduledBetweenDate
- subscriptionsUpdatedBetweenDate
- subscriptionsCreatedBetweenDate
- executionsBetweenDate
parameters:
- name: reportName
in: path
required: true
description: |-
Name of the type of report in wish to generate. The following values are accepted:
- `subscriptionsWithStatus`
- `subscriptionsScheduledBetweenDate`
- `subscriptionsUpdatedBetweenDate`
- `subscriptionsCreatedBetweenDate`
- `executionsBetweenDate`
schema:
type: string
nullable: true
- name: email
in: query
description: The report is sent to the email in this field.
schema:
type: string
nullable: false
default: [email protected]
- name: beginDate
in: query
description: Start date of the report with the format `yyyy-mm-dd`. This field is required for any type of report.
schema:
type: string
default: '2022-09-01'
- name: endDate
in: query
description: End date of the report with the format `yyyy-mm-dd`. This field is required for any type of report.
schema:
type: string
default: '2022-10-01'
- name: Content-Type
in: header
description: Type of the content being sent.
required: true
style: simple
schema:
type: string
example: application/json
- name: Accept
in: header
description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
example: application/json
responses:
'200':
description: Requested report
content:
text/plain:
schema:
$ref: '#/components/schemas/ReportResponse'
application/json:
schema:
$ref: '#/components/schemas/ReportResponse'
text/json:
schema:
$ref: '#/components/schemas/ReportResponse'
/api/rns/pub/subscriptions/{id}:
get:
tags:
- Subscriptions
summary: VTex Get subscription details
description: Retrieve a specific subscription by its ID.
parameters:
- name: id
in: path
required: true
description: ID from the target subscription.
schema:
type: string
nullable: true
- name: Content-Type
in: header
description: Type of the content being sent.
required: true
style: simple
schema:
type: string
example: application/json
- name: Accept
in: header
description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
example: application/json
responses:
'200':
description: Requested subscription
content:
text/plain:
schema:
$ref: '#/components/schemas/SubscriptionGroupResponse'
application/json:
schema:
$ref: '#/components/schemas/SubscriptionGroupResponse'
text/json:
schema:
$ref: '#/components/schemas/SubscriptionGroupResponse'
patch:
tags:
- Subscriptions
summary: VTex Update subscription
description: Update a specific subscription.
parameters:
- name: id
in: path
required: true
description: ID from the given subscription.
schema:
type: string
example: '4002961'
nullable: false
- name: Content-Type
in: header
description: Type of the content being sent.
required: true
style: simple
schema:
type: string
example: application/json
- name: Accept
in: header
description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
example: application/json
requestBody:
content:
application/json-patch+json:
schema:
$ref: '#/components/schemas/SubscriptionUpdateRequestV3'
application/json:
schema:
$ref: '#/components/schemas/SubscriptionUpdateRequestV3'
text/json:
schema:
$ref: '#/components/schemas/SubscriptionUpdateRequestV3'
application/*+json:
schema:
$ref: '#/components/schemas/SubscriptionUpdateRequestV3'
responses:
'200':
description: Subscription successfully updated
content:
text/plain:
schema:
$ref: '#/components/schemas/SubscriptionGroupResponse'
application/json:
schema:
$ref: '#/components/schemas/SubscriptionGroupResponse'
text/json:
schema:
$ref: '#/components/schemas/SubscriptionGroupResponse'
/api/rns/pub/subscriptions:
get:
tags:
- Subscriptions
summary: VTex List subscriptions
description: List subscriptions filtering by some arguments.
parameters:
- name: customerEmail
in: query
description: Customer that owns the subscription. Defaults to the current logged user.
schema:
type: string
nullable: true
- name: status
in: query
description: Current subscription status
schema:
type: string
nullable: true
- name: addressId
in: query
description: Id from the address used as shipping address
schema:
type: string
nullable: true
- name: paymentId
in: query
description: Id from the payment used as payment method
schema:
type: string
nullable: true
- name: planId
in: query
description: Id from the plan that the subscription belongs to
schema:
type: string
nullable: true
- name: nextPurchaseDate
in: query
description: Date for the next cycle
schema:
type: string
nullable: true
- name: originalOrderId
in: query
description: Id from the order that generated the subscription
schema:
type: string
nullable: true
- name: page
in: query
description: Page used for pagination
schema:
type: integer
format: int32
default: 1
- name: size
in: query
description: Page size used for pagination
schema:
type: integer
format: int32
default: 15
- name: Content-Type
in: header
description: Type of the content being sent.
required: true
style: simple
schema:
type: string
example: application/json
- name: Accept
in: header
description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
example: application/json
responses:
'200':
description: Requested subscriptions
content:
text/plain:
schema:
type: array
items:
$ref: '#/components/schemas/SubscriptionGroupResponse'
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SubscriptionGroupResponse'
text/json:
schema:
type: array
items:
$ref: '#/components/schemas/SubscriptionGroupResponse'
post:
tags:
- Subscriptions
summary: VTex Create subscription
description: Create a new subscription.
parameters:
- name: Content-Type
in: header
description: Type of the content being sent.
required: true
style: simple
schema:
type: string
example: application/json
- name: Accept
in: header
description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
example: application/json
requestBody:
content:
application/json-patch+json:
schema:
$ref: '#/components/schemas/SubscriptionGroupRequest'
application/json:
schema:
$ref: '#/components/schemas/SubscriptionGroupRequest'
text/json:
schema:
$ref: '#/components/schemas/SubscriptionGroupRequest'
application/*+json:
schema:
$ref: '#/components/schemas/SubscriptionGroupRequest'
responses:
'201':
description: Subscription created
content:
text/plain:
schema:
$ref: '#/components/schemas/SubscriptionGroupResponse'
application/json:
schema:
$ref: '#/components/schemas/SubscriptionGroupResponse'
text/json:
schema:
$ref: '#/components/schemas/SubscriptionGroupResponse'
/api/rns/pub/subscriptions/{id}/items/{itemId}:
delete:
tags:
- Subscriptions
summary: VTex Remove items from a subscription.
description: Removes a specific item from a given subscription
parameters:
- name: id
in: path
description: Id from the target subscription
required: true
schema:
type: string
nullable: true
- name: itemId
in: path
description: Id from the subscription item that will be removed
required: true
schema:
type: string
nullable: true
- name: Content-Type
in: header
description: Type of the content being sent.
required: true
style: simple
schema:
type: string
example: application/json
- name: Accept
in: header
description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
example: application/json
responses:
'200':
description: Success
patch:
tags:
- Subscriptions
summary: VTex Edit items on a subscription.
description: Edit a given item on a specific subscription
parameters:
- name: id
in: path
required: true
description: Id from the target subscription
schema:
type: string
nullable: true
- name: itemId
in: path
required: true
description: Id from the target item
schema:
type: string
nullable: true
- name: Content-Type
in: header
description: Type of the content being sent.
required: true
style: simple
schema:
type: string
example: application/json
- name: Accept
in: header
description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
example: application/json
requestBody:
content:
application/json-patch+json:
schema:
$ref: '#/components/schemas/UpdateItemInput'
application/json:
schema:
$ref: '#/components/schemas/UpdateItemInput'
text/json:
schema:
$ref: '#/components/schemas/UpdateItemInput'
application/*+json:
schema:
$ref: '#/components/schemas/UpdateItemInput'
responses:
'200':
description: Subscription updated
content:
text/plain:
schema:
$ref: '#/components/schemas/SubscriptionGroupResponse'
application/json:
schema:
$ref: '#/components/schemas/SubscriptionGroupResponse'
text/json:
schema:
$ref: '#/components/schemas/SubscriptionGroupResponse'
/api/rns/pub/subscriptions/{id}/items:
post:
tags:
- Subscriptions
summary: VTex Add item to subscription
description: Add a new item to a given subscription.
parameters:
- name: id
in: path
description: ID from the target subscription
required: true
schema:
type: string
nullable: true
- name: Content-Type
in: header
description: Type of the content being sent.
required: true
style: simple
schema:
type: string
example: application/json
- name: Accept
in: header
description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
example: application/json
requestBody:
content:
application/json-patch+json:
schema:
$ref: '#/components/schemas/SubscriptionThinItemRequest'
application/json:
schema:
$ref: '#/components/schemas/SubscriptionThinItemRequest'
text/json:
schema:
$ref: '#/components/schemas/SubscriptionThinItemRequest'
application/*+json:
schema:
$ref: '#/components/schemas/SubscriptionThinItemRequest'
responses:
'200':
description: Subscription successfully updated
content:
text/plain:
schema:
$ref: '#/components/schemas/SubscriptionGroupResponse'
application/json:
schema:
$ref: '#/components/schemas/SubscriptionGroupResponse'
text/json:
schema:
$ref: '#/components/schemas/SubscriptionGroupResponse'
/api/rns/pub/subscriptions/{id}/simulate:
post:
tags:
- Subscriptions
summary: VTex Calculate the current prices for a specific subscription
description: Simulates an order made by the specific subscription on checkout and retrieves the current price for items and shipping.
parameters:
- name: id
in: path
required: true
description: Id from the target subscription
schema:
type: string
nullable: true
- name: Content-Type
in: header
description: Type of the content being sent.
required: true
style: simple
schema:
type: string
example: application/json
- name: Accept
in: header
description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
example: application/json
responses:
'200':
description: Simulation result
content:
text/plain:
schema:
$ref: '#/components/schemas/SimulateResponseVO'
application/json:
schema:
$ref: '#/components/schemas/SimulateResponseVO'
text/json:
schema:
$ref: '#/components/schemas/SimulateResponseVO'
/api/rns/pub/subscriptions/simulate:
post:
tags:
- Subscriptions
summary: VTex Calculate the current prices for the provided subscription template
description: Simulates an order made by subscriptions on checkout and retrieves the current price for items and shipping.
parameters:
- name: Content-Type
in: header
description: Type of the content being sent.
required: true
style: simple
schema:
type: string
example: application/json
- name: Accept
in: header
description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
example: application/json
requestBody:
content:
application/json-patch+json:
schema:
$ref: '#/components/schemas/SubscriptionGroupRequest'
application/json:
schema:
$ref: '#/components/schemas/SubscriptionGroupRequest'
text/json:
schema:
$ref: '#/components/schemas/SubscriptionGroupRequest'
application/*+json:
schema:
$ref: '#/components/schemas/SubscriptionGroupRequest'
responses:
'200':
description: Simulation result
content:
text/plain:
schema:
$ref: '#/components/schemas/SimulateResponseVO'
application/json:
schema:
$ref: '#/components/schemas/SimulateResponseVO'
text/json:
schema:
$ref: '#/components/schemas/SimulateResponseVO'
/api/rns/pub/subscriptions/{subscriptionId}/conversation-message:
get:
tags:
- Subscriptions
summary: VTex Get conversation messages
description: Retrieve all conversation messages sent to a customer regarding a given subscription.
parameters:
- name: subscriptionId
in: path
description: ID of the subscription.
required: true
style: simple
schema:
type: string
default: 123456789abc
- name: Content-Type
in: header
description: Type of the content being sent.
required: true
style: simple
schema:
type: string
example: application/json
- name: Accept
in: header
description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
example: application/json
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vtex/refs/heads/main/openapi/vtex-subscriptions-openapi-original.yml