Create invoice Create a new invoice for a customer. You must supply at least one line item. Line items can reference existing products by ID (which auto-populates description and price) or be freeform entries with a description and unit price.
Authentication x-api-key: your_api_key x-api-secret: your_api_secret
Request body Invoice details A descriptive title for the invoice, e.g. "Web Development Services — March 2024".
ISO 4217 3-letter currency code. Defaults to "USD" if not provided. Example: "NGN".
Your company or business name as it should appear on the invoice.
Your business email address. Must be a valid email.
ISO 8601 date-time of when the invoice is issued. Defaults to now if omitted. Example: "2024-04-01T00:00:00Z".
ISO 8601 date-time of the payment due date. Example: "2024-04-30T00:00:00Z".
Customer details Full name of the customer receiving the invoice.
Customer’s email address. Must be a valid email. Used when sending the invoice by email.
Customer’s street billing address.
Customer’s state or province.
Customer’s postal / zip code.
Tax & discounts (invoice-level) When you set taxType at the invoice level, it overrides any per-line-item tax settings.
How tax is applied across the invoice. One of: "none", "percentage", "fixed". Defaults to "none".
Tax value. When taxType is "percentage", this is the percentage (e.g. 7.5 for 7.5%). When taxType is "fixed", this is the flat amount per line item.
How the discount is applied. One of: "none", "percentage", "fixed". Defaults to "none".
Discount value. Interpretation depends on discountType.
Flat shipping fee added to the invoice total.
Other Optional notes or payment instructions shown on the invoice.
Arbitrary key-value pairs you want to attach to the invoice for your own reference.
An HTTPS URL Hyparrow will POST to when a checkout-link payment for this invoice changes status (completed, pending, or failed).
Line items Array of line item objects. At least one is required. UUID of an existing product. When provided, description and unitPrice are auto-populated from the product. You may still override unitPrice.
Description of the line item. Required when productId is not provided.
Number of units. Must be greater than 0.
Price per unit. Required when productId is not provided. Must be greater than 0.
Line-item tax type: "none", "percentage", or "fixed". Only applied when the invoice-level taxType is "none".
Line-item tax rate or fixed amount.
Line-item discount type: "none", "percentage", or "fixed".
Line-item discount value.
Example request curl --request POST \ --url https://api.hyparrow.com/api/v1/invoices/ \ --header 'Content-Type: application/json' \ --header 'x-api-key: your_api_key' \ --header 'x-api-secret: your_api_secret' \ --data '{ "title": "Web Development Services — Q1 2024", "currency": "NGN", "companyName": "Acme Corp", "email": "billing@acme.com", "issueDate": "2024-04-01T00:00:00Z", "dueDate": "2024-04-30T00:00:00Z", "customerName": "Jane Doe", "customerEmail": "jane@example.com", "billingAddress": "12 Victoria Island", "city": "Lagos", "state": "Lagos", "country": "Nigeria", "taxType": "percentage", "taxRate": 7.5, "discountType": "none", "shippingFee": 0, "notes": "Payment due within 30 days.", "lineItems": [ { "description": "Frontend development", "quantity": 1, "unitPrice": 250000 }, { "description": "API integration", "quantity": 2, "unitPrice": 75000 } ] }'
Example response { "success" : true , "message" : "Invoice created successfully" , "data" : { "id" : "3fa85f64-5717-4562-b3fc-2c963f66afa6" , "invoiceNumber" : "invoice-hpw-000000001" , "title" : "Web Development Services — Q1 2024" , "currency" : "NGN" , "companyName" : "Acme Corp" , "email" : "billing@acme.com" , "customerName" : "Jane Doe" , "customerEmail" : "jane@example.com" , "issueDate" : "2024-04-01T00:00:00Z" , "dueDate" : "2024-04-30T00:00:00Z" , "taxType" : "percentage" , "taxRate" : 7.5 , "discountType" : "none" , "discount" : 0 , "shippingFee" : 0 , "subTotal" : 400000 , "taxTotal" : 30000 , "discountTotal" : 0 , "totalAmount" : 430000 , "status" : "draft" , "lineItems" : [ { "id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "description" : "Frontend development" , "quantity" : 1 , "unitPrice" : 250000 , "taxType" : "none" , "taxRate" : 0 , "discountType" : "none" , "discount" : 0 }, { "id" : "b2c3d4e5-f6a7-8901-bcde-f12345678901" , "description" : "API integration" , "quantity" : 2 , "unitPrice" : 75000 , "taxType" : "none" , "taxRate" : 0 , "discountType" : "none" , "discount" : 0 } ], "createdAt" : "2024-04-01T08:00:00Z" , "updatedAt" : "2024-04-01T08:00:00Z" } }
Add line item Add a new line item to an existing invoice.
POST /api/v1/invoices/:invoiceId/line-items
Path parameters UUID of the invoice to add the line item to.
Request body Description of the line item.
Number of units. Must be greater than 0.
Price per unit. Must be greater than 0.
Tax type for this line item: "none", "percentage", or "fixed". Only applied when the invoice-level taxType is "none".
Tax rate or fixed amount for this line item.
Discount type for this line item: "none", "percentage", or "fixed".
Discount value for this line item.
Example request curl --request POST \ --url https://api.hyparrow.com/api/v1/invoices/3fa85f64-5717-4562-b3fc-2c963f66afa6/line-items \ --header 'Content-Type: application/json' \ --header 'x-api-key: your_api_key' \ --header 'x-api-secret: your_api_secret' \ --data '{ "description": "Hosting setup fee", "quantity": 1, "unitPrice": 15000 }'
Example response { "success" : true , "message" : "Line item added" , "data" : { "id" : "c3d4e5f6-a7b8-9012-cdef-012345678902" , "invoiceId" : "3fa85f64-5717-4562-b3fc-2c963f66afa6" , "description" : "Hosting setup fee" , "quantity" : 1 , "unitPrice" : 15000 , "taxType" : "none" , "taxRate" : 0 , "discountType" : "none" , "discount" : 0 , "createdAt" : "2024-04-02T09:00:00Z" , "updatedAt" : "2024-04-02T09:00:00Z" } }
List invoices Returns a paginated list of all invoices for your account.
Query parameters Page number. Defaults to 1.
Number of results per page. Defaults to 20.
Filter by invoice status. One of: draft, pending, paid, overdue, canceled.
Example request curl --request GET \ --url 'https://api.hyparrow.com/api/v1/invoices/?page=1&limit=10&status=pending' \ --header 'x-api-key: your_api_key' \ --header 'x-api-secret: your_api_secret'
Example response { "success" : true , "data" : [ { "id" : "3fa85f64-5717-4562-b3fc-2c963f66afa6" , "invoiceNumber" : "invoice-hpw-000000001" , "title" : "Web Development Services — Q1 2024" , "customerName" : "Jane Doe" , "customerEmail" : "jane@example.com" , "totalAmount" : 430000 , "currency" : "NGN" , "status" : "pending" , "dueDate" : "2024-04-30T00:00:00Z" , "createdAt" : "2024-04-01T08:00:00Z" } ], "pagination" : { "page" : 1 , "limit" : 10 , "total" : 1 , "totalPages" : 1 } }
Get invoice Retrieve a single invoice by its ID.
GET /api/v1/invoices/:invoiceId
Path parameters UUID of the invoice to retrieve.
Example request curl --request GET \ --url https://api.hyparrow.com/api/v1/invoices/3fa85f64-5717-4562-b3fc-2c963f66afa6 \ --header 'x-api-key: your_api_key' \ --header 'x-api-secret: your_api_secret'
Example response { "success" : true , "data" : { "id" : "3fa85f64-5717-4562-b3fc-2c963f66afa6" , "invoiceNumber" : "invoice-hpw-000000001" , "title" : "Web Development Services — Q1 2024" , "currency" : "NGN" , "companyName" : "Acme Corp" , "email" : "billing@acme.com" , "customerName" : "Jane Doe" , "customerEmail" : "jane@example.com" , "issueDate" : "2024-04-01T00:00:00Z" , "dueDate" : "2024-04-30T00:00:00Z" , "taxType" : "percentage" , "taxRate" : 7.5 , "subTotal" : 400000 , "taxTotal" : 30000 , "discountTotal" : 0 , "totalAmount" : 430000 , "status" : "pending" , "notes" : "Payment due within 30 days." , "lineItems" : [], "createdAt" : "2024-04-01T08:00:00Z" , "updatedAt" : "2024-04-01T08:00:00Z" } }
