Skip to main content
POST
/
v1
/
invoices
Create invoice
curl --request POST \
  --url https://api.gwop.io/v1/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount_usdc": 1000000,
  "description": "Premium API access",
  "metadata": {
    "orderId": "ORD-123",
    "sku": "premium-api"
  },
  "metadata_public": false,
  "expires_in_seconds": 900,
  "consumption_type": "redeliverable",
  "replay_window_seconds": 15768030,
  "max_replays": 500
}
'
{
  "id": "904e9f44-a5a3-4e07-94c9-9c425d6bbe64",
  "merchant_id": "904e9f44-a5a3-4e07-94c9-9c425d6bbe64",
  "amount_usdc": 1000000,
  "currency": "USDC",
  "status": "OPEN",
  "metadata_public": true,
  "created_at": "2026-02-02T12:00:00.000Z",
  "expires_at": "2026-02-02T12:00:00.000Z",
  "description": "<string>",
  "metadata": {},
  "consumption_type": "redeliverable",
  "replay_window_seconds": 123,
  "max_replays": 123
}

Authorizations

​
Authorization
string
header
required

Merchant API key (sk_m_*). Used for invoice management, store configuration, and viewing merchant data.

Authorization: Bearer sk_m_abc123def456...

Headers

​
Idempotency-Key
string<uuid>

Client-generated key for idempotent requests (UUID v4 required if provided)

Required string length: 10 - 64
Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

application/json
​
amount_usdc
integer<int64>
required

Amount in USDC minor units (6 decimals).

Human ReadableAPI Value
$1.001000000
$0.0110000
$100.00100000000
$10,000.00 (max)10000000000
Required range: 1 <= x <= 10000000000
Example:

1000000

​
description
string

Human-readable invoice description

Maximum string length: 500
Example:

"Premium API access"

​
metadata
object

Custom key-value data (max 1KB)

Example:
{
  "orderId": "ORD-123",
  "sku": "premium-api"
}
​
metadata_public
boolean
default:false

If true, description and metadata visible in public GET

​
expires_in_seconds
integer
default:900

Invoice TTL in seconds (default 15 minutes)

Required range: 60 <= x <= 86400
​
consumption_type
enum<string>

Controls retry behavior for delivery.

TypeRetry Safe?Example
redeliverableYesFiles, articles, downloads
consumableNoAPI credits, subscriptions
Available options:
redeliverable,
consumable
​
replay_window_seconds
integer

Time window for retrying delivery (redeliverable only)

Required range: 60 <= x <= 31536000
​
max_replays
integer

Max delivery retries (redeliverable only)

Required range: 1 <= x <= 1000

Response

Invoice created

​
id
string<uuid>
required

UUID v4 identifier

Example:

"904e9f44-a5a3-4e07-94c9-9c425d6bbe64"

​
merchant_id
string<uuid>
required

UUID v4 identifier

Example:

"904e9f44-a5a3-4e07-94c9-9c425d6bbe64"

​
amount_usdc
integer<int64>
required

Amount in USDC minor units (6 decimals).

Human ReadableAPI Value
$1.001000000
$0.0110000
$100.00100000000
$10,000.00 (max)10000000000
Required range: 1 <= x <= 10000000000
Example:

1000000

​
currency
enum<string>
required

Currency code. Currently only USDC is supported.

Available options:
USDC
Example:

"USDC"

​
status
enum<string>
required

Invoice lifecycle status.

OPEN ──[pay]──> PAYING ──[confirm]──> PAID
 │                ▲
 │                │
 └────[fails]─────┘ (rolls back to OPEN)

OPEN ──[cancel]──> CANCELED
OPEN ──[expires]──> EXPIRED
Available options:
OPEN,
PAYING,
PAID,
EXPIRED,
CANCELED
​
metadata_public
boolean
required
​
created_at
string<date-time>
required

ISO 8601 timestamp in UTC

Example:

"2026-02-02T12:00:00.000Z"

​
expires_at
string<date-time>
required

ISO 8601 timestamp in UTC

Example:

"2026-02-02T12:00:00.000Z"

​
description
string
​
metadata
object
​
consumption_type
enum<string>

Controls retry behavior for delivery.

TypeRetry Safe?Example
redeliverableYesFiles, articles, downloads
consumableNoAPI credits, subscriptions
Available options:
redeliverable,
consumable
​
replay_window_seconds
integer
​
max_replays
integer