Invoices API

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

All amounts (amount_due, amount_paid, subtotal, total, unit_amount, etc.) are integers in pesewas — the smallest currency unit. 100 pesewas = GHS 1.00. 15000 pesewas = GHS 150.00. The API never accepts or returns fractional GHS amounts.

The Invoice Object

{
  "id": "inv_udjkz1qeau7yabhx56ktg7x1",
  "object": "invoice",
  "invoice_number": "INV-2026-000001",
  "status": "draft",
  "customer": "cus_xyz789",
  "customer_email": "customer@example.com",
  "customer_name": "John Doe",
  "customer_phone": "0241234567",
  "customer_address": "123 Main St, Accra",
  "subtotal": 15000,
  "tax": 0,
  "tax_percent": null,
  "discount": 0,
  "total": 15000,
  "amount_paid": 0,
  "amount_due": 15000,
  "currency": "GHS",
  "coupon": null,
  "description": "January services",
  "footer": "Thank you for your business",
  "memo": "Net 30",
  "invoice_date": "2026-01-15T10:00:00.000Z",
  "due_date": "2026-02-15T00:00:00.000Z",
  "paid_at": null,
  "payment": null,
  "collection_method": "send_invoice",
  "hosted_invoice_url": "https://shikacreators.com/invoice/inv_udjkz1qeau7yabhx56ktg7x1",
  "invoice_pdf": null,
  "attempt_count": 0,
  "next_payment_attempt": null,
  "finalized_at": null,
  "voided_at": null,
  "livemode": true,
  "metadata": {},
  "lines": {
    "object": "list",
    "data": [
      {
        "id": "ee683280-e002-41f9-a7f8-c64195bdb6c1",
        "object": "line_item",
        "description": "Web Development",
        "quantity": 1,
        "unit_amount": 10000,
        "amount": 10000,
        "currency": "GHS",
        "taxable": false,
        "tax_percent": null,
        "discount_amount": 0,
        "product": null,
        "metadata": {}
      },
      {
        "id": "a48a8d06-f8a3-49ec-9621-cc54f1fc53dd",
        "object": "line_item",
        "description": "Hosting",
        "quantity": 1,
        "unit_amount": 5000,
        "amount": 5000,
        "currency": "GHS",
        "taxable": false,
        "tax_percent": null,
        "discount_amount": 0,
        "product": null,
        "metadata": {}
      }
    ],
    "has_more": false,
    "url": "/v1/invoices/inv_udjkz1qeau7yabhx56ktg7x1/lines"
  },
  "created": 1778347235
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier (`inv_xxx`)
`object`	string	Always `"invoice"`
`invoice_number`	string	Human-readable invoice number, e.g. `INV-2026-000001`
`status`	string	One of `draft`, `open`, `paid`, `void`, `uncollectible`
`customer`	string \| null	Customer ID (`cus_xxx`) if the invoice is linked to a customer
`customer_email`	string \| null	Customer email
`customer_name`	string \| null	Customer name
`customer_phone`	string \| null	Customer phone
`customer_address`	string \| null	Customer address
`subtotal`	integer	Sum of line item amounts in pesewas, before tax/discount
`tax`	integer	Tax amount in pesewas
`tax_percent`	number \| null	Tax percentage applied
`discount`	integer	Discount amount in pesewas
`total`	integer	Final total in pesewas (`subtotal + tax - discount`)
`amount_paid`	integer	Amount paid in pesewas
`amount_due`	integer	Amount remaining in pesewas
`currency`	string	ISO currency code (e.g. `GHS`)
`coupon`	string \| null	Coupon ID if a coupon was applied
`description`	string \| null	Invoice description
`footer`	string \| null	Invoice footer text
`memo`	string \| null	Internal memo (not shown to customer)
`invoice_date`	string	When the invoice was issued (ISO 8601)
`due_date`	string \| null	Payment due date (ISO 8601)
`paid_at`	string \| null	When the invoice was paid (ISO 8601)
`payment`	string \| null	Public ID (`pay_xxx`) of the payment, once paid
`collection_method`	string	`send_invoice` or `charge_automatically`
`hosted_invoice_url`	string	Public URL where the customer can view and pay
`invoice_pdf`	string \| null	URL to the generated PDF (set after first PDF generation)
`attempt_count`	integer	Number of payment attempts made
`next_payment_attempt`	string \| null	Scheduled next attempt (ISO 8601)
`finalized_at`	string \| null	When the invoice was finalized (ISO 8601)
`voided_at`	string \| null	When the invoice was voided (ISO 8601)
`livemode`	boolean	`true` if created with a live key, `false` for test
`metadata`	object	Custom metadata
`lines`	object	Sub-list of line items: `{ object: "list", data: [...], has_more, url }`
`created`	integer	Creation timestamp (Unix seconds)

Create an Invoice

POST /v1/invoices

Request Body

Parameter	Type	Required	Description
`customer`	string	No	Customer ID (`cus_xxx`). Auto-fills email/name/phone from the customer record
`customer_email`	string	No	Overrides customer email
`customer_name`	string	No	Overrides customer name
`customer_phone`	string	No	Overrides customer phone
`customer_address`	string	No	Customer address
`description`	string	No	Invoice description
`footer`	string	No	Footer text shown on the invoice
`memo`	string	No	Internal memo (not shown to customer)
`due_date`	string	No	Due date (ISO 8601)
`collection_method`	string	No	`send_invoice` (default) or `charge_automatically`
`auto_finalize`	boolean	No	If `true`, the invoice is finalized immediately on creation (status becomes `open`)
`metadata`	object	No	Custom metadata
`line_items`	array	No	Initial line items (see below)

Line Item Fields

Parameter	Type	Required	Description
`description`	string	Yes	Item description
`quantity`	number	No	Quantity (default: 1)
`unit_amount`	integer	Yes	Unit price in pesewas (e.g. `10000` = GHS 100.00)
`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": "2026-02-15T00:00:00Z",
    "line_items": [
      {
        "description": "Web Development",
        "unit_amount": 10000,
        "quantity": 1
      },
      {
        "description": "Hosting",
        "unit_amount": 5000,
        "quantity": 1
      }
    ]
  }'

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

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

Retrieve an Invoice

GET /v1/invoices/:id

Update an Invoice

Updates a draft invoice. The response is the full invoice object.

POST /v1/invoices/:id

Only invoices with status draft can be updated.

Add a Line Item

Adds a line item to a draft invoice. The response is the updated invoice (not the bare line item).

POST /v1/invoices/:id/lines

Request Body

Parameter	Type	Required	Description
`description`	string	Yes	Item description
`quantity`	number	No	Quantity (default: 1)
`unit_amount`	integer	Yes	Unit price in pesewas
`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. SMS receipts are sent to the customer (if a phone is on the invoice or source is provided) and to the merchant's business phone.

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 the payment (used as fallback receipt destination)
`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

Returns a 302 redirect to a hosted PDF URL. Most HTTP clients (browsers, curl -L) follow the redirect and download the file. The PDF is generated on first request and the URL is cached on invoice_pdf for subsequent calls.

GET /v1/invoices/:id/pdf

Delete an Invoice

Deletes a draft invoice. Returns { "id": "...", "object": "invoice", "deleted": true }.

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, deletable)
`open`	Invoice has been finalized and can be paid
`paid`	Invoice has been paid
`void`	Invoice has been voided
`uncollectible`	Invoice is uncollectable

Invoices

On this page