Invoices

Overview

Every payment in Shoppex starts with an invoice. Whether a customer checks out through your storefront, clicks a payment link, or your backend creates one via API — the invoice is always the central object that tracks who is paying, what they’re 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. A customer might try PayPal, abandon it, and come back with a credit card — it’s 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 (Developer 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

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. 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 from the dashboard. Use this when the shortfall is negligible and you want to fulfill the order immediately.

Request remaining

Customer pays the difference. The invoice stays in PARTIAL status until the remaining amount is received, then 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 Guide 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 might fail, the second might succeed — the invoice ends as COMPLETED regardless of how many tries it took.

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

Start Here

Concepts

Webhooks

Headless Commerce

Use Cases

Embed SDK

Overview

Invoice Statuses

Creating an Invoice

Via Dashboard

Via API (Developer API)

Completing or Processing an Invoice

Invoice Expiration

Partial Payments

Webhooks

Integration Rule

Next Steps

Payments Guide

Webhooks Guide

​Overview

​Invoice Statuses

​Creating an Invoice

​Via Dashboard

​Via API (Developer API)

​Completing or Processing an Invoice

​Invoice Expiration

​Partial Payments

​Webhooks

​Integration Rule

​Next Steps

Payments Guide

Webhooks Guide

Overview

Invoice Statuses

Creating an Invoice

Via Dashboard

Via API (Developer API)

Completing or Processing an Invoice

Invoice Expiration

Partial Payments

Webhooks

Integration Rule

Next Steps