Documentation
Documentation
https://docs.paigo.tech/
GettingStarted
https://docs.paigo.tech/overview/getting-started-with-paigo
OpenAPI Specification
openapi: 3.0.0
info:
title: Paigo Customers 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: Customers
description: Manage customers in Paigo.
paths:
/customers:
get:
operationId: Get all Customers
summary: ''
description: List all customers created in this account
parameters: []
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReadAllCustomerResponseDTO'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
tags:
- Customers
security:
- bearer: []
post:
operationId: Create a customer
summary: ''
description: Create a customer
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCustomerDto'
responses:
'201':
description: Customer Created
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCustomerResponseDto'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
tags:
- Customers
security:
- bearer: []
/customers/{customerId}/children/{childId}:
post:
operationId: Assign a child to a customer
summary: ''
description: Assign a child to a customer
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateChildRowDto'
responses:
'201':
description: Child Added
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
tags:
- Customers
security:
- bearer: []
delete:
operationId: Remove a child from a customer
summary: ''
description: Remove a child from parent
parameters: []
responses:
'200':
description: Child Removed
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
tags:
- Customers
security:
- bearer: []
put:
operationId: Update a child to a customer
summary: ''
description: Update child relationship
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateChildRowDto'
responses:
'200':
description: Child Updated
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
tags:
- Customers
security:
- bearer: []
/customers/{customerId}:
get:
operationId: Get a customer by ID
summary: ''
description: Find one customer
parameters:
- name: customerId
required: true
in: path
description: 'The unique identifier assigned by Paigo.<br><br> Example: `f8e8c18c-0a59-40f4-bf72-356090366355`'
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReadCustomerResponseDTO'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
'404':
description: Customer Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message
example: 'Customer with ID: 807867e0-26ca-4831-846b-a670224db055 not found'
error:
type: string
description: The error name
example: Not Found
statusCode:
type: number
description: The HTTP status code
example: 404
externalDocs:
description: MDN Documentation Reference
url: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404
example:
message: 'Customer with ID: 807867e0-26ca-4831-846b-a670224db055 not found'
error: Not Found
statusCode: 404
required:
- message
- error
- statusCode
tags:
- Customers
security:
- bearer: []
put:
operationId: Update a customer
summary: ''
description: Update a customer
parameters:
- name: customerId
required: true
in: path
description: 'The unique identifier assigned by Paigo.<br><br> Example: `f8e8c18c-0a59-40f4-bf72-356090366355`'
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCustomerDto'
responses:
'200':
description: Customer Updated
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCustomerDto'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
'404':
description: Customer Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message
example: 'Customer with ID: 807867e0-26ca-4831-846b-a670224db055 not found'
error:
type: string
description: The error name
example: Not Found
statusCode:
type: number
description: The HTTP status code
example: 404
externalDocs:
description: MDN Documentation Reference
url: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404
example:
message: 'Customer with ID: 807867e0-26ca-4831-846b-a670224db055 not found'
error: Not Found
statusCode: 404
required:
- message
- error
- statusCode
tags:
- Customers
security:
- bearer: []
delete:
operationId: Delete a customer
summary: ''
description: Delete a customer
parameters:
- name: customerId
required: true
in: path
description: 'The unique identifier assigned by Paigo.<br><br> Example: `f8e8c18c-0a59-40f4-bf72-356090366355`'
schema:
type: string
responses:
'200':
description: Customer Deleted
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteCustomerResponseDto'
'404':
description: Customer Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message
example: 'Customer with ID: 807867e0-26ca-4831-846b-a670224db055 not found'
error:
type: string
description: The error name
example: Not Found
statusCode:
type: number
description: The HTTP status code
example: 404
externalDocs:
description: MDN Documentation Reference
url: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404
example:
message: 'Customer with ID: 807867e0-26ca-4831-846b-a670224db055 not found'
error: Not Found
statusCode: 404
required:
- message
- error
- statusCode
tags:
- Customers
security:
- bearer: []
/customers/{customerId}/refunds:
post:
operationId: Create a refund for customer
summary: ''
description: 'Create Customer Refund
<br><br>
<b>NOTE:</b> This endpoint currently only supports Stripe for a refund channel. Customers with manual payments will cause an 400 error response.'
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCustomerRefundDto'
responses:
'201':
description: Refund Created
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCustomerRefundResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
tags:
- Customers
security:
- bearer: []
get:
operationId: Get a refund for customer
summary: ''
description: 'Get customer refunds
<br><br>
<b>NOTE:</b> This endpoint currently only supports Stripe for a refund channel. Customers with manual payments will cause an 400 error response.'
parameters: []
responses:
'200':
description: Refunds found
content:
application/json:
schema:
$ref: '#/components/schemas/FindCustomerRefundsResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
tags:
- Customers
security:
- bearer: []
/customers/{customerId}/enrollment:
get:
operationId: Get a Customer Enrollment
summary: ''
description: Get a Customer Enrollment
parameters:
- name: customerId
required: true
in: path
description: 'The unique identifier assigned by Paigo.<br><br> Example: `f8e8c18c-0a59-40f4-bf72-356090366355`'
schema:
type: string
responses:
'200':
description: Enrollment Found
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerEnrollmentResponseDto'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
'404':
description: Customer Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message
example: 'Customer with ID: 807867e0-26ca-4831-846b-a670224db055 not found'
error:
type: string
description: The error name
example: Not Found
statusCode:
type: number
description: The HTTP status code
example: 404
externalDocs:
description: MDN Documentation Reference
url: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404
example:
message: 'Customer with ID: 807867e0-26ca-4831-846b-a670224db055 not found'
error: Not Found
statusCode: 404
required:
- message
- error
- statusCode
tags:
- Customers
security:
- bearer: []
put:
operationId: Update Customer Offering Enrollment
summary: ''
description: Update Customer Enrollment
parameters:
- name: customerId
required: true
in: path
description: 'The unique identifier assigned by Paigo.<br><br> Example: `f8e8c18c-0a59-40f4-bf72-356090366355`'
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCustomerEnrollmentDto'
responses:
'200':
description: Customer Enrollment Updated
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCustomerRefundResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
'404':
description: Customer Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message
example: 'Customer with ID: 807867e0-26ca-4831-846b-a670224db055 not found'
error:
type: string
description: The error name
example: Not Found
statusCode:
type: number
description: The HTTP status code
example: 404
externalDocs:
description: MDN Documentation Reference
url: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404
example:
message: 'Customer with ID: 807867e0-26ca-4831-846b-a670224db055 not found'
error: Not Found
statusCode: 404
required:
- message
- error
- statusCode
tags:
- Customers
security:
- bearer: []
/customers/{customerId}/payments:
get:
operationId: Get payments for customer
summary: ''
description: 'Get customer payments
<br><br>
<b>NOTE:</b> This endpoint currently only supports Stripe for a payment channel. Customers with manual payments will cause an 400 error response.'
parameters:
- name: invoiceId
required: false
in: query
description: 'The Paigo invoiceId associated with the stripe payment. Can be undefined.
This operation instructs paigo to search for payments with the given invoiceId in the metadata of the payment intent.
<br><br>
Example: `"476b84a0-bba7-4e05-9040-59cffdff493a"`'
example: 476b84a0-bba7-4e05-9040-59cffdff493a
externalDocs:
url: https://docs.paigo.tech/invoice-and-process-payment/issue-invoice
description: 'Paigo API Reference: Issue Invoice'
schema:
type: string
responses:
'200':
description: Payments Found
content:
application/json:
schema:
$ref: '#/components/schemas/FindCustomerPaymentsResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
tags:
- Customers
security:
- bearer: []
/customers/{customerId}/stripePortal:
get:
operationId: Get Stripe Portal for customer
summary: ''
parameters: []
responses:
'200':
description: Payments Found
content:
application/json:
schema:
$ref: '#/components/schemas/GetCustomerStripePortalResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
tags:
- Customers
security:
- bearer: []
/customers/{customerId}/freeTrial:
put:
operationId: Update free trial
summary: ''
description: Update a free trial of a customer
parameters:
- name: customerId
required: true
in: path
description: 'The unique identifier assigned by Paigo.<br><br> Example: `f8e8c18c-0a59-40f4-bf72-356090366355`'
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateFreeTrialDto'
responses:
'200':
description: Customer free trial updated
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateFreeTrialResponseDto'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
'404':
description: Customer Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message
example: 'Customer with ID: 807867e0-26ca-4831-846b-a670224db055 not found'
error:
type: string
description: The error name
example: Not Found
statusCode:
type: number
description: The HTTP status code
example: 404
externalDocs:
description: MDN Documentation Reference
url: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404
example:
message: 'Customer with ID: 807867e0-26ca-4831-846b-a670224db055 not found'
error: Not Found
statusCode: 404
required:
- message
- error
- statusCode
tags:
- Customers
security:
- bearer: []
/customers/{customerId}/usage:
get:
operationId: Get usage data for a customer
summary: ''
description: Get usage data for a customer
parameters:
- name: customerId
required: true
in: path
description: 'The unique identifier assigned by Paigo.<br><br> Example: `f8e8c18c-0a59-40f4-bf72-356090366355`'
schema:
type: string
- name: aggregationInterval
required: false
in: query
description: 'The aggregation interval to use for the query.
<br><br>
Default: the aggregation interval defined in the dimension definition.'
schema:
enum:
- none
- hour
- day
- month
type: string
- name: ignoreEnrollmentDate
required: false
in: query
description: 'If the current offering enrollment date should be ignored for the response data. Enables looking at usage prior to the enrollment date.
<br><br>
Default: `false`'
schema:
type: string
- name: aggregationPurpose
required: false
in: query
description: 'The aggregation purpose to use for the query. Enum: `"billing"`, `"metering"`
<br><br>
Default: "billing"'
schema:
enum:
- billing
- metering
type: string
- name: endTime
required: false
in: query
description: 'The end time of the time range to query.
The time range is inclusive of the start time and exclusive of the end time.
The end time must be after the start time.
The end time must be before the current time.
The end time must be in <a href="https://ijmacd.github.io/rfc3339-iso8601/">RFC3339</a> format.
<br><br>
Example: `"2020-01-01T00:00:00Z"`'
schema:
type: string
- name: startTime
required: false
in: query
description: 'The end time of the time range to query.
The time range is inclusive of the start time and exclusive of the end time.
The end time must be after the start time.
The end time must be before the current time.
The end time must be in <a href="https://ijmacd.github.io/rfc3339-iso8601/">RFC3339</a> format.
<br><br>
Example: `"2020-01-01T00:00:00Z"`'
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReadCustomerUsageData'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
'404':
description: Customer Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundException'
tags:
- Customers
security:
- bearer: []
/customers/{customerId}/token:
get:
operationId: Get a customer auth token
summary: ''
description: Get a token to allow SaaS customers to view their billing data in paigo securely
parameters:
- name: customerId
required: true
in: path
description: 'The unique identifier assigned by Paigo.<br><br> Example: `248fc14e-9934-4d3c-a39f-ce43cbb3f7b2`'
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerAuthenticationTokenResponse'
'404':
description: Customer Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message
example: 'Customer with ID: 807867e0-26ca-4831-846b-a670224db055 not found'
error:
type: string
description: The error name
example: Not Found
statusCode:
type: number
description: The HTTP status code
example: 404
externalDocs:
description: MDN Documentation Reference
url: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404
example:
message: 'Customer with ID: 807867e0-26ca-4831-846b-a670224db055 not found'
error: Not Found
statusCode: 404
required:
- message
- error
- statusCode
tags:
- Customers
security:
- bearer: []
/customers/{customerId}/transactions:
post:
operationId: Create a wallet transaction
summary: ''
description: Commit a transaction to the ledger for a customer. This will update thier credit balances
parameters:
- name: customerId
required: true
in: path
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCreditDto'
responses:
'201':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
tags:
- Customers
get:
operationId: Get customer credit ledger
summary: ''
description: Get the ledger of wallet transactions applied to a customer
parameters:
- name: customerId
required: true
in: path
description: 'The unique identifier assigned by Paigo.<br><br> Example: `f8e8c18c-0a59-40f4-bf72-356090366355`'
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreditLedgerResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
'404':
description: Customer Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundException'
tags:
- Customers
components:
schemas:
CountBasedConsumptionUnit:
type: object
properties:
unit:
type: string
enum:
- count-based
description: A dimensionless unit for a dimension of type count-based
examples:
- count-based
type:
type: string
enum:
- count
description: A string that indicates the type of consumption unit
required:
- unit
- type
Address:
type: object
properties:
countryCode:
type: string
description: 'Two-letter country code
<br><br>
Example: <br>
- `''US''`<br>
- `''DE''`<br>'
example: US
postalCode:
type: string
description: 'The postal code of the address. Typically, this is the country-specific.
<br><br>
Example: `"90210"`'
example: '90210'
city:
type: string
description: 'The city of the address
<br><br>
Example: `"Beverly Hills"`'
example: Beverly Hills
streetLineOne:
type: string
description: 'The first line of the street address
<br><br>
Example: `"1234 Main St"`'
example: 1234 Main St
streetLineTwo:
type: string
description: 'The second line of the street address
<br><br>
Example: `"Apt 1"`'
example: Apt 1
state:
type: string
description: 'Two-letter state code
<br><br>
Example: <br>
- `''NY''`
- `''CA''`'
example: NY
required:
- countryCode
- postalCode
- city
- streetLineOne
- state
AggregatedUsageResponse:
type: object
properties:
offeringId:
type: string
description: The unique identifier of the offering.
dimensionId:
type: string
description: The unique identifier of a dimension.
usage:
description: Array of usage records group by aggregation time interval
type: array
items:
$ref: '#/components/schemas/UsageResponseDocument'
required:
- dimensionId
- usage
TimeBasedConsumptionUnit:
type: object
properties:
unit:
enum:
- second
- minute
- hour
- day
type: string
description: A unit of time for a dimension of type time-based
examples:
- second
- minute
- hour
- day
type:
type: string
enum:
- time
description: A string that indicates the type of consumption unit
required:
- unit
- type
UpdateFreeTrialDto:
type: object
properties:
offeringId:
type: string
freeTrialEndDate:
type: string
description: 'The end date of the free trial. Must be in the future and must be an RFC3339 date string.
<br><br>
Example: `"2021-01-01T00:00:00Z"`'
example: '2021-01-01T00:00:00Z'
freeTrialStartDate:
type: string
description: 'The start date of the free trial. Must be in the future and must be an RFC3339 date string. Optional to set, determines the free trial start date for a customer.
This is used during billing calculations to determine the proration amount for their free trial invoice.
<br><br>
Example: `"2021-01-01T00:00:00Z"`'
example: '2017-01-01T00:00:00Z'
required:
- freeTrialEndDate
CreateCreditDto:
type: object
properties:
transactionAmount:
type: string
description: 'The amount to credit the customer. Can be positive or negative. Customers cannot have a negative balance set via the API.
<br><br>
Example: `"100.00"`'
examples:
- '100.00'
- '100'
minimum: -1000000000
maximum: 1000000000
timestamp:
type: string
description: 'The timestamp of the credit. Optional. Will be set to right now UTC if not provided.
<br><br>
Example: `"2021-01-01T00:00:00.000Z"`'
example: '2021-01-01T00:00:00.000Z'
metadata:
type: object
description: 'The metadata to attach to the credit. Optional
<br><br>
Example: `{"key": "value"}`'
required:
- transactionAmount
ReadAllCustomerResponseDTO:
type: object
properties:
message:
type: string
descri
# --- truncated at 32 KB (112 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paigo/refs/heads/main/openapi/paigo-customers-api-openapi.yml