Invoices API

The Invoices API allows you to create, send, and manage invoices for your customers.

The Invoice Object

{
  "id": "inv_abc123def456",
  "object": "invoice",
  "status": "open",
  "customer": "cus_xyz789",
  "customer_email": "customer@example.com",
  "customer_name": "John Doe",
  "customer_phone": "0241234567",
  "customer_address": "123 Main St, Accra",
  "description": "January services",
  "footer": "Thank you for your business",
  "memo": "Net 30",
  "amount_due": 150,
  "amount_paid": 0,
  "currency": "GHS",
  "due_date": "2024-02-15T00:00:00Z",
  "collection_method": "send_invoice",
  "line_items": [
    {
      "id": "li_abc123",
      "description": "Web Development",
      "quantity": 1,
      "unit_amount": 100,
      "amount": 100,
      "taxable": false
    },
    {
      "id": "li_def456",
      "description": "Hosting",
      "quantity": 1,
      "unit_amount": 50,
      "amount": 50,
      "taxable": false
    }
  ],
  "metadata": {},
  "created_at": "2024-01-15T10:00:00Z"
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier
`object`	string	Always `"invoice"`
`status`	string	`draft`, `open`, `paid`, `void`, `uncollectible`
`customer`	string	Customer ID
`customer_email`	string	Customer email
`customer_name`	string	Customer name
`customer_phone`	string	Customer phone
`customer_address`	string	Customer address
`description`	string	Invoice description
`footer`	string	Invoice footer text
`memo`	string	Internal memo
`amount_due`	number	Total amount due in GHS
`amount_paid`	number	Amount paid in GHS
`currency`	string	Currency code
`due_date`	string	Due date
`collection_method`	string	Collection method
`line_items`	array	Line items on the invoice
`metadata`	object	Custom metadata
`created_at`	string	Creation timestamp

Create an Invoice

POST /v1/invoices

Request Body

Parameter	Type	Required	Description
`customer`	string	No	Customer ID (auto-fills email/name/phone)
`customer_email`	string	No	Customer email
`customer_name`	string	No	Customer name
`customer_phone`	string	No	Customer phone
`customer_address`	string	No	Customer address
`description`	string	No	Invoice description
`footer`	string	No	Footer text
`memo`	string	No	Internal memo
`due_date`	string	No	Due date (ISO 8601)
`collection_method`	string	No	Default: `send_invoice`
`auto_finalize`	boolean	No	Automatically finalize on creation
`metadata`	object	No	Custom metadata
`line_items`	array	No	Initial line items

Line Item Fields

Parameter	Type	Required	Description
`description`	string	Yes	Item description
`quantity`	number	No	Quantity (default: 1)
`unit_amount`	number	Yes	Unit price in GHS
`product`	string	No	Product ID
`taxable`	boolean	No	Whether item is taxable (default: `false`)
`tax_percent`	number	No	Tax percentage
`metadata`	object	No	Custom metadata

curl -X POST https://api.shikacreators.com/v1/invoices \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_xyz789",
    "description": "January services",
    "due_date": "2024-02-15T00:00:00Z",
    "line_items": [
      {
        "description": "Web Development",
        "unit_amount": 100,
        "quantity": 1
      },
      {
        "description": "Hosting",
        "unit_amount": 50,
        "quantity": 1
      }
    ]
  }'

const invoice = await shikacreators.invoices.create({
  customer: 'cus_xyz789',
  description: 'January services',
  due_date: '2024-02-15T00:00:00Z',
  line_items: [
    { description: 'Web Development', unit_amount: 100 },
    { description: 'Hosting', unit_amount: 50 }
  ]
})

invoice = client.invoices.create(
    customer='cus_xyz789',
    description='January services',
    due_date='2024-02-15T00:00:00Z',
    line_items=[
        {'description': 'Web Development', 'unit_amount': 100},
        {'description': 'Hosting', 'unit_amount': 50}
    ]
)

Retrieve an Invoice

GET /v1/invoices/:id

Update an Invoice

Updates a draft invoice.

POST /v1/invoices/:id

Only invoices with status draft can be updated.

Add a Line Item

Adds a line item to a draft invoice.

POST /v1/invoices/:id/lines

Request Body

Parameter	Type	Required	Description
`description`	string	Yes	Item description
`quantity`	number	No	Quantity (default: 1)
`unit_amount`	number	Yes	Unit price in GHS
`product`	string	No	Product ID
`taxable`	boolean	No	Whether item is taxable
`tax_percent`	number	No	Tax percentage
`metadata`	object	No	Custom metadata

Finalize an Invoice

Finalizes a draft invoice, changing its status to open.

POST /v1/invoices/:id/finalize

The invoice must be in draft status and must have at least one line item. Finalizing triggers PDF generation and notification queuing.

Pay an Invoice

Marks an invoice as paid and creates an associated payment.

POST /v1/invoices/:id/pay

Request Body

Parameter	Type	Required	Description
`payment_method`	string	No	Payment method identifier
`source`	string	No	Source/phone number for payment
`off_session`	boolean	No	Off-session payment indicator

Only invoices with status open can be paid.

Void an Invoice

Voids an invoice, making it uncollectable.

POST /v1/invoices/:id/void

Paid invoices cannot be voided. Issue a refund instead.

Send an Invoice

Sends the invoice to the customer via email and/or SMS.

POST /v1/invoices/:id/send

The invoice must have a customer email or phone number and cannot be in draft status.

Download PDF

Generates and downloads the invoice as a PDF.

GET /v1/invoices/:id/pdf

Delete an Invoice

Deletes a draft invoice.

DELETE /v1/invoices/:id

Only invoices with status draft can be deleted.

List Invoices

GET /v1/invoices

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (1-100, default 10)
`starting_after`	string	Cursor for pagination
`customer`	string	Filter by customer ID
`status`	string	Filter by status (`draft`, `open`, `paid`, `void`, `uncollectible`)
`due_date`	string	Filter by due date range
`created`	string	Filter by creation date range

Invoice Statuses

Status	Description
`draft`	Invoice is being prepared (editable)
`open`	Invoice has been finalized and sent
`paid`	Invoice has been paid
`void`	Invoice has been voided
`uncollectible`	Invoice is uncollectable

Invoices

On this page