Vendasta Subscription Assignments API

openapi: 3.2.0
info:
  title: Platform REST Subscription Assignments API
  version: Evergreen
servers:
- url: https://prod.apigateway.co/platform
  description: Production
- description: Demo
  url: https://demo.apigateway.co/platform
- description: Local
  url: '{local}/platform'
- url: http://localhost:11001/platform
  description: Localhost
tags:
- name: Subscription Assignments
paths:
  /subscriptionAssignments:
    parameters:
    - schema:
        type: string
      name: filter[businessLocationId]
      in: query
      required: true
    get:
      summary: List Subscription Assignments
      responses:
        '200':
          description: A list of Assignments
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/subscriptionAssignment'
                  links:
                    type: object
                    properties:
                      self:
                        type: string
                        format: uri
                      first:
                        type: string
                        format: uri
                      next:
                        type: string
                        format: uri
      operationId: get-subscriptionAssignments
      security:
      - OAuth2Demo:
        - sales.account
      - OAuth2Prod:
        - sales.account
      x-lifecycle:
        status: trustedTester
      parameters:
      - schema:
          type: string
          example: Bearer <Access Token>
          pattern: ^Bearer\s\S+
        in: header
        name: Authorization
        description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
        required: true
      - schema:
          type: string
        in: query
        name: filter[businessLocationId]
        description: The id of the business location you want to get a the assignments for
        required: true
      tags:
      - Subscription Assignments
      description: 'Status: `Trusted Tester`


        Returns a list of subscription assignments based on the provided filters.


        Currently you must filter the list to a single business location at a time using `filter[businessLocationId]`


        You will receive a different record for each subscription purchased for multi-activatable products.'
    options:
      summary: List valid HTTP verbs for /subscriptionAssignments
      operationId: options-subscriptionAssignments
      responses:
        '204':
          description: No Content
      description: Used solely for CORS the OPTIONS request returns the list of possible HTTP methods and other headers that browsers use to protect user's security. You should not call this operation directly.
      tags:
      - Subscription Assignments
  /subscriptionAssignments/{id}:
    parameters:
    - schema:
        type: string
      name: id
      in: path
      required: true
    get:
      summary: Get a particular Subscription Assignment
      responses:
        '200':
          description: A particular Assignment
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/subscriptionAssignment'
      operationId: get-subscriptionAssignments-by-id
      description: 'Status: `Proposed`


        Fetch the details of a specific subscription assignment by id.'
      tags:
      - Subscription Assignments
      x-lifecycle:
        status: proposed
    options:
      summary: List valid HTTP verbs for /subscriptionAssignments/{id}
      operationId: options-subscriptionAssignment-id
      responses:
        '204':
          description: No Content
      description: Used solely for CORS the OPTIONS request returns the list of possible HTTP methods and other headers that browsers use to protect user's security. You should not call this operation directly.
      tags:
      - Subscription Assignments
  /subscriptionAssignments/{id}/actions/requestCancellation:
    parameters:
    - schema:
        type: string
        example: AG-CQD6ZR6:MP-R7G3NP55T725DM5VGD:beff34a4-cccc-4be8-bd9
      name: id
      in: path
      required: true
      description: 'The id should be a string which is in the form - businessLocationId : productId : activationId'
    post:
      summary: Cancel Subscription Assignment
      responses:
        '204':
          description: No Content
      description: 'Status: `Trusted Tester`


        Used for cancelling subscription assignments.


        By default all cancel request uses DeactivationType as a DeactivationTypeCancel which indicate we should turn the item off at the items anniversary date, or commitment date, whichever is later. So product is still active till the anniversary date.'
      tags:
      - Subscription Assignments
      x-lifecycle:
        status: proposed
      operationId: cancel-subscriptionAssignments-by-id
      security:
      - OAuth2Demo:
        - sales.account
      - OAuth2Prod:
        - sales.account
      parameters:
      - schema:
          type: string
          example: Bearer <Access Token>
          pattern: ^Bearer\s\S+
        in: header
        description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
        name: Authorization
        required: true
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                reason:
                  type: array
                  description: '`crisisShiftInPriorities`due to crisis shift in priorities


                    `customerWasNotSatisfied`due to customer not satisfied with product


                    `customerReachedEndOfContract`due to customer reached end of contract


                    `movingToAComputer`due to moving to a computer


                    `productIsTooExpensive`due to product is too expensive


                    `productWasAccidentallyActivated`due to product was accidentally activated


                    `other` any other reason for cancellation'
                  items:
                    type: string
                    enum:
                    - crisisShiftInPriorities
                    - customerWasNotSatisfied
                    - customerReachedEndOfContract
                    - movingToAComputer
                    - productIsTooExpensive
                    - productWasAccidentallyActivated
                    - other
                comments:
                  type: string
                  description: more description for cancellation of products
                deactivationType:
                  type: string
                  description: '`cancel` indicates we should turn the product or service off at the anniversary date, or commitment date, whichever is later and till then it will be available for use.


                    `immediate` indicates we should turn the product or service off immediately and it will no longer be available to use.'
                  default: cancel
                  enum:
                  - cancel
                  - immediate
            examples:
              Example 1:
                value:
                  reason:
                  - crisisShiftInPriorities
                  comments: Due to crisis
                  deactivationType: cancel
        description: ''
    options:
      summary: List valid HTTP verbs for /subscriptionAssignments/{id}/actions/requestCancellat…
      operationId: options-subscriptionAssignment-requestCancellationAction
      responses:
        '204':
          description: No Content
      description: Used solely for CORS the OPTIONS request returns the list of possible HTTP methods and other headers that browsers use to protect user's security. You should not call this operation directly.
      tags:
      - Subscription Assignments
  /subscriptionAssignments/{id}/actions/undoCancellation:
    parameters:
    - schema:
        type: string
        example: AG-CQD6ZR6:MP-R7G3NP55T725DM5VGD:beff34a4-cccc-4be8-bd9
      name: id
      in: path
      required: true
      description: 'The id should be a string which is in the form - businessLocationId : productId : activationId'
    post:
      summary: Restore a Canceled Subscription Assignment
      responses:
        '204':
          description: No Content
      description: 'Status: `Trusted Tester`


        Used for restoring a canceled subscription assignment.'
      tags:
      - Subscription Assignments
      x-lifecycle:
        status: proposed
      operationId: restore-subscriptionAssignments-by-id
      security:
      - OAuth2Demo:
        - sales.account
      - OAuth2Prod:
        - sales.account
      parameters:
      - schema:
          type: string
          example: Bearer <Access Token>
          pattern: ^Bearer\s\S+
        in: header
        description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
        name: Authorization
        required: true
    options:
      summary: List valid HTTP verbs for /subscriptionAssignments/{id}/actions/undoCancellation
      operationId: options-subscriptionAssignment-undoCancellationAction
      responses:
        '204':
          description: No Content
      description: Used solely for CORS the OPTIONS request returns the list of possible HTTP methods and other headers that browsers use to protect user's security. You should not call this operation directly.
      tags:
      - Subscription Assignments
components:
  schemas:
    subscriptionAssignment:
      type: object
      description: A SubscriptionAssignment is an allocation of a single Subscription unit. The way a subscription unit is allocated depends on the Product or Service represented by the Subscription. A common case is that Subscription Units are assigned to Locations. In that case, the SubscriptionAssignment stores the link between a purchased Subscription and the Location it was allocated to.
      x-tags:
      - Subscription Assignments
      title: Subscription Assignments
      properties:
        id:
          type: string
          description: "The id is a string which is in the form - \nbusinessLocationId : productId : activationId"
          example: AG-1234:MP-12345:vb99d662-e12f-4r1c-g275-449aa19td438
        type:
          type: string
          default: subscriptionAssignment
          enum:
          - subscriptionAssignment
          description: Should always be subscriptionAssignment
        attributes:
          type: object
          properties:
            sku:
              type: string
              description: The unique identifier of a product, product edition or package. It can be obtained by following [this guide](https://docs.apigateway.co/docs/openapi-specs/docs/Guides/Sell/FindSKU.md). This value is used when placing an order.
            productId:
              type: string
              description: The Application ID associated with this subscription
            editionId:
              type: string
              description: The Application Edition ID associated with this subscription (if applicable)
            status:
              type: string
              description: The status of the Assignment. Both `assigned` and `pendingUnassignment` mean it is currently assigned.
              enum:
              - assigned
              - pendingUnassignment
              - pendingAssignment
  securitySchemes:
    JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
    OAuth2Demo:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://sso-api-demo.apigateway.co/oauth2/auth
          tokenUrl: https://sso-api-demo.apigateway.co/oauth2/token
          scopes:
            sales.contact: Read-write access to sales contact details
            business:read: Read only access to business details
            business: Read-write access to business details
            partner:read: Read-write access to details about your partner
            financial: Read-write access to financial details
            order: Read-write access to order details
            order:read: Read only access to order details
            user.profile:read: Read access to the profile fields of all categories of users
            user.contact:read: Read access to the contact info (email, phone, address) of all categories of users
            user.permission:read: Read access to the permission info (accessible locations, features and roles) of all categories of users
            user.permission: Read-write access to the permission info (accessible locations, features and roles) of all categories of users
            user.admin: Read-write access to manage all users
            user.list: '''Allows searching for users based on a set of filters. (ex: email, name, category, organization). Without this scope an exact user id is required.'
            self.user.admin: Allows editing the profile, contact info and profile image for the current user.
            self.user.contact:read: Read access to the contact info (email, phone, address) of the current user.
            openid: Allows getting the user id of the current user
            profile: Readonly access to the user profile, including name, locale, and language preferences.
            email: Allows readonly access to the email of the current user.
            phone: Allows readonly access to the phone numbers of the current user.
            address: Allows readonly access to the address of the current user.
            sales.account: Allows read-write access to account records
            sales.proposals: Allows read-write access to proposals
            product: Read access to the product details
            automation:read: Read only access to automations
          refreshUrl: ''
    OAuth2Prod:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://sso-api-prod.apigateway.co/oauth2/auth
          tokenUrl: https://sso-api-prod.apigateway.co/oauth2/token
          scopes:
            sales.contact: Read-write access to sales contact details
            business:read: Read only access to business details
            business: Read-write access to business details
            partner:read: Read-write access to details about your partner
            financial: Read-write access to financial details
            order:read: Read only access to order details
            order: Read-write access to order details
            user.profile:read: Read access to the profile fields of all categories of users
            user.contact:read: Read access to the contact info (email, phone, address) of all categories of users
            user.permission:read: Read access to the permission info (accessible locations, features and roles) of all categories of users
            user.permission: Read-write access to the permission info (accessible locations, features and roles) of all categories of users
            user.admin: Read-write access to manage all users
            user.list: '''Allows searching for users based on a set of filters. (ex: email, name, category, organization). Without this scope an exact user id is required.'
            self.user.admin: Allows editing the profile, contact info and profile image for the current user.
            self.user.contact:read: Read access to the contact info (email, phone, address) of the current user.
            openid: Allows getting the user id of the current user
            profile: Readonly access to the user profile, including name, locale, and language preferences.
            email: Allows readonly access to the email of the current user.
            phone: Allows readonly access to the phone numbers of the current user.
            address: Allows readonly access to the address of the current user.
            sales.account: Allows read-write access to account records
            sales.proposals: Allows read-write access to proposals
            product: Read access to the product details
            automation:read: Read only access to automations
          refreshUrl: ''