Overview
Invoices are the core of Shoppex. Every payment starts with an invoice that tracks the customer, products, and payment status.
Invoice Lifecycle
Invoice Statuses
| Status | Description |
|---|
PENDING | Invoice created, awaiting payment |
COMPLETED | Payment completed successfully |
PARTIAL | Partial payment received (crypto underpayment) |
VOIDED | Invoice cancelled or expired |
WAITING_FOR_CONFIRMATIONS | Crypto payment pending blockchain confirmations |
CUSTOMER_DISPUTE_ONGOING | Customer opened a dispute/chargeback |
REVERSED | Payment reversed (chargeback won by customer) |
REFUNDED | Payment was refunded |
Creating an Invoice
Via Dashboard
- Go to Invoices → Create Invoice
- Select products and quantities
- Enter customer email (optional)
- Choose allowed payment methods
- Click Create
Via API
Use the POST /payments endpoint to create an invoice programmatically:
const response = await fetch('https://api.shoppex.io/dev/v1/payments', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
title: 'Order #456',
email: '[email protected]',
value: 29.99,
currency: 'EUR'
})
});
const { data } = await response.json();
// Redirect to data.url for checkout
Invoice Expiration
By default, invoices expire after 24 hours. You can customize this:
- Set
expires_at when creating the invoice
- Configure default expiration in Settings → Invoices
Expired invoices cannot be paid. Create a new invoice for the customer if needed.
Partial Payments
Partial payments can occur with cryptocurrency when the customer sends slightly less than required. You can:
- Accept as paid - Mark the invoice as paid manually
- Request remaining - Customer pays the difference
- Refund - Cancel and refund the partial payment
Webhooks
Get notified when invoice status changes:
{
"event": "order:paid",
"data": {
"uniqid": "abc123def456",
"type": "PRODUCT",
"status": "COMPLETED",
"gateway": "STRIPE",
"total": 29.99,
"total_display": 29.99,
"currency": "USD",
"customer_email": "[email protected]",
"product_id": "prod_xyz",
"product_title": "Pro License",
"created_at": 1705314600,
"updated_at": 1705314650
},
"created_at": 1705314650
}
