VTEX Subscriptions API

openapi: 3.0.0
info:
  title: VTex Anti-fraud Provider Account Subscriptions API
  description: ">ℹ️ Onboarding guide\r\n>\r\n> Check the new [Payments onboarding guide](https://developers.vtex.com/docs/guides/payments-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Payments and is organized by focusing on the developer's journey.\r\n\r\nThe Anti-fraud Provider Protocol is a set of definitions to help you integrate your anti-fraud service API into VTEX platform.\r\n\r\nTo achieve this, you need to implement a web API (REST) following the specifications described in this documentation.\r\n\r\n>⚠️ You can also access our [template on GitHub](https://github.com/vtex-apps/antifraud-provider-example) to help you quickly develop your anti-fraud connector using the Anti-fraud Provider Protocol and VTEX IO.\r\n\r\nTo learn more about the Anti-fraud Provider Protocol, check our [developer guide](https://developers.vtex.com/docs/guides/how-the-integration-protocol-between-vtex-and-antifraud-companies-works).\r\n\r\n## Anti-fraud Provider API Index\r\n\r\n### Anti-fraud  Flow\r\n\r\n- `POST` [Send Anti-fraud Pre-Analysis Data (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/pre-analysis)\r\n- `POST` [Send Anti-fraud Data](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/transactions)\r\n- `PUT` [Update Anti-fraud Transactions (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#put-/transactions/-transactionId-)\r\n- `GET` [List Anti-fraud Provider Manifest](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/manifest)\r\n- `GET` [Get Anti-fraud Status](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/transactions/-transactions.id-)\r\n- `DELETE` [Stop Anti-fraud Analysis (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#delete-/transactions/-transactions.Id-)\r\n\r\n### OAuth Flow\r\n\r\n1. `POST` [Retrieve Token](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/authorization/token)\r\n2. `GET` [Redirect](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/redirect)\r\n3. `GET` [Return to VTEX](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/authorizationCode)\r\n4. `GET` [Get Credentials](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/authorization/credentials)"
  version: '1.0'
servers:
- url: https://{providerApiEndpoint}
  description: Anti-fraud provider endpoint URL.
  variables:
    providerApiEndpoint:
      description: Anti-fraud provider endpoint URL.
      default: '{providerApiEndpoint}'
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
          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:
                      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:
    PurchaseContextAvailableGiftResponse:
      type: object
      properties:
        id:
          type: string
          nullable: true
        seller:
          type: string
          nullable: true
        quantity:
          type: integer
          format: int32
          title: quantity
          description: Amount of units in the cart.
          example: 5
        price:
          type: integer
          format: int64
          nullable: true
        sellingPrice:
          type: integer
          format: int64
          nullable: true
        unitMultiplier:
          type: number
          format: double
          nullable: true
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/ItemAttachment'
          nullable: true
        name:
          type: string
          nullable: true
        isGift:
          type: boolean
        priceTags:
          type: array
          items:
            $ref: '#/components/schemas/PriceTag'
          nullable: true
        isSelected:
          type: boolean
      additionalProperties: false
    PlanResponse:
      title: Plan
      required:
      - frequency
      - id
      - purchaseDay
      - validity
      type: object
      properties:
        id:
          type: string
          nullable: true
        frequency:
          $ref: '#/components/schemas/FrequencyResponse'
        validity:
          $ref: '#/components/schemas/ValidityResponse'
        purchaseDay:
          $ref: '#/components/schemas/PurchaseDay'
      additionalProperties: false
    ValidityResponse:
      title: Validity
      required:
      - begin
      type: object
      properties:
        begin:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
          nullable: true
      additionalProperties: false
    PlanThinRequest:
      title: PlanRequest
      description: Information about the plan.
      required:
      - frequency
      - id
      - purchaseDay
      type: object
      properties:
        id:
          type: string
          nullable: true
          description: ID of the plan.
          example: store.subscription
        frequency:
          $ref: '#/components/schemas/FrequencyRequest'
        validity:
          $ref: '#/components/schemas/ValidityRequest'
        purchaseDay:
          type: string
          description: Day in which recurrent orders will be created.
          nullable: true
          example: '15'
      additionalProperties: false
    UpdateItemInput:
      type: object
      properties:
        status:
          type: string
          nullable: true
        isSkipped:
          type: boolean
          nullable: true
        quantity:
          type: integer
          format: int32
          title: quantity
          description: Amount of units in the cart.
          example: 5
        manualPrice:
          type: integer
          format: int32
          title: manualPrice
          description: Manual price.
          default: null
          nullable: true
          example: 40
      additionalProperties: false
    SimulateMessageResponse:
      type: object
      properties:
        code:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
        text:
          type: string
          nullable: true
      additionalProperties: false
    ItemSimulationStatus:
      enum:
      - 0
      - 1
      - 2
      - 3
      - 4
      type: integer
      format: int32
    Transaction:
      type: object
      properties:
        isActive:
          type: boolean
        payments:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
          nullable: true
      additionalProperties: false
    PurchaseContextSelectableGiftsResponse:
      type: object
      properties:
        id:
          type: string
          nullable: true
        availableQuantity:
          type: integer
          format: int32
        availableGifts:
          type: array
          items:
            $ref: '#/components/schemas/PurchaseContextAvailableGiftResponse'
          nullable: true
      additionalProperties: false
    LogisticsInfoDeliveryWindow:
      type: object
      properties:
        startDateUtc:
          type: string
          format: date-time
        endDateUtc:
          type: string
          format: date-time
        price:
          type: integer
          format: int64
      additionalProperties: false
    FrequencyResponse:
      title: Frequency
      required:
      - interval
      - periodicity
      type: object
      properties:
        periodicity:
          type: string
          nullable: true
        interval:
          type: integer
          format: int32
      additionalProperties: false
    LogisticsInfoSLA:
      type: object
      properties:
        id:
          type: string
          nullable: true
        pickupPointId:
          type: string
          nullable: true
        deliveryChannel:
          type: string
          nullable: true
        price:
          type: integer
          format: int32
        shippingEstimate:
          type: string
          nullable: true
        lockTtl:
          type: string
          nullable: true
        deliveryWindows:
          type: array
          items:
            $ref: '#/components/schemas/LogisticsInfoDeliveryWindow'
          nullable: true
        availableDeliveryWindows:
          type: array
          items:
            $ref: '#/components/schemas/LogisticsInfoDeliveryWindow'
          nullable: true
      additionalProperties: false
    SubscriptionGroupResponse:
      title: Subscription
      required:
      - createdAt
      - customerEmail
      - customerId
      - cycleCount
      - id
      - isSkipped
      - items
      - lastUpdate
      - nextPurchaseDate
      - plan
      - purchaseSettings
      - shippingAddress
      - status
      type: object
      properties:
        id:
          type: string
          nullable: true
        customerId:
          type: string
          nullable: true
        customerEmail:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
        isSkipped:
          type: boolean
        nextPurchaseDate:
          type: string
          format: date-time
        lastPurchaseDate:
          type: string
          format: date-time
          nullable: true
        plan:
          $ref: '#/components/schemas/PlanResponse'
        shippingAddress:
          $ref: '#/components/schemas/ShippingAddressResponse'
        purchaseSettings:
          $ref: '#/components/schemas/PurchaseSettingsResponse'
        cycleCount:
          type: integer
          format: int32
        createdAt:
          type: string
          format: date-time
        lastUpdate:
          type: string
          format: date-time
        items:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionItemResponse'
          nullable: true
      additionalProperties: false
    PurchaseDay:
      enum:
      - 0
      - 1
      - 2
      - 3
      - 4
      - 5
      - 6
      - 7
      - 8
      - 9
      - 10
      - 11
      - 12
      - 13
      - 14
      - 15
      - 16
      - 17
      - 18
      - 19
      - 20
      - 21
      - 22
      - 23
      - 24
      - 25
      - 26
      - 27
      - 28
      - 29
      - 30
      - 31
      - 999
      - -6
      - -5
      - -4
      - -3
      - -2
      - -1
      type: integer
      format: int32
    SimulateResponseVO:
      type: object
      properties:
        simulateResponse:
          $ref: '#/components/schemas/SimulateResponse'
        shippingEstimate:
          $ref: '#/components/schemas/ShippingEstimate'
        simulationItems:
          type: array
          items:
            $ref: '#/components/schemas/SimulationItemResult'
          nullable: true
        totals:
          type: array
          items:
            $ref: '#/components/schemas/Totalization'
          nullable: true
      additionalProperties: false
    PurchaseSettingsThinRequest:
      title: PurchaseSettingsRequest
      description: Object containing purchase settings information.
      required:
      - paymentMethod
      - salesChannel
      type: object
      properties:
        paymentMethod:
          $ref: '#/components/schemas/PaymentMethodThinRequest'
        salesChannel:
          type: string
          description: Sales channel (or [trade policy](https://help.vtex

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