Aqueduct

Aqueduct API

REST API to bill, invoice, and quote for usage-based business models — account owners, price models, billable events, invoices, line items, products, subscriptions, provisioning, and webhooks.

GitHub OpenAPI

Documentation

📖
Documentation
https://docs.tryaqueduct.com/reference
📖
APIReference
https://docs.tryaqueduct.com/reference
📖
GettingStarted
https://docs.tryaqueduct.com/reference/getting-started-with-your-api

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/aqueduct/refs/heads/main/openapi/aqueduct-openapi.json

Other Resources

🔗
Overlay
https://raw.githubusercontent.com/api-evangelist/aqueduct/refs/heads/main/overlays/aqueduct-openapi-overlay.yaml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/aqueduct/refs/heads/main/data-model/aqueduct-data-model.yml
🔗
APIsJSON
https://raw.githubusercontent.com/api-evangelist/aqueduct/refs/heads/main/apis.yml

OpenAPI Specification

aqueduct-openapi.json Raw ↑ 
{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.0",
    "title": "Aqueduct API Reference",
    "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"
    }
  ],
  "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 \u2013 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"
                }
              }
            }
          }
        }
      }
    },
    "/accountOwners": {
      "post": {
        "summary": "Create a new account owner",
        "operationId": "createAccountOwner",
        "tags": [
          "AccountOwner"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Name of the account owner (person or organization)",
                    "example": "Bobby Buyer"
                  },
                  "email": {
                    "type": "string",
                    "description": "Contact email address - usually the billing email of the organization",
                    "example": "bobby@foocorp.com"
                  },
                  "phoneNumber": {
                    "type": "string",
                    "example": "555-555-5555"
                  },
                  "address": {
                    "$ref": "#/components/schemas/Address"
                  },
                  "tags": {
                    "type": "array",
                    "description": "tags to associate with this account owner",
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "customer",
                      "payout-target"
                    ]
                  },
                  "accountType": {
                    "type": "string",
                    "description": "AccountsReceivable (for customers), PayoutAccount. Can also be CreditsGivenAccount, CreditsReceivedAccount, CashAccount, ProcessingFeesAccount, RevenueAccount, but generally these are not created via API"
                  },
                  "stripeCustomerId": {
                    "$ref": "#/components/schemas/stripeCustomerId"
                  },
                  "intacctCustomerId": {
                    "type": "string",
                    "description": "The Sage Intacct customer Id associated with this account owner. Will be used for syncing invoices",
                    "example": "C1234"
                  },
                  "parentAccountOwnerId": {
                    "description": "ID of the AccountOwner that acts as the parent of this AccountOwner",
                    "example": "owner_01FSSVRVGQ7GGB13815DE3F518"
                  },
                  "payerAccountOwnerId": {
                    "description": "ID of the AccountOwner that pays on behalf of this AccountOwner. Note that all invoices will be sent to the payer directly.",
                    "example": "owner_01FSSVRVGQ7GGB13815DE3F518"
                  },
                  "externalId": {
                    "$ref": "#/components/schemas/externalId",
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Account is created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountOwner"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "Retrieve a list of account owners",
        "operationId": "getAccountOwners",
        "tags": [
          "AccountOwner"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "accountType",
            "required": false,
            "description": "The account type to fetch",
            "example": "PayoutAccount",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "tag",
            "required": false,
            "description": "The tag to filter by",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "externalId",
            "required": false,
            "description": "Used to get the AccountOwners matching the provided externalId",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns a list of account owners that matched the parameters provided",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/AccountOwner"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/accountOwners/{accountOwnerId}": {
      "get": {
        "summary": "Retrieve an AccountOwner",
        "operationId": "getAccountOwner",
        "tags": [
          "AccountOwner"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "accountOwnerId",
            "required": true,
            "description": "The id of the AccountOwner to retrieve",
            "example": "acct_01FSSVRVGQ7GGB13815DE3F518",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns the requested AccountOwner",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountOwner"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Update an AccountOwner",
        "operationId": "updateAccountOwner",
        "tags": [
          "AccountOwner"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "accountOwnerId",
            "required": true,
            "description": "The id of the AccountOwner to update",
            "example": "acct_01FSSVRVGQ7GGB13815DE3F518",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "$ref": "#/components/schemas/accountOwnerName"
                  },
                  "email": {
                    "type": "string",
                    "description": "Contact email address - usually the billing email of the organization",
                    "example": "bobby@foocorp.com"
                  },
                  "phoneNumber": {
                    "type": "string",
                    "example": "555-555-5555"
                  },
                  "stripeCustomerId": {
                    "$ref": "#/components/schemas/stripeCustomerId"
                  },
                  "address": {
                    "$ref": "#/components/schemas/Address"
                  },
                  "tags": {
                    "$ref": "#/components/schemas/AccountOwnerTags"
                  },
                  "intacctCustomerId": {
                    "type": "string",
                    "description": "The Sage Intacct customer Id associated with this account owner. Will be used for syncing invoices",
                    "example": "C1234"
                  },
                  "parentAccountOwnerId": {
                    "description": "ID of the AccountOwner that acts as the parent of this AccountOwner",
                    "example": "owner_01FSSVRVGQ7GGB13815DE3F518"
                  },
                  "payerAccountOwnerId": {
                    "description": "ID of the AccountOwner that pays on behalf of this AccountOwner. Note that all invoices will be sent to the payer directly.",
                    "example": "owner_01FSSVRVGQ7GGB13815DE3F518"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Returns the AccountOwner that was updated in the request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountOwner"
                }
              }
            }
          }
        }
      }
    },
    "/accountOwners/{accountOwnerId}/customerPortal": {
      "post": {
        "summary": "Generate a Customer Portal link.",
        "operationId": "createCustomerPortalLink",
        "tags": [
          "AccountOwner"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "accountOwnerId",
            "required": true,
            "description": "The id of the AccountOwner (customer)",
            "example": "owner_01FSSVRVGQ7GGB13815DE3F518",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "expiresAt": {
                    "type": "string",
                    "description": "DateTime corresponding to when the Customer Portal session should expire. Defaults to 30 minutes from now. Pass in `null` to have the session never expire"
             

# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/aqueduct/refs/heads/main/openapi/aqueduct-openapi.json