Nutshell Invoices API
Invoice documents, their status transitions and payment/completion metadata. 3 operation(s) across 3 path(s).
OpenAPI Specification
openapi: 3.0.0
info:
title: Nutshell Invoices API
description: The most powerful API in the world
version: 2.0.0
contact:
name: Nutshell Developers
url: https://developers.nutshell.com
servers:
- url: https://app.nutshell.com/rest
description: Nutshell REST API
tags:
- name: Invoices
paths:
/invoices/{id}:
get:
tags:
- Invoices
summary: Get an invoice
description: Get a single invoice by the ID provided.
operationId: b9c9d23692da5d58d025a29911416b8f
parameters:
- name: id
in: path
description: Invoice ID
required: true
schema:
type: string
responses:
'200':
description: Invoice
content:
application/json:
schema:
properties:
invoices:
type: array
items:
$ref: '#/components/schemas/Invoice'
example:
- id: 789-quotes
type: invoices
number: 1000-01
displayStatus: ACCEPTED
total:
amount: '3200.50'
currency: USD
formatted: $3,200.50
productLineItems:
- id: 1-quoteProductLineItems
position: 0
product: 100-products
name: Consulting Services
description: Monthly consulting retainer
sku: CONS-001
quantity: 2
term: null
price:
amount: '1500.00'
currency: USD
formatted: $1,500.00
total:
amount: '3000.00'
currency: USD
formatted: $3,000.00
discountUnit: null
discountNumber: null
subtotalLineItems:
- id: 1-quoteSubtotalLineItems
position: 0
label: Tax
modifierUnit: '%'
modifierValue: 6.5
operation: +
total:
amount: '200.50'
currency: USD
formatted: $200.50
recipient:
id: 321-contacts
name: Jane Doe
email: jane@example.com
validThroughTime: '2024-12-31T23:59:59Z'
createdTime: '2024-01-15T10:30:00Z'
publishedTime: '2024-01-16T14:20:00Z'
sentTime: '2024-01-17T09:15:00Z'
paidTime: '2024-01-20T16:45:00Z'
acceptedName: Jane Customer
acceptedEmail: jane@example.com
completionComment: Paid via ACH
deletedTime: null
links:
lead: 456-leads
type: object
security:
- basicAuth: []
/invoices/{id}/status:
post:
tags:
- Invoices
summary: Update the status of an invoice
description: Updates an invoice to a native Nutshell status (READY, SENT, REVOKED, ACCEPTED, ARCHIVED).
ACCEPTED marks the invoice as paid. Optional comment is stored as payment/completion metadata.
operationId: d35e25a23af6446bdc10dffb07a59c79
parameters:
- name: id
in: path
description: Invoice ID
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
required:
- status
properties:
status:
type: string
enum:
- READY
- SENT
- REVOKED
- ACCEPTED
- ARCHIVED
example: ACCEPTED
comment:
description: Payment or completion note (invoices only, on ACCEPTED or REVOKED)
type: string
example: Paid via ACH
acceptedName:
description: Optional name recorded when marking the invoice paid
type: string
acceptedEmail:
description: Optional email recorded when marking the invoice paid
type: string
type: object
responses:
'200':
description: Invoice
content:
application/json:
schema:
properties:
invoices:
type: array
items:
$ref: '#/components/schemas/Invoice'
example:
- id: 789-quotes
type: invoices
number: 1000-01
total:
amount: '3200.50'
currency: USD
formatted: $3,200.50
validThroughTime: '2024-12-31T23:59:59Z'
createdTime: '2024-01-15T10:30:00Z'
publishedTime: '2024-01-16T14:20:00Z'
sentTime: '2024-01-17T09:15:00Z'
paidTime: '2024-01-20T16:45:00Z'
acceptedName: Jane Customer
acceptedEmail: jane@example.com
completionComment: Paid via ACH
deletedTime: null
links:
lead: 456-leads
type: object
security:
- basicAuth: []
/invoices:
get:
tags:
- Invoices
summary: Get a list of invoices
operationId: 44a63cb9277feafb979ccef9038cd6d5
parameters:
- name: filter[lead]
in: query
description: Filter invoices by lead
required: false
schema:
type: string
- name: filter[dateMin]
in: query
description: Filter invoices created after this date. Date expected in the format YYYY-MM-DD
required: false
schema:
type: string
- name: filter[dateMax]
in: query
description: Filter invoices created before this date. Date expected in the format YYYY-MM-DD
required: false
schema:
type: string
- name: page[limit]
in: query
description: Limit the number of results returned, for pagination.
required: false
schema:
type: string
- name: page[page]
in: query
description: Request a specific page of results, for pagination. Used in conjunction with the
page[limit] parameter. Indexing is 0-based.
required: false
schema:
type: string
responses:
'200':
description: A list of invoices
content:
application/json:
schema:
properties:
invoices:
description: An array of invoice objects
type: array
items:
$ref: '#/components/schemas/Invoice'
example:
- id: 789-quotes
type: invoices
number: 1000-01
displayStatus: ACCEPTED
total:
amount: '3200.50'
currency: USD
formatted: $3,200.50
productLineItems:
- id: 1-quoteProductLineItems
position: 0
product: 100-products
name: Consulting Services
description: Monthly consulting retainer
sku: CONS-001
quantity: 2
term: null
price:
amount: '1500.00'
currency: USD
formatted: $1,500.00
total:
amount: '3000.00'
currency: USD
formatted: $3,000.00
discountUnit: null
discountNumber: null
subtotalLineItems:
- id: 1-quoteSubtotalLineItems
position: 0
label: Tax
modifierUnit: '%'
modifierValue: 6.5
operation: +
total:
amount: '200.50'
currency: USD
formatted: $200.50
recipient:
id: 321-contacts
name: Jane Doe
email: jane@example.com
validThroughTime: '2024-12-31T23:59:59Z'
createdTime: '2024-01-15T10:30:00Z'
publishedTime: '2024-01-16T14:20:00Z'
sentTime: '2024-01-17T09:15:00Z'
paidTime: '2024-01-20T16:45:00Z'
acceptedName: Jane Customer
acceptedEmail: jane@example.com
completionComment: Paid via ACH
deletedTime: null
links:
lead: 456-leads
- id: 790-quotes
type: invoices
number: 1000-02
displayStatus: SENT
total:
amount: '1500.00'
currency: USD
formatted: $1,500.00
productLineItems:
- id: 2-quoteProductLineItems
position: 0
product: 101-products
name: Setup Fee
description: One-time setup
sku: SETUP-001
quantity: 1
term: null
price:
amount: '1500.00'
currency: USD
formatted: $1,500.00
total:
amount: '1500.00'
currency: USD
formatted: $1,500.00
discountUnit: null
discountNumber: null
subtotalLineItems: []
recipient:
id: 322-contacts
name: John Smith
email: john@example.com
validThroughTime: '2024-11-30T23:59:59Z'
createdTime: '2024-02-01T08:00:00Z'
publishedTime: '2024-02-02T10:00:00Z'
sentTime: '2024-02-03T11:00:00Z'
paidTime: null
acceptedName: null
acceptedEmail: null
completionComment: null
deletedTime: null
links:
lead: 457-leads
meta:
$ref: '#/components/schemas/meta'
links:
description: Pagination links
type: object
example:
self: /rest/invoices?page[page]=0&page[limit]=25
first: /rest/invoices?page[page]=0&page[limit]=25
last: /rest/invoices?page[page]=0&page[limit]=25
type: object
security:
- basicAuth: []
components:
schemas:
Invoice:
type: object
allOf:
- $ref: '#/components/schemas/SalesDocument'
- properties:
number:
description: The invoice number
type: string
example: 1000-01
total:
$ref: '#/components/schemas/value'
validThroughTime:
description: The date and time when the invoice expires or is due
type: string
example: '2024-12-31T23:59:59Z'
createdTime:
description: The date and time when the invoice was created
type: string
example: '2024-01-15T10:30:00Z'
publishedTime:
description: The date and time when the invoice was published
type: string
example: '2024-01-16T14:20:00Z'
sentTime:
description: The date and time when the invoice was sent to the customer
type: string
example: '2024-01-17T09:15:00Z'
paidTime:
description: The date and time when the invoice was paid by the customer
type: string
example: '2024-01-20T16:45:00Z'
completionComment:
description: Payment or completion note when the invoice was marked paid or revoked
type: string
example: Paid via ACH
nullable: true
deletedTime:
description: The date and time when the invoice was deleted
type: string
example: '2024-02-01T12:00:00Z'
type: object
SalesDocument:
properties:
id:
description: The API ID of this entity, formatted {integer}-{entityType}
type: string
example: 3-contacts
displayStatus:
description: The current status of the sales document. For invoices, ACCEPTED means paid.
type: string
enum:
- DRAFT
- READY
- SENT
- REVOKED
- ACCEPTED
- ARCHIVED
- EXPIRED
example: SENT
productLineItems:
$ref: '#/components/schemas/salesDocumentProductLineItems'
subtotalLineItems:
$ref: '#/components/schemas/salesDocumentSubtotalLineItems'
recipient:
$ref: '#/components/schemas/SalesDocumentRecipient'
acceptedName:
description: Name recorded when the document was accepted or marked paid
type: string
example: Jane Customer
nullable: true
acceptedEmail:
description: Email recorded when the document was accepted or marked paid
type: string
example: jane@example.com
nullable: true
type: object
SalesDocumentProductLineItem:
title: Product line item
properties:
id:
description: The line item ID
type: string
example: 1-quoteProductLineItems
position:
description: Sort order of the line item on the document
type: integer
example: 0
product:
description: The product ID this line item references, if any
type: string
example: 100-products
nullable: true
name:
description: Display name of the line item
type: string
example: Consulting Services
description:
description: Description of the line item
type: string
example: Monthly consulting retainer
sku:
description: SKU of the line item
type: string
example: CONS-001
quantity:
description: Quantity of the line item
type: number
format: float
example: 2
term:
description: Billing period unit for the line item, if any (minute, hour, day, week, month,
quarter, or year)
type: string
example: month
nullable: true
price:
$ref: '#/components/schemas/value'
total:
$ref: '#/components/schemas/value'
discountUnit:
description: 'Discount unit: ''$'' for a fixed amount, or ''%'' for a percentage'
type: string
example: '%'
nullable: true
discountNumber:
description: Discount amount or percentage, depending on discountUnit
type: number
format: float
example: 10
nullable: true
type: object
SalesDocumentRecipient:
description: The contact or company selected as the document recipient
properties:
id:
description: The recipient entity ID; entity type is encoded in the API id suffix (e.g. contacts
or accounts)
type: string
example: 321-contacts
name:
description: Display name of the recipient
type: string
example: Jane Doe
email:
description: Email address used for the recipient on this document
type: string
example: jane@example.com
nullable: true
type: object
nullable: true
SalesDocumentSubtotalLineItem:
title: Subtotal line item
properties:
id:
description: The subtotal line item ID
type: string
example: 1-quoteSubtotalLineItems
position:
description: Sort order of the adjustment on the document
type: integer
example: 0
label:
description: Display label for the adjustment
type: string
example: Tax
modifierUnit:
description: 'Modifier unit: ''$'' for a fixed amount, or ''%'' for a percentage'
type: string
example: '%'
modifierValue:
description: Modifier amount or percentage, depending on modifierUnit
type: number
format: float
example: 6.5
operation:
description: Whether the modifier is added (+) or subtracted (-)
type: string
enum:
- +
- '-'
example: +
total:
$ref: '#/components/schemas/value'
type: object
meta:
description: Information about the Nutshell instance making the request
properties:
instanceId:
description: The Nutshell instance ID
type: string
example: '12345'
siteId:
description: Site ID for WebFX customers
type: string
type: object
salesDocumentProductLineItems:
description: The products and services included in the sales document.
type: array
items:
allOf:
- $ref: '#/components/schemas/SalesDocumentProductLineItem'
salesDocumentSubtotalLineItems:
description: Adjustments applied after the product subtotal, such as tax, shipping, or discounts.
type: array
items:
allOf:
- $ref: '#/components/schemas/SalesDocumentSubtotalLineItem'
value:
properties:
formatted:
description: The value formatted as a string
type: string
example: $100.00
amount:
description: The value as a number
type: string
example: '100.00'
currency:
description: The currency code
type: string
example: USD
type: object
securitySchemes:
basicAuth:
type: http
scheme: basic