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](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`\n\nReturns a list of subscription assignments based on the provided filters. \n\nCurrently you must filter the list to a single business location at a time using `filter[businessLocationId]`\n\nYou 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/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](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `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](https://developer.mozilla.org/en-US/docs/Web/HTTP/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](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `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/requestCancellation
      operationId: options-subscriptionAssignment-requestCancellationAction
      responses:
        '204':
          description: No Content
      description: 'Used solely for [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/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](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `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](https://developer.mozilla.org/en-US/docs/Web/HTTP/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: ''