Invoices

Issue hosted payment links. Create, send or activate, cancel, and render PDFs; buyers pay via the public link.

10 endpoints

POST/v1/invoicesOptional

Create a draft invoice. lineItems must sum to amountMinor. Accepts an optional Idempotency-Key header.

Request Parameters

Name	Type	Required	Description
`storeId`	string	Required	Store the invoice belongs to
`customerId`	string	Optional	Bind the invoice to a customer
`amountMinor`	integer	Required	Total in kuruş (must equal sum of lineItems)
`currency`	string	Required	Always "TRY"
`lineItems`	array	Required	[{name, qty, unitPriceMinor, lineTotalMinor}]
`buyerEmail`	string	Optional	Required before /send (email delivery)
`buyerName`	string	Optional	Buyer display name
`dueDate`	string	Optional	ISO 8601 due date
`expiresAt`	string	Optional	ISO 8601 link expiry
`notes`	string	Optional	Free-text note on the invoice

JSONRequest Example

{
  "storeId": "sto_5a6b7c8d",
  "amountMinor": 50000,
  "currency": "TRY",
  "lineItems": [
    {
      "name": "Monthly subscription",
      "qty": 1,
      "unitPriceMinor": 50000,
      "lineTotalMinor": 50000
    }
  ],
  "buyerEmail": "buyer@example.com",
  "dueDate": "2026-04-20T12:00:00Z"
}

JSONResponse Example

{
  "id": "inv_7a8b9c0d1e2f",
  "merchantId": "mrc_8a1b2c3d4e5f",
  "storeId": "sto_5a6b7c8d",
  "publicHash": "aB3xK9mN2pQ7rS1tV5wY8z",
  "status": "draft",
  "amountMinor": 50000,
  "currency": "TRY",
  "lineItems": [
    {
      "name": "Monthly subscription",
      "qty": 1,
      "unitPriceMinor": 50000,
      "lineTotalMinor": 50000
    }
  ],
  "buyerEmail": "buyer@example.com",
  "url": "https://pay.kvell.group/invoice/aB3xK9mN2pQ7rS1tV5wY8z",
  "createdAt": "2026-04-13T10:00:00Z"
}

GET/v1/invoicesOptional

List invoices with keyset pagination. Filters: storeId, status.

Request Parameters

Name	Type	Required	Description
`storeId`	string	Optional	Filter by store
`status`	string	Optional	draft\|sent\|activated\|viewed\|paid\|expired\|cancelled
`limit`	integer	Optional	Page size
`cursor`	string	Optional	Opaque keyset cursor

JSONResponse Example

{
  "items": [
    {
      "id": "inv_7a8b9c0d1e2f",
      "storeId": "sto_5a6b7c8d",
      "status": "sent",
      "amountMinor": 50000,
      "currency": "TRY",
      "createdAt": "2026-04-13T10:00:00Z"
    }
  ],
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA0LTEzVDEwOjAwOjAwWiJ9"
}

GET/v1/invoices/{id}Optional

Retrieve an invoice by id.

JSONResponse Example

{
  "id": "inv_7a8b9c0d1e2f",
  "merchantId": "mrc_8a1b2c3d4e5f",
  "storeId": "sto_5a6b7c8d",
  "publicHash": "aB3xK9mN2pQ7rS1tV5wY8z",
  "status": "sent",
  "amountMinor": 50000,
  "currency": "TRY",
  "buyerEmail": "buyer@example.com",
  "url": "https://pay.kvell.group/invoice/aB3xK9mN2pQ7rS1tV5wY8z",
  "createdAt": "2026-04-13T10:00:00Z",
  "sentAt": "2026-04-13T10:05:00Z"
}

POST/v1/invoices/{id}/sendOptional

Move a draft to sent and email the buyer the public link. Requires buyerEmail.

JSONRequest Example

{}

JSONResponse Example

{
  "id": "inv_7a8b9c0d1e2f",
  "status": "sent",
  "sentAt": "2026-04-13T10:05:00Z"
}

POST/v1/invoices/{id}/activateOptional

Move a draft to activated without sending email — share the public link yourself.

JSONRequest Example

{}

JSONResponse Example

{
  "id": "inv_7a8b9c0d1e2f",
  "status": "activated",
  "activatedAt": "2026-04-13T10:05:00Z"
}

POST/v1/invoices/{id}/cancelOptional

Cancel a non-terminal invoice.

JSONRequest Example

{}

JSONResponse Example

{
  "id": "inv_7a8b9c0d1e2f",
  "status": "cancelled",
  "cancelledAt": "2026-04-13T11:00:00Z"
}

GET/v1/invoices/{id}/pdfOptional

Stream the invoice as application/pdf.

JSONResponse Example

{
  "note": "Streams application/pdf; no JSON body."
}

GET/v1/public/invoices/{hash}Optional

Buyer-facing read via the public link (the publicHash is the bearer; no merchant signature). First hit flips sent/activated → viewed.

JSONResponse Example

{
  "publicHash": "aB3xK9mN2pQ7rS1tV5wY8z",
  "merchantName": "Acme Store",
  "status": "viewed",
  "amountMinor": 50000,
  "currency": "TRY",
  "lineItems": [
    {
      "name": "Monthly subscription",
      "qty": 1,
      "unitPriceMinor": 50000,
      "lineTotalMinor": 50000
    }
  ]
}

POST/v1/public/invoices/{hash}/payOptional

Buyer clicks "Pay now": lazily mints a checkout session and returns the hosted checkout URL.

JSONRequest Example

{}

JSONResponse Example

{
  "sessionId": "9c1f2a7b-8c9d-0e1f-3f1c-9a2e6b4d4e8a",
  "checkoutUrl": "https://pay.kvell.group/s/9c1f2a7b-8c9d-0e1f-3f1c-9a2e6b4d4e8a",
  "expiresAt": "2026-04-13T11:00:00Z"
}

GET/v1/public/invoices/{hash}/pdfOptional

Buyer-facing PDF (no view side-effect).

JSONResponse Example

{
  "note": "Streams application/pdf; no JSON body."
}

Category Summary

Total Endpoints

Base Domain

api.pay.kvell.group