VTEX Subscriptions API

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 Specification

vtex-subscriptions-openapi-original.yml Raw ↑
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![image](https://user-images.githubusercontent.com/77292838/213024675-9407863b-0c55-4282-9442-306352716abe.png)\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