openapi: 3.2.0
info:
  title: Platform REST Purchases 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: Purchases
paths:
  /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.vendasta.com/platform/ZG9jOjEwMTkzMDg0-overview#paging).
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/purchases'
                  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 purchases can be gotten from
                        format: uri
    options:
      operationId: options-purchases
      summary: List valid HTTP verbs for /purchases
      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:
      - Purchases
components:
  schemas:
    purchases:
      title: Purchase
      type: object
      x-lifecycle:
        status: trustedTester
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`


        Purchases are a receipt of items sold to your organization. When selling to another organization you will want to create an Order instead.


        Purchases generated by the platform to record the wholesale fees that are charged to a partner for products they sell to their customers. One time fees and each renewal will appear as separate line items broken out per customer.


        All amounts will be specified in the minor unit of the purchase''s currency. For example in the case of USD that would be cents. For more info on converting between minor and major units see [this wikipedia article](https://en.wikipedia.org/wiki/ISO_4217#Minor_units_of_currency).'
      x-tags:
      - Purchases
      properties:
        id:
          type: string
          description: 'A platform generated identifier for the purchase '
        type:
          type: string
          enum:
          - purchases
          readOnly: false
        attributes:
          type: object
          properties:
            createdAt:
              description: The time at which the purchase was created
              format: date-time
              type: string
            statusCode:
              type: string
              default: draft
              enum:
              - draft
              - due
              - overdue
              - paid
              - uncollectible
              description: 'The payment status of the purchase will be one of the following:

                - `draft`:  Indicates the purchase is not closed yet. New line items can be added when the purchase is in this state.

                - `due`: The purchase has been finalized and is ready to be paid.

                - `overdue`: The purchase is unpaid and has past the due date

                - `paid`: The full amount has been paid.

                - `uncollectible`: After multiple failed attempts to collect payment it''s unlikely that this purchase will be paid'
              readOnly: true
            discountAmount:
              type: integer
              description: The sum of all price reductions applied to products
            taxAmount:
              type: integer
              description: The sum of all taxes applied to items of the purchase
            total:
              type: integer
              description: The total amount the purchase is for, accounting for any applied discounts or taxes
            currencyCode:
              type: string
              minLength: 3
              maxLength: 3
              example: CAD
              description: The 3 letter currency code as defined by [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)
            lineItems:
              type: array
              items:
                type: object
                properties:
                  sku:
                    type: string
                    description: The unique identifier of a product or service
                  customerId:
                    type: string
                    description: The ID of the organization that purchased the product
                  unitAmount:
                    description: The wholesale cost of the product before discounts or taxes are applied.
                    type: integer
                  discountAmount:
                    description: The total amount the cost of this product has been reduced by
                    type: integer
                  taxAmount:
                    description: The total amount of tax charged for this product
                    type: integer
                  total:
                    description: The final cost of the product accounting for any applied discounts or taxes
                    type: integer
        relationships:
          type: object
          properties:
            partner:
              type: object
              description: The partner that the purchase receipt is being sent to. They will be the one who purchased the product at a wholesale rate and activated it for one of their customers
              x-stoplight:
                id: 2l7icoo6qmoaw
              properties:
                data:
                  type: object
                  required:
                  - id
                  - type
                  properties:
                    id:
                      type: string
                      minLength: 3
                      maxLength: 4
                    type:
                      type: string
                      enum:
                      - partner
              required:
              - data
      required:
      - id
      - type
  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: ''