AgencyHandy Handbook

Send invoice to client

Atikur Rahaman

Get available templates

GET /invoices/template

example response

{

"success": true,

"data": [

{

"_id": "673d750605683b99a1ccb7e4",

"templateData": "{\"logo\":\"https://agency-stage-file.s3.amazonaws.com/6656afc1cf09b46f9a362eae/6656afc1cf09b46f9a362eae_1721107309845_DSC1579-2.png\",\"title\":\"Invoice\",\"notes\":\"\",\"backgroundColor\":\"#FFFFFF\",\"themeColor\":\"#b35683\",\"textColor\":\"#344054\",\"hiddenFields\":[],\"signatory\":\"\",\"signatoryDesignation\":\"\",\"signature\":\"\",\"additionalAddress\":\"\"}",

"defaultTemplate": "670e331970492034b4259bee",

"isDefault": false,

"__v": 0,

"name": "Classic"

{

"_id": "67b58238e96bd31d5057f5d7",

"templateData": "{\"logo\":\"https://agency-stage-file.s3.amazonaws.com/6656afc1cf09b46f9a362eae/6656afc1cf09b46f9a362eae_1738133558931_1kb.png\",\"title\":\"Invoice\",\"notes\":\"\",\"backgroundColor\":\"#FFFFFF\",\"themeColor\":\"#475467\",\"textColor\":\"#475467\",\"hiddenFields\":[],\"signatory\":\"\",\"signatoryDesignation\":\"\",\"signature\":\"\",\"additionalAddress\":\"\"}",

"defaultTemplate": "6666a78f18f001e34ff0f9f2",

"isDefault": false,

"__v": 0,

"name": "Simple"

{

"_id": "67c68d08c7dc1a0b1eb14594",

"templateData": "{\"logo\":\"https://agency-stage-file.s3.amazonaws.com/6656afc1cf09b46f9a362eae/6656afc1cf09b46f9a362eae_1738133558931_1kb.png\",\"title\":\"Invoice\",\"notes\":\"\",\"backgroundColor\":\"#FFFFFF\",\"themeColor\":\"#CEB8A6\",\"textColor\":\"#344054\",\"hiddenFields\":[],\"signatory\":\"\",\"signatoryDesignation\":\"\",\"signature\":\"\",\"additionalAddress\":\"\"}",

"defaultTemplate": "6715d56f010b2aa6a1c10612",

"isDefault": true,

"__v": 0,

"name": "Serene"

}

]

}

Set default template

POST /invoices/templates

payload

{

"defaultTemplateId": "6715d56f010b2aa6a1c10612",

"templateData": "{\"logo\":\"https://agency-stage-file.s3.amazonaws.com/6656afc1cf09b46f9a362eae/6656afc1cf09b46f9a362eae_1738133558931_1kb.png\",\"title\":\"Invoice\",\"notes\":\"\",\"backgroundColor\":\"#FFFFFF\",\"themeColor\":\"#CEB8A6\",\"textColor\":\"#344054\",\"hiddenFields\":[],\"signatory\":\"\",\"signatoryDesignation\":\"\",\"signature\":\"\",\"additionalAddress\":\"\"}",

"isDefault": true

}

Create invoice

POST /invoice

payload schema

const invoiceSchema = Joi.object().keys({

createdBy: idSchema.id, // _id of object

client: idSchema.id,

project: idSchema.id,

address: Joi.string().trim(),

additionalAddress: Joi.string().trim().allow(''),

currency: Joi.string().valid(stripeCurrencies),

amountTotal: Joi.number().min(0),

amountDue: Joi.number().min(0),

amountPaid: Joi.number().min(0),

amountRemain: Joi.number().min(0),

upfrontPaid: Joi.boolean(),

defaultPaymentMethod: Joi.string().trim().default(null),

dueDate: Joi.date(),

paidDate: Joi.date(),

notes: Joi.string().allow(''),

discountPercentage: Joi.number().min(0).max(100),

status: Joi.string().valid('draft'),

amount: Joi.number().min(0),

quantity: Joi.number().min(1),

paymentType: Joi.string().valid('oneTime', 'subscription'),

repeatCount: Joi.number().min(1),

repeatDuration: Joi.string().valid('day', 'week', 'month', 'year'),

billingCycleCount: Joi.number().min(0),

vat: Joi.number().min(0),

wisePaymentLink: Joi.string().uri().optional(),

additionalFields: Joi.array()

.items(

Joi.object().keys({

name: Joi.string().required(),

quantity: Joi.number().min(1).required(),

value: Joi.number().required(),

}),

)

.min(1),

reminderType: Joi.string()

.valid('sendReminder', 'doNotSendReminder')

.optional(),

reminders: Joi.when('reminderType', {

is: 'sendReminder',

then: Joi.array().items(invoiceReminderObj).min(1).required(),

otherwise: Joi.forbidden(),

}),

});

invoiceReminderObj

const invoiceReminderObj = Joi.object().keys({

order: Joi.number().min(1).required(),

template: Joi.string()

.valid(...invoiceReminderTemplates)

.required(),

days: Joi.number().min(1).required(),

actionDate: Joi.string().valid('dueDate').required(),

action: Joi.string().valid('before', 'after').required(),

});

invoiceReminderTemplates

const invoiceReminderTemplates = [

'invoiceReminderRecurringInvoice',

'invoiceReminderUpcomingInvoice',

'invoiceReminderPaymentDueSoon',

'invoiceReminderPaymentDueToday',

'invoiceReminderOverdueInvoice',

'invoiceReminderFinalInvoicePayment',

];

payload

{

"currency": "USD",

"discountPercentage": 0,

"notes": "",

"amountDue": 1,

"amountPaid": 0,

"amountTotal": 1,

"project": "67c136dbaefb1c16e0170b80",

"client": "665e82153fb3434863879c5c",

"quantity": 1,

"amount": 1,

"paymentType": "oneTime",

"vat": 0,

"billingCycleCount": 1,

"additionalAddress": "",

"address": "United States~California~California~11111"

}

if a default template is present. the invoice will be created with that template

Send a invoice to the client

PUT /invoices/{{INVOICE_ID}}

payload

{"status":"open"}

Want to print your doc?
This is not the way.

Try clicking the ⋯ next to your doc name or using a keyboard shortcut (

CtrlP

) instead.