Invoices

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

Navigate to invoices

Go to Invoices → Create Invoice

Select products

Select products and quantities

Enter customer email

Enter customer email (optional)

Choose payment methods

Choose allowed payment methods

Create the invoice

Click Create

Via API

Use the POST /payments endpoint of the Developer API 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

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": "[email protected]",
    "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.

Start here

Invoices and payments

Webhooks

Headless commerce

Storefront SDK

Checkout embeds

Integrations

Resellers

Email marketing

Tutorials

Invoice statuses

Creating an invoice

Via dashboard

Via API

Completing or processing an invoice

Invoice expiration

Partial payments

Webhooks

Integration rule

Payments

Webhooks

​Invoice statuses

​Creating an invoice

​Via dashboard

​Via API

​Completing or processing an invoice

​Invoice expiration

​Partial payments

​Webhooks

​Integration rule

Payments

Webhooks

Invoice statuses

Creating an invoice

Via dashboard

Via API

Completing or processing an invoice

Invoice expiration

Partial payments

Webhooks

Integration rule