VTEX Subscriptions API

openapi: 3.2.0
info:
  title: VTex API (v3) Subscriptions API
  description: '

    A **Subscription** is a list of items (SKUs) tied to certain recurring purchase settings:


    - User profile

    - Address

    - Payment method

    - Frequency

    - Cycle


    Once 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.


    ![image](https://user-images.githubusercontent.com/77292838/213024675-9407863b-0c55-4282-9442-306352716abe.png)


    To 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
security:
- appKey: []
  appToken: []
tags:
- name: Subscriptions
paths:
  /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
          - 'null'
      - 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'
      - 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
          - 'null'
      - name: status
        in: query
        description: Current subscription status
        schema:
          type:
          - string
          - 'null'
      - name: addressId
        in: query
        description: Id from the address used as shipping address
        schema:
          type:
          - string
          - 'null'
      - name: paymentId
        in: query
        description: Id from the payment used as payment method
        schema:
          type:
          - string
          - 'null'
      - name: planId
        in: query
        description: Id from the plan that the subscription belongs to
        schema:
          type:
          - string
          - 'null'
      - name: nextPurchaseDate
        in: query
        description: Date for the next cycle
        schema:
          type:
          - string
          - 'null'
      - name: originalOrderId
        in: query
        description: Id from the order that generated the subscription
        schema:
          type:
          - string
          - 'null'
      - 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
          - 'null'
      - name: itemId
        in: path
        description: Id from the subscription item that will be removed
        required: true
        schema:
          type:
          - string
          - 'null'
      - 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
          - 'null'
      - name: itemId
        in: path
        required: true
        description: Id from the target item
        schema:
          type:
          - string
          - 'null'
      - 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
          - 'null'
      - 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
          - 'null'
      - 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:
                      type: string
                      description: Message ID
                    from:
                      type: object
                      description: Information regarding the message sender.
                      properties:
                        conversationRelatedTo:
                          type: string
                          description: ID of the subscription related to the message.
                        conversationSubject:
                          type: string
                          description: Subject of conversation.
                        emailAlias:
                          type: string
                          description: Email alias.
                        aliasMaskType:
                          type: string
                          description: Alias mask type.
                        email:
                          type: string
                          description: Email address.
                        name:
                          type: string
                          description: Name.
                        role:
                          type: string
                          description: Role.
                    to:
                      type: array
                      description: Information regarding the message receivers.
                      items:
                        type: object
                        properties:
                          conversationRelatedTo:
                            type: string
                            description: ID of the subscription related to the message.
                          conversationSubject:
                            type: string
                            description: Subject of conversation.
                          emailAlias:
                            type: string
                            description: Email alias.
                          aliasMaskType:
                            type: string
                            description: Alias mask type.
                          email:
                            type: string
                            description: Email address.
                          name:
                            type: string
                            description: Name.
                          role:
                            type: string
                            description: Role.
                    subject:
                      type: string
                      description: Message subject.
                    firstWords:
                      type: string
                      description: First words of the message text.
                    body:
                      type: string
                      description: HTML content of the message's body.
                    hasAttachment:
                      type: boolean
                      description: Indicates whether the message has at least one attachment.
                    attachmentNames:
                      type: array
                      description: Attachment names.
                      items:
                        type: string
                    date:
                      type: string
                      description: Date of message.
              example:
              - id: string
                from:
                  conversationRelatedTo: string
                  conversationSubject: string
                  emailAlias: string
                  aliasMaskType: string
                  email: string
                  name: string
                  role: string
                to:
                - conversationRelatedTo: string
                  conversationSubject: string
                  emailAlias: string
                  aliasMaskType: string
                  email: string
                  name: string
                  role: string
                subject: string
                firstWords: string
                body: string
                hasAttachment: true
                attachmentNames:
                - string
                date: '2021-08-31T22:50:53.564Z'
components:
  schemas:
    LogisticsInfoDeliveryWindow:
      type: object
      properties:
        startDateUtc:
          type: string
          format: date-time
        endDateUtc:
          type: string
          format: date-time
        price:
          type: integer
          format: int64
      additionalProperties: false
    LogisticsInfo:
      type: object
      properties:
        itemIndex:
          type: integer
          format: int32
        quantity:
          type: integer
          format: int32
          title: quantity
          description: Amount of units in the cart.
          example: 5
        selectedSla:
          type:
          - string
          - 'null'
        selectedDeliveryChannel:
          type:
          - string
          - 'null'
        lockTtl:
          type:
          - string
          - 'null'
        shippingEstimate:
          type:
          - string
          - 'null'
        addressId:
          type:
          - string
          - 'null'
        pickupId:
          type:
          - string
          - 'null'
        price:
          type: integer
          format: int32
        deliveryWindow:
          $ref: '#/components/schemas/LogisticsInfoDeliveryWindow'
        slAs:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/LogisticsInfoSLA'
      additionalProperties: false
    PlanThinRequest:
      title: PlanRequest
      description: Information about the plan.
      required:
      - frequency
      - id
      - purchaseDay
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: ID of the plan.
          example: store.subscription
        frequency:
          $ref: '#/components/schemas/FrequencyRequest'
        validity:
          $ref: '#/components/schemas/ValidityRequest'
        purchaseDay:
          type:
          - string
          - 'null'
          description: Day in which recurrent orders will be created.
          example: '15'
      additionalProperties: false
    PurchaseContextAvailableGiftResponse:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
        seller:
          type:
          - string
          - 'null'
        quantity:
          type: integer
          format: int32
          title: quantity
          description: Amount of units in the cart.
          example: 5
        price:
          type:
          - integer
          - 'null'
          format: int64
        sellingPrice:
          type:
          - integer
          - 'null'
          format: int64
        unitMultiplier:
          type:
          - number
          - 'null'
          format: double
        attachments:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ItemAttachment'
        name:
          type:
          - string
          - 'null'
        isGift:
          type: boolean
        priceTags:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PriceTag'
        isSelected:
          type: boolean
      additionalProperties: false
    Totalization:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
        value:
          type: number
          format: double
      additionalProperties: false
    ShippingEstimate:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
        estimate:
          type:
          - string
          - 'null'
        estimateDeliveryDate:
          type:
          - string
          - 'null'
          format: date-time
        nextPurchaseDate:
          type: string
          format: date-time
        allItemsMatched:
          type: boolean
      additionalProperties: false
    TotalizationResponse:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
        name:
          type:
          - string
          - 'null'
        valueAsInt:
          type: integer
          format: int64
      additionalProperties: false
    LogisticsInfoSLA:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
        pickupPointId:
          type:
          - string
          - 'null'
        deliveryChannel:
          type:
          - string
          - 'null'
        price:
          type: integer
          format: int32
        shippingEstimate:
          type:
          - string
          - 'null'
        lockTtl:
          type:
          - string
          - 'null'
        deliveryWindows:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/LogisticsInfoDeliveryWindow'
        availableDeliveryWindows:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/LogisticsInfoDeliveryWindow'
      additionalProperties: false
    Payment:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
        paymentSystem:
          type:
          - string
          - 'null'
        group:
          type:
          - string
          - 'null'
        bin:
          type:
          - string
          - 'null'
        accountId:
          type:
          - string
          - 'null'
        parentAccountId:
          type:
          - string
          - 'null'
        referenceValue:
          type: integer
          format: int64
        value:
          type: integer
          format: int64
        installments:
          type: integer
          format: int32
        url:
          type:
          - string
          - 'null'
        cardNumber:
          type:
          - string
          - 'null'
        fields:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PaymentField'
      additionalProperties: false
    Transaction:
      type: object
      properties:
        isActive:
          type: boolean
        payments:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Payment'
      additionalProperties: false
    PaymentField:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
        value:
          type:
          - string
          - 'null'
      additionalProperties: false
    FrequencyRequest:
      required:
      - interval
      - periodicity
      type: object
      description: Information about subscriptions' recurrence.
      properties:
        periodicity:
          type:
          - string
          - 'null'
          description: "Defines the subscriptions recurrence period. The possible values are: \n- `DAILY` \n- `WEEKLY` \n- `MONTHLY` \n- `YEARLY`"
          example: MONTHLY
        interval:
          type: integer
          format: int32
          description: Time interval configured between subscription orders, which depends on the periodicity. For a `DAILY` periodicity, the value will be days, for `MONTHLY` it will be months, and so on.
          example: 3
      additionalProperties: false
    PriceTag:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
        valueAsInt:
          type: integer
          format: int64
        rawValue:
          type: number
          format: double
        isPercentual:
          type: boolean
        identifier:
          type:
          - string
          - 'null'
      additionalProperties: false
    FrequencyResponse:
      title: Frequency
      required:
      - interval
      - periodicity
      type: object
      properties:
        periodicity:
          type:
          - string
          - 'null'
        interval:
          type: integer
          format: int32
      additionalProperties: false
    SimulateResponse:
      type: object
      properties:
        items:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/OrderItem'
        logisticsInfo:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/LogisticsInfo'
        paymentData:
          $ref: '#/components/schemas/PaymentData'
        country:
          type:
          - string
          - 'null'
        postalCode:
          type:
          - string
          - 'null'
        messages:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/SimulateMessageResponse'
        selectableGiftsResponse:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PurchaseContextSelectableGiftsResponse'
        totals:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/TotalizationResponse'
        simulationItems:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/SimulationItemResult'
      additionalProperties: false
    PaymentMethodResponse:
      title: PaymentMethod
      required:
      - paymentSystem
      type: object
      properties:
        paymentAccountId:
          type:
          - string
          - 'null'
        paymentSystem:
          type:
          - string
          - 'null'
        installments:
          type:
          - integer
          - 'null'
          format: int32
      additionalProperties: false
    ValidityRequest:
      type: object
      description: Information about the period during which the subscription will be valid.
      properties:
        begin:
          type:
          - string
          - 'null'
          description: Subscription's beginning date with the format `yyyy-mm-ddThh:mm:ss`.
          example: '2022-06-10T00:00:00'
        end:
          type:
          - string
          - 'null'
          description: Subscription's ending date with the format `yyyy-mm-ddThh:mm:ss`.
          example: '2023-06-10T00:00:00'
   

# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vtex/refs/heads/main/openapi/vtex-subscriptions-api-openapi.yml