Skip to content
/
Creates an invoice

Creates an invoice

Request

POST {{baseURL}}/pay-int-api/invoices

This endpoint creates a new invoice for the merchant.

A newly created invoice is saved in Draft status. A draft invoice isn't visible to the customer yet. It can be freely edited, adding or changing line items, customer details, and settings like tax, shipping, and discounts before anything is sent.

The following is an example request.

POST {{baseURL}}/pay-int-api/invoices HTTP/1.1
Authorization: Bearer {{accessToken}}
x-api-version: 1.0
Content-Type: application/json
{
  "dueDate": "2026-08-31",
  "additionalNotes": "Extension permitted for 30 days.",
  "taxPercentage": 8.50,
  "shippingAmount": 129.99,
  "customer": {
    "firstName": "Alexandro",
    "lastName": "Peppared",
    "companyName": "Peppared Street Cafe",
    "email": "peppared@example.com"
  },
  "lineItems": [
    {
      "lineItemId": "3473cce6-6b6a-4cd3-b293-7280b17006a6",
      "quantity": 2,
      "unitTypeId": 1
    }
  ]
}

Once the invoice is ready, it can be published separately with POST /pay-int-api/invoices/publish, which is what actually sends it to the customer for payment.

See Also:
To list invoices, see GET /pay-int-api/invoices.
To retrieve an invoice by ID, see GET /pay-int-api/invoices/{invoiceId}.
To update an invoice, see PUT /pay-int-api/invoices/{invoiceId}.
To publish an invoice, see POST /pay-int-api/invoices/publish.

Security
Bearer
Headers
x-api-versionstring

Specifies the API version to use for the request.

Example: 1.0

Example:1.0
Bodyapplication/json

Specifies an invoice creation request.

dueDatestring or null, (date)

Specifies the date (in an ISO 8601 date only format) the invoice is due.

Examples: 2026-08-31

Example:"2026-08-31"
cardPaymentProcessorIdstring or null, (uuid)

Specifies an identifier for the credit card payment processor handling a card transaction.

Example: 78723ff2-d47e-460b-b838-d602bdf0e1bc

Example:"78723ff2-d47e-460b-b838-d602bdf0e1bc"
achPaymentProcessorIdstring or null, (uuid)

Specifies an identifier for the automated clearing house (ACH) payment processor handling a transaction.

Example: 9925a0b0-eb18-4d74-8967-7e0cf6af0729

Example:"9925a0b0-eb18-4d74-8967-7e0cf6af0729"
additionalNotesstring or null

Specifies additional notes or comments.

Example: Extension permitted for 30 days.

Example:"Extension permitted for 30 days."
shippingAmountnumber or null, (double)

Specifies the shipping amount (in USD).

Example: 129.99

Example:129.99
taxPercentagenumber or null, (double)

Specifies the tax percentage.

Example: 8.50 (as 8.50%)

Example:8.5
feesPercentagenumber or null, (double)

Specifies the fees percentage.

Example: 10.25 (as 10.25%)

Example:10.25
discountPercentagenumber or null, (double)

Specifies the discount percentage.

Example: 1.5 (as 1.5%)

Example:1.5
merchantContactInfoIdstring or null, (uuid)

Indicates the merchant’s stored contact information record used on invoices and payment flows.

Example: bdf4b5c6-7d8e-4f9a-0b1c-2d3e4f5a6b92

Example:"bdf4b5c6-7d8e-4f9a-0b1c-2d3e4f5a6b92"
customerIdstring or null, (uuid)

Specifies the customer identifier.

This is used when saving the payment method.
If this value is provided, the payment method is saved to the specified customer.
If this value is not provided, a new customer record is created.

Example: fd9198a4-eb6f-4620-9603-4f4638289de5

Example:"fd9198a4-eb6f-4620-9603-4f4638289de5"
achAllowFasterProcessingboolean or null

Specifies faster processing is allowed for the invoice's ACH payment.

If true, faster processing is allowed.
If false, faster processing is not allowed.

Example: true

Example:true
customerobject

Indicates the customer's information for the invoice.

lineItemsArray of objects or null

Line items for the invoice.

canPriceBeForceOverridedboolean or null

Specifies a line item's price can be force-overridden when publishing.

If true, a line item's unitPrice can override its catalog price even if the merchant's invoice settings would otherwise block it.
If false, a line item's unitPrice can only override its catalog price when the merchant's invoice settings allow it.

Example: true

Example:true
curl -i -X POST \
  https://developer.flute.com/_mock/api-reference/pay-int-api/invoices \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'x-api-version: 1.0' \
  -d '{
    "dueDate": "2026-08-31",
    "cardPaymentProcessorId": "78723ff2-d47e-460b-b838-d602bdf0e1bc",
    "achPaymentProcessorId": "9925a0b0-eb18-4d74-8967-7e0cf6af0729",
    "additionalNotes": "Extension permitted for 30 days.",
    "shippingAmount": 129.99,
    "taxPercentage": 8.5,
    "feesPercentage": 10.25,
    "discountPercentage": 1.5,
    "merchantContactInfoId": "bdf4b5c6-7d8e-4f9a-0b1c-2d3e4f5a6b92",
    "customerId": "fd9198a4-eb6f-4620-9603-4f4638289de5",
    "achAllowFasterProcessing": true,
    "customer": {
      "firstName": "Alexandro",
      "lastName": "Peppared",
      "companyName": "Peppared Street Cafe",
      "email": "peppared@example.com",
      "mobilePhoneNumber": "+14155552309",
      "isMobileNumberSmsNotificationsEnabled": true,
      "useBillingAsShippingAddress": true,
      "billingAddress": {
        "line1": "21 E. Main Street",
        "line2": "Apt. Block 6",
        "city": "Chicago",
        "zip": "60612",
        "countryId": 1,
        "stateId": 1,
        "stateName": "Illinois"
      },
      "shippingAddress": {
        "line1": "21 E. Main Street",
        "line2": "Apt. Block 6",
        "city": "Chicago",
        "zip": "60612",
        "countryId": 1,
        "stateId": 1,
        "stateName": "Illinois"
      }
    },
    "lineItems": [
      {
        "productName": "RollerMouse Wireless Mouse",
        "unitTypeId": 1,
        "unitPrice": 18.99,
        "id": "d0f6d7e8-9f0a-4b1c-2d3e-4f5a6b7c8d14",
        "lineItemId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "description": "RollerMouse Design Collection, Limited Edition Wireless Mouse",
        "sku": "24474771",
        "quantity": 10,
        "discountPercentage": 1.5,
        "totalAmount": 3219.45
      }
    ],
    "canPriceBeForceOverrided": true
  }'

Responses

OK

Bodyapplication/json
idstring, (uuid)

Indicates the invoice identifier.

Example: cef5c6d7-8e9f-4a0b-1c2d-3e4f5a6b7c03

Example:"cef5c6d7-8e9f-4a0b-1c2d-3e4f5a6b7c03"
Response
{
  "id": "cef5c6d7-8e9f-4a0b-1c2d-3e4f5a6b7c03"
}