openapi: 3.0.0
info:
  title: Paigo Customers Usage API
  description: "\nFor developer documentation of the platform, please visit https://docs.paigo.tech.\n\n## Authentication\nPaigo API supports **bearer token** as the authentication method.\nSteps to set up authentication:\n1. Sign up with Paigo platform and get **client id** and **client secret**.\n2. Make a POST request to the auth endpoint `https://auth.paigo.tech/oauth/token` with the following body:\n```json\n{\n        audience: 'https://qnonyh1pc7.execute-api.us-east-1.amazonaws.com',\n        grant_type: 'client_credentials',\n        client_id: <your client id>,\n        client_secret: <your client secret>\n}\n```\nAdditionally verify that the following headers are set by the client you are using: \n```json\n{\n    \"Content-Type\": \"application/json\"\n}\n```\n\n3. Use the access token in the response to make requests to the Paigo API. Here is an example of the response:  \n```json   \n{\n            access_token: <your access token>,\n            expires_in: 86400,\n            token_type: 'Bearer'  \n}\n```\n4. To use Paigo API, add in the header of your request:\n```json\n{\n        Authorization: \"Bearer <your access token>\"\n}\n```\n\n## API Endpoints\nPaigo API has the following endpoint:\n- Production Environment API: `https://api.prod.paigo.tech`\n        "
  version: v1.10
  contact: {}
servers:
- url: https://api.prod.paigo.tech
  description: Product Environment API
tags:
- name: Usage
  description: Measure and collect usage data.
paths:
  /usage:
    post:
      operationId: Collect usage data
      summary: ''
      description: 'Collect usage data by API-based method.

        See <a href="https://docs.paigo.tech/measure-usage-and-collect-data/measure-and-collect-usage-data-at-production-scale">Measure and Collect Usage Data At Production Scale</a>

        for full documentation on Paigo <b>Usage Measurement and Collection</b>.'
      parameters:
      - name: invoice
        required: false
        in: query
        description: The invoice query parameter is used to create an invoice for the usage data body. It can _only_ be used with dimensions that have an `upfront` payment schedule and `last` aggregation method. If the dimension does not have these properties, the invoice will not be created and a `400` status code will be returned. Additionally, the customer for the usage must be actively enrolled in an offering in order to make use of the automated invoice, otherwise a `400` error will be returned. The body will not be loaded into the database on any `400` error. <br/><br/> The invoice created is independent of any `tiers`, or `entitlement` associated with the dimension, and will be created for the exact usage data sent in. <br/><br/> The invoice will be created for the difference between the usage data sent in, and the most recent usage data for the dimension. If the usage data sent in is less than the most recent usage data, a zero quantity line item will be created. For example if the most recent usage data for a dimension is `5`, and the usage data sent in is `3`, a zero quantity line item will be created. If the usage data sent in is `7`, a `2` quantity line item will be created.
        example: true
        schema:
          type: boolean
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUsageDto'
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicResponseDTO'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicResponseDTO'
      tags:
      - Usage
      security:
      - bearer: []
components:
  schemas:
    BasicResponseDTO:
      type: object
      properties:
        message:
          type: string
          description: A human readable message describing the outcome of the operation
          example: This is a sample API message. The exact message may vary based on the API behavior
      required:
      - message
    CreateUsageDto:
      type: object
      properties:
        dimensionId:
          type: string
          description: 'The unique identifier of the dimension this usage record is associated with.

            <br><br>

            Example: `''da9611bd-e0f3-4c0d-a754-fda5be730872''`'
        timestamp:
          type: string
          description: 'The timestamp of usage record in <a href="https://ijmacd.github.io/rfc3339-iso8601/">RFC3339</a>

            format with a 4-digit year.

            This is the time the usage occurred, or the end of the usage period.

            <br><br>

            Example: `"2023-02-08T19:24:10Z"`'
        customerId:
          type: string
          description: 'The unique identifier of the customer this usage record attributes to.

            <br><br>

            Example: `"e8366954-6f36-47e9-8431-ac95f88b5cc7"`'
        recordValue:
          type: string
          description: 'The amount of the usage on this record.

            Numerical values are represented as strings to avoid precision loss.

            <br><br>

            Example: `"0.87"`'
        metadata:
          type: object
          description: 'An optional key-value map of additional metadata to associate with this usage record.

            Additional metadata to be stored on the usage record,

            such as environment, purpose, owner, developer, contract number,

            or any arbitrary data to be associated with this usage record.

            Metadata can be used for analytics purpose.

            <br><br>

            Example `{"environment": "staging", "purpose": "proof-of-concept", "owner": "John Doe"}`'
      required:
      - dimensionId
      - timestamp
      - customerId
      - recordValue
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: oauth2
      in: Header
      description: Use bearer token to authenticate `Bearer <your access token>`
      flows:
        clientCredentials:
          tokenUrl: https://auth.paigo.tech/oauth/token
          scopes: {}