Invoices

Understanding the invoice lifecycle and statuses

Every payment in Shoppex starts with an invoice. A customer can check out through your storefront, click a payment link, or your backend can create one through the API. The invoice is always the central object that tracks who is paying, what they are buying, and whether the payment succeeded.

This guide covers the Shoppex invoice model used by both hosted checkout flows and the Developer API.

An invoice can go through more than one payment attempt before it reaches its final state. For example, a customer can try PayPal, abandon it, and come back with a credit card. It is still the same invoice.

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

1. Navigate to invoices

   Go to Invoices → Create Invoice

2. Select products

   Select products and quantities

3. Enter customer email

   Enter customer email (optional)

4. Choose payment methods

   Choose allowed payment methods

5. Create the invoice

   Click Create

Via API

Use the POST /payments endpoint of the Developer API to create an invoice programmatically:

TypeScript

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: '[e-mail]',
    value: 29.99,
    currency: 'EUR'
  })
});

const { data } = await response.json();
// Redirect to data.url for checkout

Completing or processing an invoice

The dashboard calls the manual merchant action Process Invoice. The public Developer API calls the same operation complete invoice:

POST /dev/v1/invoices/{uniqid}/complete

Use it only after your server has independently confirmed payment. The invoice must still be PENDING or PENDING_PAYMENT. An already completed or otherwise non-completable invoice returns 422 VALIDATION_ERROR. Every request must include an Idempotency-Key header.

See Manual payment auto-completion for request examples, idempotency, webhook verification, and common errors.

Invoice expiration

By default, Shoppex-hosted invoice payment windows expire after 24 hours. You can customize the default expiration in Settings → Invoices.

The current Dev API payment example on this page does not accept an expires_at request field. Configure a different default expiration in the dashboard instead.

Expired invoices cannot be paid. If the customer still wants to pay, create a new invoice.

Partial payments

Partial payments can occur with cryptocurrency when the customer sends slightly less than required. You have three options:

• Accept as paid — Mark the invoice as paid manually from the dashboard. Use this when the shortfall is negligible and you want to fulfill the order immediately.
• Request the remaining amount — The customer pays the difference. The invoice stays in PARTIAL status until the remaining amount arrives, then it transitions to COMPLETED.
• Refund — Cancel and refund the partial payment. The invoice moves to VOIDED, and you can create a new one if needed.

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": "[e-mail]",
    "product_id": "prod_xyz",
    "product_title": "Pro License",
    "created_at": "2026-01-15T09:10:00.000Z",
    "updated_at": "2026-01-15T09:10:50.000Z"
  },
  "created_at": 1705314650
}

See Webhooks for setup instructions.

Integration rule

If you sync invoices into your own system, use the Shoppex invoice status as the final source of truth. The first payment attempt can fail and the second can succeed. The invoice ends as COMPLETED regardless of how many tries it took.

React to the final invoice state through webhook events, not through individual gateway callbacks. This is the single most important integration rule in Shoppex.

Payments

Learn about payment gateways, configuration, and processing.

Webhooks

Set up real-time notifications for invoice status changes.