VTEX Cycles API

openapi: 3.2.0
info:
  title: VTex Subscriptions API (v3) Cycles 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 in your store, the Subscriptions API allows you to create, manage and monitor your customers'' subscriptions.


    !image


    To read more about the Subscriptions feature, check our article How Subscription works.'
  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: Cycles
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
          - '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: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/SubscriptionCycleResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionCycleResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/SubscriptionCycleResponse'
      operationId: getApiRnsPubCyclesByCycleId
      x-operation-id-source: derived
  /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
          - 'null'
      - name: endDate
        description: Upper limit for the date of creation of the cycle
        in: query
        schema:
          type:
          - string
          - 'null'
      - name: subscriptionId
        description: Id from the subscription that generated the cycle
        in: query
        schema:
          type:
          - string
          - 'null'
      - 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 cycle status
        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: 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'
      operationId: getApiRnsPubCycles
      x-operation-id-source: derived
  /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
          - '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: OK
      operationId: postApiRnsPubCyclesByCycleIdRetry
      x-operation-id-source: derived
components:
  schemas:
    SubscriptionCycleContext:
      type: object
      properties:
        items:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/SubscriptionCycleItemContext'
        paymentSystem:
          type:
          - string
          - 'null'
        paymentSystemName:
          type:
          - string
          - 'null'
        paymentSystemGroup:
          type:
          - string
          - 'null'
        paymentAccountId:
          type:
          - string
          - 'null'
        addressId:
          type:
          - string
          - 'null'
        addressType:
          type:
          - string
          - 'null'
      additionalProperties: false
    SimulationItemResult:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
        quantity:
          type: integer
          format: int32
          title: quantity
          description: Amount of units in the cart.
          example: 5
        unitPrice:
          type:
          - integer
          - 'null'
          format: int64
        status:
          $ref: '#/components/schemas/ItemSimulationStatus'
        statusName:
          type:
          - string
          - 'null'
      additionalProperties: false
    SubscriptionCycleItemContext:
      type: object
      properties:
        subscriptionItemId:
          type:
          - string
          - 'null'
        skuId:
          type:
          - string
          - 'null'
          title: skuId
          description: SKU ID.
          example: '12'
        quantity:
          type: integer
          format: int32
          title: quantity
          description: Amount of units in the cart.
          example: 5
        status:
          $ref: '#/components/schemas/Status'
        isSkipped:
          type: boolean
        cycleCount:
          type: integer
          format: int32
      additionalProperties: false
    Status:
      enum:
      - 0
      - 1
      - 2
      - 3
      type: integer
      format: int32
    ItemSimulationStatus:
      enum:
      - 0
      - 1
      - 2
      - 3
      - 4
      type: integer
      format: int32
    SubscriptionCycleOrderInfo:
      type: object
      properties:
        orderId:
          type:
          - string
          - 'null'
        orderGroup:
          type:
          - string
          - 'null'
        paymentURL:
          type:
          - string
          - 'null'
        value:
          type: integer
          format: int64
      additionalProperties: false
    SubscriptionCycleResponse:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
        subscriptionId:
          type:
          - string
          - 'null'
        status:
          type:
          - string
          - 'null'
        customerEmail:
          type:
          - string
          - 'null'
        date:
          type: string
          format: date-time
        lastUpdate:
          type: string
          format: date-time
        cycleCount:
          type: integer
          format: int32
        isInRetry:
          type: boolean
        message:
          type:
          - string
          - 'null'
        orderInfo:
          $ref: '#/components/schemas/SubscriptionCycleOrderInfo'
        context:
          $ref: '#/components/schemas/SubscriptionCycleContext'
        simulationItems:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/SimulationItemResult'
      additionalProperties: false
  securitySchemes:
    appKey:
      type: apiKey
      in: header
      name: X-VTEX-API-AppKey
    appToken:
      type: apiKey
      in: header
      name: X-VTEX-API-AppToken