Send and Manage Invoices with PayGood

This guide walks you through the full invoice lifecycle: create a draft, revise it, mark it as paid, void it, and inspect its revision history.

You need an API key and a merchant and customer already set up. See Set Up Your API Keys and Manage Customers.

Create a draft invoice

Send POST /invoices with the merchant and customer references and a list of line items. Line items can be product_charge items pulled from your catalog, manual_adjustment items for things like tax or shipping, or a mix of both.

curl -X POST https://api.paygood.co/invoices \
  -H 'Authorization: Bearer $PAYGOOD_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotencyKey": "idem-inv-01",
    "merchantId": "mer_01hxy8m1nqk9g3x3y3p0azq2bg",
    "customerId": "cust_01hxy8m1nqk9g3x3y3p0azq2zz",
    "currency": "usd",
    "lineItems": [
      {
        "kind": "manual_adjustment",
        "description": "Sales tax",
        "amount": 1300
      }
    ]
  }'

Save the returned invoice id (inv_...) for use in later steps.

Revise the draft

Draft invoices can be updated with PUT /invoices/{id}. Each successful update appends an entry to the invoice’s revision history. Send the full line item snapshot you want on the invoice, not just the changes.

curl -X PUT https://api.paygood.co/invoices/inv_01hxy8m1nqk9g3x3y3p0azq2va \
  -H 'Authorization: Bearer $PAYGOOD_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotencyKey": "idem-inv-01-rev-1",
    "merchantId": "mer_01hxy8m1nqk9g3x3y3p0azq2bg",
    "lineItems": [
      {
        "kind": "product_charge",
        "productId": "prod_01hxy8m1nqk9g3x3y3p0azq2c1",
        "priceId": "price_01hxy8m1nqk9g3x3y3p0azq2f1",
        "description": "Monthly subscription",
        "quantity": 3,
        "unitAmount": 2500
      }
    ]
  }'

Mark the invoice as paid

Once the customer has paid outside of PayGood (for example, by ACH or check), transition the invoice to paid with POST /invoices/{id}/mark-paid.

curl -X POST https://api.paygood.co/invoices/inv_01hxy8m1nqk9g3x3y3p0azq2va/mark-paid \
  -H 'Authorization: Bearer $PAYGOOD_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotencyKey": "idem-inv-01-paid",
    "merchantId": "mer_01hxy8m1nqk9g3x3y3p0azq2bg"
  }'

Void an invoice

To cancel a draft or issued invoice, call POST /invoices/{id}/void. Void is a terminal state.

curl -X POST https://api.paygood.co/invoices/inv_01hxy8m1nqk9g3x3y3p0azq2va/void \
  -H 'Authorization: Bearer $PAYGOOD_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotencyKey": "idem-inv-01-void",
    "merchantId": "mer_01hxy8m1nqk9g3x3y3p0azq2bg"
  }'

View revision history

Every update creates a new revision. Retrieve the append-only history (newest first) with GET /invoices/{id}/revisions.

curl -X GET 'https://api.paygood.co/invoices/inv_01hxy8m1nqk9g3x3y3p0azq2va/revisions?merchantId=mer_01hxy8m1nqk9g3x3y3p0azq2bg' \
  -H 'Authorization: Bearer $PAYGOOD_API_KEY'

Always pass a unique idempotencyKey on every write. Retrying the same key returns the original result instead of creating a duplicate invoice, revision, or state transition.

For the full request and response schemas, see the Invoices API reference.

Get Started

Guides

Merchant Onboarding

Send and Manage Invoices with PayGood