Vendasta Platform REST API

openapi: 3.0.0
info:
  title: Platform REST APIs
  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
paths:
  /businessLocations:
    post:
      summary: Create Business Location
      operationId: post-businessLocations
      responses:
        '201':
          description: Created
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/businessLocations'
                  links:
                    type: object
                    properties:
                      self:
                        type: string
                        format: uri
                        description: The address of the newly created business location
          headers:
            Location:
              schema:
                type: string
                format: uri
              description: The address of the newly created business location
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/businessLocations'
            examples:
              Example Request:
                value:
                  type: businessLocations
                  attributes:
                    customerIdentifier: string
                    name: string
                    address:
                      line1: 109 8th Street E.
                      line2: Suite 23
                      city: string
                      postalCode: S7M 1R3
                      regionCode: CA-SK
                      countryCode: CA
                    phoneNumbers:
                      - string
                    serviceAreaBusiness: true
                    geoCoordinate:
                      latitude: -90
                      longitude: -180
                    hours:
                      - hoursTypeId: general
                        regularHours:
                          - openDay: wednesday
                            closeDay: wednesday
                            openTime: '09:00'
                            closeTime: '17:00'
                        specialHours:
                          - status: open
                            startDate: '2019-08-24'
                            endDate: '2019-08-24'
                            startTime: '09:45'
                            endTime: '16:45'
                    tollFreeNumber: string
                    trackingNumbers:
                      - string
                    commonNames:
                      - string
                  relationships:
                    businessPartner:
                      data:
                        type: partners
                        id: ABC
                    businessCategories:
                      data:
                        - type: businessCategories
                          id: 'active:diving:freediving'
      x-lifecycle:
        status: trustedTester
      description: |-
        [Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`

        Used to record basic data for a new location.

        The following members must be populated during creation:
        - `relationships.businessPartner.data.id`
        - `attributes.name`
      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
            default: application/vnd.api+json
            enum:
              - application/vnd.api+json
          in: header
          name: Content-Type
          required: true
          description: Indicates the format of the request body being sent. In most cases you will want `application/vnd.api+json`
      security:
        - OAuth2Demo:
            - business
        - OAuth2Prod:
            - business
      tags:
        - Business Locations
    options:
      operationId: options-businessLocations
      summary: List valid HTTP verbs for /businessLocations
      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. '
      responses:
        '204':
          description: No Content
      tags:
        - Options
        - Business Locations
    get:
      summary: List Business Locations
      operationId: get-businessLocations
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/businessLocations'
                  links:
                    type: object
                    properties:
                      self:
                        type: string
                        format: uri
                      first:
                        type: string
                        description: Provides a link back to the first page of results
                        format: uri
                      next:
                        type: string
                        description: The URI at which the next batch of business locations can be gotten from
                        format: uri
                  meta:
                    type: object
                    x-stoplight:
                      id: 9c9hcw9pdy3iy
                    properties:
                      error:
                        type: array
                        x-stoplight:
                          id: qg547xfmaujg5
                        items:
                          x-stoplight:
                            id: ykm7pgshfp82r
                          type: object
                          properties:
                            ID:
                              type: string
                              x-stoplight:
                                id: 3s1xmzarzaaf6
                              example: AG-XXXXXXXX
                            Message:
                              type: string
                              x-stoplight:
                                id: m3i058fvfdhvq
                              example: Account not found
        '500':
          description: |-
            Internal Server Error
            * duplicate filter ids, and other unkown errors
      description: |-
        [Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`

        Produces a list of business locations
      parameters:
        - schema:
            type: string
          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[businessPartner.id]'
          description: Return business locations for the specified partner
          required: true
        - schema:
            type: string
          in: query
          description: 'The cursor stores all your filters and current location in the list to allow paging over the results in smaller batches. The value will be provided in the response links. [Pagination Docs](https://developers.vendasta.com/platform/ZG9jOjEwMTkzMDg0-overview#paging).'
          name: 'page[cursor]'
        - schema:
            type: string
            maxLength: 25
            default: '25'
            minLength: 1
          in: query
          description: 'The maximum number of tasks you would like returned in a single batch. Use the links.next member in the response to get the remainder. [Pagination Docs](https://developers.vendasta.com/platform/ZG9jOjEwMTkzMDg0-overview#paging).'
          name: 'page[limit]'
        - schema:
            type: string
            enum:
              - createdAt
              - '-createdAt'
              - name
              - '-name'
              - updatedAt
              - '-updatedAt'
            default: '-updatedAt'
          in: query
          name: sort
          description: Sort busines location based on selected option. Defaulted to -updatedAt (Desc updatedAt)
        - schema:
            type: boolean
          in: query
          name: useNewCategory
          description: 'useNewCategory is of type boolean which returns new/old business categories.If value of useNewCategory is true then it will return new business categories , if false then it will return old business categories.In case of not set, it will return categories as per feature flag.'
        - schema:
            type: string
            example: 'name,phoneNumbers,hours'
          in: query
          name: 'fields[businessLocations]'
          description: 'Filter businessLocations by the following fields: name, phoneNumbers, customerIdentifier, geoCoordinate, serviceAreaBusiness, hours, and updatedAt. These fields will be included in the response.'
        - schema:
            type: array
            items:
              type: string
            example: '["AG-123","AG-456"]'
          in: query
          name: 'filter[id]'
          description: 'Return accounts for given ids. For this filter ,We are not supporting pagination.'
        - schema:
            type: string
            example: 'Acme Plumbing'
          in: query
          name: 'filter[searchTerm]'
          description: |-
            Performs a full-text search across business location data (such as name, phone numbers, and address). The results order is not affected by the quality of this match — use `sort` to control ordering.
            Cannot be combined with `filter[id]`; the request will be rejected if both are provided.
      security:
        - OAuth2Demo:
            - business
            - 'business:read'
        - OAuth2Prod:
            - business
            - 'business:read'
      tags:
        - Business Locations
      x-lifecycle:
        status: trustedTester
  '/businessLocations/{id}':
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
    get:
      summary: Get Business Location
      tags:
        - Business Locations
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/businessLocations'
                  links:
                    type: object
                    properties:
                      self:
                        type: string
      operationId: get-businessLocations-id
      x-lifecycle:
        status: trustedTester
      description: |-
        [Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`

        Returns basic data about the business location.
      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: boolean
          in: query
          description: 'useNewCategory is of type boolean which returns new/old business categories.If value of useNewCategory is true then it will return new business categories , if false then it will return old business categories.In case of not set, it will return categories as per feature flag.'
          name: useNewCategory
        - schema:
            type: string
            example: 'name,phoneNumbers,hours'
          in: query
          name: 'fields[businessLocations]'
          description: 'Filter businessLocations by the following fields: name, phoneNumbers, customerIdentifier, geoCoordinate, serviceAreaBusiness, hours, and updatedAt. These fields will be included in the response.'
      security:
        - OAuth2Demo:
            - business
            - 'business:read'
        - OAuth2Prod:
            - business
            - 'business:read'
    options:
      operationId: options-businessLocations-id
      summary: 'List valid HTTP verbs for /businessLocations/{id}'
      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. '
      responses:
        '204':
          description: No Content
      tags:
        - Options
        - Business Locations
    patch:
      summary: Update Business Location
      operationId: patch-businessLocations-id
      tags:
        - Business Locations
      description: |-
        [Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`

        Update the existing business location.
        Only the root ID and type fields are required. All others are optional and will keep their original value if omitted.
      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
            default: application/vnd.api+json
            enum:
              - application/vnd.api+json
          in: header
          name: Content-Type
          required: true
          description: Indicates the format of the request body being sent. In most cases you will want `application/vnd.api+json`
      security:
        - OAuth2Demo:
            - business
        - OAuth2Prod:
            - business
      responses:
        '200':
          description: Ok
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/businessLocations'
                  links:
                    type: object
                    properties:
                      self:
                        type: string
                        format: uri
                        description: The address of the updated business location
          headers: {}
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/businessLocations'
  /users:
    post:
      summary: Create User
      operationId: post-users
      responses:
        '201':
          description: Created
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/users'
                  links:
                    type: object
                    properties:
                      self:
                        type: string
                        format: uri
                        description: The address of the newly created user
          headers:
            Location:
              schema:
                type: string
                format: uri
              description: The address of the newly created user
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/users'
            examples:
              Example 1:
                value:
                  data:
                    type: users
                    attributes:
                      givenName: William
                      familyName: Smith
                      greetingName: Billy
                      email: bill@example.com
                      languageLocaleCode: en-US
                      phoneNumbersSet: true
                      phoneNumbers:
                        - number: +1-306-555-1234 ext. 56
                          typeCode: mobile
                      address:
                        line1: 109 8th Street E.
                        line2: Suite 23
                        streetAddress: 109 8th Street E.
                        additionalAddress: Suite 23
                        city: Saskatoon
                        postalCode: S7M 1R3
                        regionCode: CA-SK
                        countryCode: CA
                      timeZone: America/Regina
                    relationships:
                      partner:
                        data:
                          type: partners
                          id: ABC
                      businessLocations:
                        data:
                          - type: businessLocations
                            id: AG-1234567
                      platformAccess:
                        data:
                          - type: appFeatures
                            id: 'pc:access'
      x-lifecycle:
        status: trustedTester
      description: |-
        [Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`

        Used to record basic data for a new location.

        The following members must be populated during creation:
        - `relationships.partner.data.id`
        - `attributes.email`
      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
            default: application/vnd.api+json
            enum:
              - application/vnd.api+json
          in: header
          name: Content-Type
          required: true
          description: Indicates the format of the request body being sent. In most cases you will want `application/vnd.api+json`
      security:
        - OAuth2Demo:
            - user.admin
        - OAuth2Prod:
            - user.admin
      tags:
        - Users
    options:
      operationId: options-users
      summary: List valid HTTP verbs for /users
      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. '
      responses:
        '204':
          description: No Content
      tags:
        - Options
        - Users
    get:
      summary: List Users
      operationId: get-users
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/users'
                  links:
                    type: object
                    properties:
                      self:
                        type: string
                        format: uri
                      first:
                        type: string
                        description: Provides a link back to the first page of results
                        format: uri
                      next:
                        type: string
                        description: The URI at which the next batch of users can be gotten from
                        format: uri
      description: |-
        [Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`

        Produces a list of users
      parameters:
        - schema:
            type: string
          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[partner.id]'
          description: Return users for the specified partner. Required except when filtering by id.
        - schema:
            type: string
          in: query
          description: 'The cursor stores all your filters and current location in the list to allow paging over the results in smaller batches. The value will be provided in the response links. [Pagination Docs](https://developers.vendasta.com/platform/ZG9jOjEwMTkzMDg0-overview#paging).'
          name: 'page[cursor]'
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          in: query
          description: 'The maximum number of users you would like returned in a single batch. Use the links.next member in the response to get the remainder. [Pagination Docs](https://developers.vendasta.com/platform/ZG9jOjEwMTkzMDg0-overview#paging).'
          name: 'page[limit]'
        - schema:
            type: array
            example:
              - 'U-12342,U-5345'
            items:
              type: string
          in: query
          name: 'filter[id]'
          description: A comma separated list of user ids to fetch in a batch
        - schema:
            type: string
          in: query
          name: 'filter[searchTerm]'
          description: A string containing a partial name or email address. The results order is not affected by the quality of this match.
        - schema:
            type: string
          in: query
          name: 'filter[email]'
          description: A string containing a complete email that must be an exact match.
        - schema:
            type: array
            items:
              type: string
              enum:
                - business
                - partner
                - bot
          in: query
          name: 'filter[category]'
          description: 'Filter the users based on the broad category that they fall into. In some rare cases users may be part of multiple categories. '
      security:
        - OAuth2Demo:
            - user.admin
            - user.list
        - OAuth2Prod:
            - user.admin
            - user.list
      tags:
        - Users
      x-lifecycle:
        status: trustedTester
  '/users/{id}':
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
    get:
      summary: Get User
      tags:
        - Users
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/users'
                  links:
                    type: object
                    properties:
                      self:
                        type: string
      operationId: get-users-id
      x-lifecycle:
        status: trustedTester
      description: |-
        [Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`

        Returns information about a single user. The fields you are able to use will be affected by the combination of scopes that you were granted access to.
      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
      security:
        - OAuth2Demo:
            - user.admin
            - 'user.profile:read'
            - 'user.contact:read'
            - 'user.permission:read'
            - user.permission
            - self.user.admin
            - 'self.user.contact:read'
            - openid
            - profile
            - email
            - phone
            - address
        - OAuth2Prod:
            - user.admin
            - 'user.profile:read'
            - 'user.contact:read'
            - 'user.permission:read'
            - user.permission
            - self.user.admin
            - 'self.user.contact:read'
            - openid
            - profile
            - email
            - phone
            - address
    options:
      operationId: options-users-id
      summary: 'List valid HTTP verbs for /users/{id}'
      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. '
      responses:
        '204':
          description: No Content
      tags:
        - Options
        - Users
    patch:
      summary: Update User
      operationId: patch-users-id
      tags:
        - Users
      description: |-
        [Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Proposed`

        Update the existing user.
        Only the root ID and type fields are required. All others are optional and will keep their original value if omitted.
      x-lifecycle:
        status: proposed
      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
            default: application/vnd.api+json
            enum:
              - application/vnd.api+json
          in: header
          name: Content-Type
          required: true
          description: Indicates the format of the request body being sent. In most cases you will want `application/vnd.api+json`
      security:
        - OAuth2Demo:
            - user.admin
        - OAuth2Prod:
            - user.admin
      responses:
        '200':
          description: Ok
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/users'
                  links:
                    type: object
                    properties:
                      self:
                        type: string
                        format: uri
                        description: The address of the updated user
          headers: {}
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/users'
            examples:
              Example 1:
                value:
                  data:
                    type: users
                    id: U-3ca38c57-7677-45d4-81e8-cd29eab91d63
                    attributes:
                      givenName: William
                      familyName: Smith
                      greetingName: Billy
                      email: bill@example.com
                      languageLocaleCode: en-US
                      phoneNumbersSet: true
                      phoneNumbers:
                        - number: +1-306-555-1234 ext. 56
                          typeCode: mobile
                      address:
                        line1: 109 8th Street E.
                        line2: Suite 23
                        streetAddress: 109 8th Street E.
                        additionalAddress: Suite 23
                        city: Saskatoon
                        postalCode: S7M 1R3
                        regionCode: CA-SK
                        countryCode: CA
                      timeZone: America/Regina
                    relationships:
                      partner:
                        data:
                          type: partners
                          id: ABC
                      businessLocations:
                        data:
                          - type: businessLocations
                            id: AG-1234567
                      platformAccess:
                        data:
                          - type: appFeatures
                            id: 'pc:access'
    delete:
      summary: Delete User
      operationId: delete-users-id
      responses:
        '204':
          description: No Content
      description: |-
        [Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`

        Deleting a user will remove personal data from it and prevent the ID from being used again in the future.
      security:
        - OAuth2Demo:
            - user.admin
        - OAuth2Prod:
            - user.admin
      tags:
        - Users
      parameters:
        - schema:
            type: string
          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
      x-lifecycle:
        status: trustedTester
  /purchases:
    get:
      summary: List Purchases
      tags:
        - Purchases
      operationId: get-purchases
      security:
        - OAuth2Demo:
            - financial
        - OAuth2Prod:
            - financial
      x-lifecycle:
        status: trustedTester
      description: |-
        [Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`

        Produces a list of wholesale purchases made.
      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[partner.id]'
          description: Only return purchases that for the specified partner
          required: true
        - schema:
            type: string
            format: date-time
          in: query
          name: 'filter[createdAt][>]'
          description: Only return purchases created after the specified time
        - schema:
            type: string
            format: date-time
          in: query
          name: 'filter[createdAt][<]'
          description: Only return purchases created before the specified time
        - schema:
            type: integer
            minimum: 0
            maximum: 100
            default: 10
          in: query
          name: 'page[limit]'
          description: 'The maximum number of tasks you would like returned in a single batch. Use the links.next member in the response to get the remainder. [Pagination Docs](https://developers.vendasta.com/platform/ZG9jOjEwMTkzMDg0-overview#paging).'
        - schema:
            type: string
          in: query
          name: 'page[cursor]'
          description: 'The cursor stores all your filters and current location in the list to allow paging over the results in smaller batches. The value will be provided in the response links. [Pagination Docs](https://developers.vendas

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