The Invoice API from Aqueduct — 6 operation(s) for invoice.
openapi: 3.0.0
info:
version: 1.0.0
title: Aqueduct API Reference AccountOwner Invoice API
description: The Aqueduct API is organized around REST. Aqueduct's API allows users to bill, invoice, and quote for usage based business models.
servers:
- url: https://api.tryaqueduct.com/v1
tags:
- name: Invoice
paths:
/invoices:
post:
summary: Create a new invoice
operationId: createInvoice
tags:
- Invoice
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
properties:
customerId:
description: Id of the account owner being billed
type: string
externalId:
description: A user-provided identifier for the object
anyOf:
- type: string
- nullable: true
currency:
description: Three-letter ISO currency code. Must be a supported currency.
enum:
- USD
- CAD
type: string
dueDate:
description: Due date for the invoice. When unspecified, defaults to the organization's default payment terms
example: '2022-08-01'
type: string
description:
description: A memo to display in the "notes" section of the invoice pdf
type: string
metadata:
additionalProperties: true
type: object
lineItems:
items:
properties:
description:
description: Name of the line item. This will be displayed to your customers in the invoice.
type: string
amount:
description: The amount to charge for this line item
type: number
tableRowDisplayFields:
description: Used for displaying the line items as a table in the invoice pdf
items:
properties:
name:
description: Column name of the property
type: string
value:
description: value to display in the table
type: string
type: object
type: array
accountingFields:
description: Used for syncing data into accounting integrations, e.g. Quickbooks or Sage Intacct
items:
properties:
name:
description: field name
type: string
value:
description: field value
type: string
type: object
type: array
externalId:
description: A user-provided identifier for the object
anyOf:
- type: string
- nullable: true
required:
- description
- amount
type: object
type: array
productId:
description: Id of the Product being billed for
type: string
sendEmail:
description: If true, will send the invoice to the customer via email immediately
type: boolean
required:
- customerId
- currency
- lineItems
- productId
additionalProperties: false
type: object
responses:
'201':
description: Invoice is created successfully
content:
application/json:
schema:
description: Used to record the amount owed by customers
example: '{"a":2,"b":3}'
properties:
id:
description: A unique identifier for the object
type: string
createdAt:
description: Time at which the object was created.
type: string
invoiceNo:
type: string
currency:
description: Three-letter ISO currency code. Must be a supported currency.
enum:
- USD
- CAD
type: string
customerId:
description: Id of the account owner being billed
type: string
externalId:
description: A user-provided identifier for the object
anyOf:
- type: string
- nullable: true
status:
description: Current states of the invoice
enum:
- outstanding
- void
- paid
- uncollectible
- draft
- paymentInitiated
- overdue
- sent
type: string
pdfUrl:
description: URL to fetch the invoice pdf (note that this still requires authentication)
type: string
dueDate:
description: Due date for the invoice. When unspecified, defaults to the organization's default payment terms
example: '2022-08-01'
type: string
description:
description: A memo to display in the "notes" section of the invoice pdf
type: string
metadata:
additionalProperties: true
type: object
lineItems:
items:
properties:
description:
description: Name of the line item. This will be displayed to your customers in the invoice.
type: string
createdAt:
description: Time at which the object was created.
type: string
invoiceId:
description: ID of the invoice that contains this line item.
type: string
amount:
description: The amount to charge for this line item
type: number
tableRowDisplayFields:
description: Used for displaying the line items as a table in the invoice pdf
items:
properties:
name:
description: Column name of the property
type: string
value:
description: value to display in the table
type: string
type: object
type: array
accountingFields:
description: Used for syncing data into accounting integrations, e.g. Quickbooks or Sage Intacct
items:
properties:
name:
description: field name
type: string
value:
description: field value
type: string
type: object
type: array
externalId:
description: A user-provided identifier for the object
anyOf:
- type: string
- nullable: true
required:
- description
- invoiceId
- amount
type: object
type: array
required:
- id
- createdAt
- currency
- customerId
- status
- lineItems
type: object
get:
summary: Retrieve a list of invoices
operationId: getInvoices
tags:
- Invoice
security:
- bearerAuth: []
parameters:
- in: query
name: accountOwnerId
required: false
description: Used to get the invoices for a given AccountOwner (customer)
example: owner_01FSSVRVGQ7GGB13815DE3F518
schema:
type: string
- in: query
name: externalId
required: false
description: Used to get the invoices matching the provided externalId
schema:
type: string
responses:
'200':
description: Returns a list of invoices that matched the parameters provided
content:
application/json:
schema:
type: array
items:
$ref: '#/paths/~1invoices/post/responses/201/content/application~1json/schema'
/invoices/{invoiceId}/invoicelineitems:
post:
summary: Add a new line item
operationId: createInvoiceLineItem
tags:
- Invoice
security:
- bearerAuth: []
parameters:
- in: path
name: invoiceId
required: true
description: The invoice id we're adding the new InvoiceLineItem to
example: inv_01FSSVRVGQ7GGB13815DE3F518
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
properties:
description:
description: Name of the line item. This will be displayed to your customers in the invoice.
type: string
amount:
description: The amount to charge for this line item
type: number
tableRowDisplayFields:
description: Used for displaying the line items as a table in the invoice pdf
items:
properties:
name:
description: Column name of the property
type: string
value:
description: value to display in the table
type: string
type: object
type: array
accountingFields:
description: Used for syncing data into accounting integrations, e.g. Quickbooks or Sage Intacct
items:
properties:
name:
description: field name
type: string
value:
description: field value
type: string
type: object
type: array
externalId:
description: A user-provided identifier for the object
anyOf:
- type: string
- nullable: true
required:
- description
- amount
type: object
responses:
'201':
description: InvoiceLineItem is created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/InvoiceLineItem'
/invoices/{invoiceId}/send:
post:
summary: Send an Invoice via email
description: Note that all the parameters to this endpoint are overrides – there are default parameters provided from the Organization's email settings
operationId: sendInvoice
tags:
- Invoice
security:
- bearerAuth: []
parameters:
- in: path
name: invoiceId
required: true
description: The id of the Invoice to send
example: inv_01FSSVRVGQ7GGB13815DE3F518
schema:
type: string
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
subject:
type: string
description: Subject of the email to be sent.
message:
type: string
description: HTML message to be added in the email body.
recipients:
type: array
description: The list of recipients for this email.
items:
type: string
example:
- foo@example.com
- bar@example.com
markAsSent:
type: boolean
description: When true, the invoice will be marked as sent and exit the draft state. Defaults to true. You can set it to false when sending test emails
responses:
'204':
description: Indicates that the invoice was sent successfully
/invoices/{invoiceId}/refund:
post:
summary: Refund an Invoice
description: Refunds an invoice if possible (e.g. credit card payments). Will otherwise return a 400
operationId: refundInvoice
tags:
- Invoice
security:
- bearerAuth: []
parameters:
- in: path
name: invoiceId
required: true
description: The id of the Invoice to refund
example: inv_01FSSVRVGQ7GGB13815DE3F518
schema:
type: string
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
amount:
type: number
description: The amount to refund. Cannot exceed the invoice total
responses:
'204':
description: Indicates that the invoice was refunded successfully
/invoices/{invoiceId}/void:
post:
summary: Void an Invoice
description: Marks an invoice as void.
operationId: voidInvoice
tags:
- Invoice
security:
- bearerAuth: []
parameters:
- in: path
name: invoiceId
required: true
description: The id of the Invoice to void
example: inv_01FSSVRVGQ7GGB13815DE3F518
schema:
type: string
responses:
'204':
description: Indicates that the invoice was voided successfully
/invoices/{invoiceId}:
get:
summary: Retrieve an Invoice
operationId: getInvoice
tags:
- Invoice
security:
- bearerAuth: []
parameters:
- in: path
name: invoiceId
required: true
description: The id of the Invoice to retrieve
example: inv_01FSSVRVGQ7GGB13815DE3F518
schema:
type: string
responses:
'200':
description: Returns the requested Invoice
content:
application/json:
schema:
$ref: '#/paths/~1invoices/post/responses/201/content/application~1json/schema'
components:
securitySchemes:
bearerAuth:
type: apiKey
name: Authorization
in: header