Skip to main content
POST
/
v1
/
invoices
Create invoice
curl --request POST \
  --url https://api.useaira.com/v1/invoices/ \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "idempotencyKey": "<string>",
  "invoiceDate": "2023-12-25",
  "memo": "<string>",
  "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "externalCustomerId": "<string>",
  "paymentAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "idempotencyKey": "<string>",
  "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "paymentAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "contractId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "issuingAccount": {
    "tradeName": "<string>",
    "businessName": "<string>",
    "emails": [
      "jsmith@example.com"
    ],
    "taxId": "<string>",
    "taxIdType": "cnpj",
    "zipCode": "<string>",
    "street": "<string>",
    "number": "<string>",
    "neighborhood": "<string>",
    "city": "<string>",
    "state": "AC",
    "country": "Brasil",
    "complement": "<string>"
  },
  "billingAccount": {
    "tradeName": "<string>",
    "businessName": "<string>",
    "emails": [
      "jsmith@example.com"
    ],
    "taxId": "<string>",
    "taxIdType": "cnpj",
    "zipCode": "<string>",
    "street": "<string>",
    "number": "<string>",
    "neighborhood": "<string>",
    "city": "<string>",
    "state": "AC",
    "country": "Brasil",
    "complement": "<string>"
  },
  "invoiceAllocationStrategy": "single",
  "lastCalculatedAt": "2023-11-07T05:31:56Z",
  "invoiceNumber": "<string>",
  "invoiceDate": "2023-12-25",
  "memo": "<string>",
  "subtotalAmount": 123,
  "adjustmentAmount": 123,
  "totalAmount": 123,
  "discountAmount": 123,
  "status": "open",
  "isLocked": true,
  "failureReason": "erp_provider_not_supported",
  "source": "contract",
  "autoIssue": true,
  "amountDue": 123,
  "dueDate": "2023-12-25",
  "lineItemGroups": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "idempotencyKey": "<string>",
      "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "planId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "startDate": "2023-12-25",
      "endDate": "2023-12-25",
      "subtotalAmount": 123,
      "adjustmentAmount": 123,
      "totalAmount": 123,
      "discountAmount": 123,
      "lineItems": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "idempotencyKey": "<string>",
          "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "resourceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "lineItemGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "<string>",
          "scope": "credit_purchase",
          "startDate": "2023-12-25",
          "endDate": "2023-12-25",
          "totalUsage": 123,
          "usageFormat": "unit",
          "subtotalAmount": 123,
          "adjustmentAmount": 123,
          "totalAmount": 123,
          "discountAmount": 123,
          "metadata": {
            "type": "metric",
            "billingModel": "in_full",
            "priceTierDivision": "unique_tier"
          },
          "subLineItems": [
            {
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "type": "fixed_price",
              "name": "<string>",
              "description": "<string>",
              "usage": 123,
              "amount": 123,
              "metadata": {
                "type": "fixed_price",
                "fixedPrice": 123
              }
            }
          ],
          "adjustments": [
            {
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "name": "<string>",
              "type": "monetary_discount",
              "amount": 123
            }
          ],
          "itemId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
      ]
    }
  ],
  "standaloneLineItems": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "idempotencyKey": "<string>",
      "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "resourceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "lineItemGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "scope": "credit_purchase",
      "startDate": "2023-12-25",
      "endDate": "2023-12-25",
      "totalUsage": 123,
      "usageFormat": "unit",
      "subtotalAmount": 123,
      "adjustmentAmount": 123,
      "totalAmount": 123,
      "discountAmount": 123,
      "metadata": {
        "type": "metric",
        "billingModel": "in_full",
        "priceTierDivision": "unique_tier"
      },
      "subLineItems": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "type": "fixed_price",
          "name": "<string>",
          "description": "<string>",
          "usage": 123,
          "amount": 123,
          "metadata": {
            "type": "fixed_price",
            "fixedPrice": 123
          }
        }
      ],
      "adjustments": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "<string>",
          "type": "monetary_discount",
          "amount": 123
        }
      ],
      "itemId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.useaira.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
X-API-KEY
string
header
required

API Key Authentication.

Body

application/json

Schema for creating a one-off invoice. Exactly one of customerId or externalCustomerId must be provided. When paymentAccountId is omitted or null, one of the customer payment accounts is used.

​
idempotencyKey
string
required

A unique idempotency key associated with the invoice.

Minimum string length: 1
Pattern: ^[a-zA-Z0-9_-]+$
​
invoiceDate
string<date>
required

The closing date of the invoice. It represents the end date of the period covered by the invoice.

​
memo
string
required

The memo to attach to the invoice.

​
customerId
string<uuid> | null

The unique identifier of the customer in our system that this invoice will be associated with.

​
externalCustomerId
string | null

The external identifier of the customer that this invoice will be associated with.

Pattern: ^[a-zA-Z0-9_-]+$
​
paymentAccountId
string<uuid> | null

The unique identifier of the payment account that will be used as the billing account. When omitted or null, one of the customer payment accounts is used.

Response

Default Response

​
id
string<uuid>
required
​
idempotencyKey
string
required
​
customerId
string<uuid>
required
​
paymentAccountId
string<uuid>
required
​
contractId
string<uuid> | null
required
​
issuingAccount
object
required
​
billingAccount
object
required
​
invoiceAllocationStrategy
enum<string>
required
Available options:
single,
percent_split
​
lastCalculatedAt
string<date-time> | null
required
​
invoiceNumber
string
required
​
invoiceDate
string<date>
required
​
memo
string | null
required
​
subtotalAmount
number
required
​
adjustmentAmount
number
required
​
totalAmount
number
required
​
discountAmount
number
required
​
status
enum<string>
required
Available options:
open,
in_review,
issued,
synced,
pending,
paid,
overdue,
canceled,
failed
​
isLocked
boolean
required
​
failureReason
enum<string> | null
required
Available options:
erp_provider_not_supported,
omie_settings_not_found,
no_contract_found_in_omie_for_contract_number,
contract_sync_not_found,
contract_without_processor_id,
omie_mapping_basis_invalid,
unexpected_error_on_invoice_sync,
omie_service_mapping_not_found,
omie_service_mappings_not_found_on_omie,
omie_service_mapping_invalid,
invoice_not_found,
invoice_has_no_contract,
unknown,
payment_invoice_not_found,
invoice_account_not_found,
payment_account_not_found,
insufficient_payment_amount,
failed_to_upload_bank_slip,
payment_unknown,
null
​
source
enum<string>
required
Available options:
contract,
one_off,
import
​
autoIssue
boolean
required
​
amountDue
number | null
required
​
dueDate
string<date> | null
required
​
lineItemGroups
object[]
required
​
standaloneLineItems
object[]
required