Create a draft invoice
Creates a merchant-scoped draft invoice with a sequential merchant invoice number. Line items may mix catalog product charges and manual adjustments such as merchant-calculated tax or shipping.
curl --request POST \
--url https://api-sandbox.paygood.co/invoices \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"merchantId": "mer_01hxy8m1nqk9g3x3y3p0azq2bg",
"customerId": "cust_01hxy8m1nqk9g3x3y3p0azq2zz",
"currency": "USD",
"lineItems": [
{
"kind": "product_charge",
"productId": "prod_01hxy8m1nqk9g3x3y3p0azq2c1",
"priceId": "price_01hxy8m1nqk9g3x3y3p0azq2f1",
"description": "Monthly subscription",
"quantity": 2
}
]
}
'{
"invoiceId": "<string>",
"invoiceNumber": "<string>",
"invoiceUrlSlug": "<string>",
"idempotencyKey": "<string>",
"merchantId": "<string>",
"customerId": "<string>",
"currentRevisionNumber": 4503599627370495,
"status": "draft",
"currency": "<string>",
"lineItems": [
{
"kind": "product_charge",
"productId": "<string>",
"description": "<string>",
"quantity": 4503599627370495,
"unitAmount": 4503599627370495,
"lineTotal": 0,
"priceId": "<string>"
}
],
"productTotal": {
"amount": 4503599627370495,
"currency": "<string>"
},
"total": {
"amount": 4503599627370495,
"currency": "<string>"
},
"amountPaid": {
"amount": 4503599627370495,
"currency": "<string>"
},
"amountRemaining": {
"amount": 4503599627370495,
"currency": "<string>"
},
"acceptedPaymentMethods": [
"card"
],
"additionalNotificationEmails": [
"jsmith@example.com"
],
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"dueDate": "2023-11-07T05:31:56Z",
"paidAt": "2023-11-07T05:31:56Z",
"notes": "<string>",
"metadata": {}
}Authorizations
Merchant API key bearer token.
Headers
Client-supplied unique key for safe retries of this mutating request. Scoped per merchant or resource as documented on each endpoint.
"idem-01"
Body
Create payload with merchant/customer references and mixed line items. Supply idempotency via the Idempotency-Key header.
Supported currency code (USD, CAD)
31- Option 1
- Option 2
Show child attributes
Show child attributes
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$2000Show child attributes
Show child attributes
Which payment method types checkout may offer for this invoice. Defaults to allowing both when omitted.
1card, bank_account Extra addresses notified alongside the customer when this invoice is issued or paid. Max 10.
10^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$Response
Draft invoice created successfully with assigned invoice number and computed totals.
1Secret pay-link token. Anyone holding this value can view and pay the invoice anonymously, so treat it like a credential: safe to send to the customer, never safe to log or expose publicly. Unguessable and unrelated to invoiceId, so it can be rotated without changing the invoice.
110 < x <= 9007199254740991draft, issued, partially_paid, paid, void Supported currency code (USD, CAD)
3- Option 1
- Option 2
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Sum of applied payment allocations, both processed and out-of-band.
Show child attributes
Show child attributes
Computed as total minus amountPaid. Zero when the invoice is fully paid.
Show child attributes
Show child attributes
Which payment method types checkout may offer for this invoice.
card, bank_account ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$Show child attributes
Show child attributes
curl --request POST \
--url https://api-sandbox.paygood.co/invoices \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"merchantId": "mer_01hxy8m1nqk9g3x3y3p0azq2bg",
"customerId": "cust_01hxy8m1nqk9g3x3y3p0azq2zz",
"currency": "USD",
"lineItems": [
{
"kind": "product_charge",
"productId": "prod_01hxy8m1nqk9g3x3y3p0azq2c1",
"priceId": "price_01hxy8m1nqk9g3x3y3p0azq2f1",
"description": "Monthly subscription",
"quantity": 2
}
]
}
'{
"invoiceId": "<string>",
"invoiceNumber": "<string>",
"invoiceUrlSlug": "<string>",
"idempotencyKey": "<string>",
"merchantId": "<string>",
"customerId": "<string>",
"currentRevisionNumber": 4503599627370495,
"status": "draft",
"currency": "<string>",
"lineItems": [
{
"kind": "product_charge",
"productId": "<string>",
"description": "<string>",
"quantity": 4503599627370495,
"unitAmount": 4503599627370495,
"lineTotal": 0,
"priceId": "<string>"
}
],
"productTotal": {
"amount": 4503599627370495,
"currency": "<string>"
},
"total": {
"amount": 4503599627370495,
"currency": "<string>"
},
"amountPaid": {
"amount": 4503599627370495,
"currency": "<string>"
},
"amountRemaining": {
"amount": 4503599627370495,
"currency": "<string>"
},
"acceptedPaymentMethods": [
"card"
],
"additionalNotificationEmails": [
"jsmith@example.com"
],
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"dueDate": "2023-11-07T05:31:56Z",
"paidAt": "2023-11-07T05:31:56Z",
"notes": "<string>",
"metadata": {}
}