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](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: 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'
  /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'
  /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
components:
  schemas:
    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
    ItemSimulationStatus:
      enum:
      - 0
      - 1
      - 2
      - 3
      - 4
      type: integer
      format: int32
    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
    Status:
      enum:
      - 0
      - 1
      - 2
      - 3
      type: integer
      format: int32
    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
    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
    SubscriptionCycleOrderInfo:
      type: object
      properties:
        orderId:
          type:
          - string
          - 'null'
        orderGroup:
          type:
          - string
          - 'null'
        paymentURL:
          type:
          - string
          - 'null'
        value:
          type: integer
          format: int64
      additionalProperties: false
  securitySchemes:
    appKey:
      type: apiKey
      in: header
      name: X-VTEX-API-AppKey
    appToken:
      type: apiKey
      in: header
      name: X-VTEX-API-AppToken