RevKeen Docs
Api reference

Batch upsert invoices by external ID

Create or update multiple invoices by external system ID. Supports up to 100 invoices per request with stale update protection and immutable field guardrails.

Related endpoints

  • GET /invoices — List invoices
  • POST /invoices — Create invoice
  • GET /invoices/{id} — Get invoice
  • PATCH /invoices/{id} — Update invoice
  • DELETE /invoices/{id} — Delete invoice
  • POST /invoices/{id}/refund — Refund invoice
  • POST /invoices/{id}/reject — Reject invoice
  • GET /invoices/{id}/comments — List invoice comments

Common errors

  • 400 invalid_request — malformed payload or failed validation.
  • 401 unauthenticated — missing, malformed, or revoked API key.
  • 403 permission_denied — key lacks the required scope, or the resource belongs to a different merchant.

Idempotency

Pass an Idempotency-Key header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see the idempotency guide.

PUT
/invoices/external/batch

Authorization

x-api-key<token>

Your RevKeen API key (powered by Unkey). Get it from Dashboard > Settings > API Keys. Use rk_sandbox_* for test mode and rk_live_* for production.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X PUT "https://api.revkeen.com/v2/invoices/external/batch" \  -H "x-api-key: $REVKEEN_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "source": "practicehub",    "invoices": [      {        "external_id": "INV-12345",        "customer_external_ref": {          "source": "string",          "id": "string"        },        "customer_uuid": "00000000-0000-0000-0000-000000000000",        "invoice_number": "string",        "total_minor": 10000,        "subtotal_minor": 0,        "tax_minor": 0,        "discount_minor": 0,        "currency": "USD",        "invoice_date": "string",        "due_date": "string",        "status": "draft",        "line_items": [          {            "description": null,            "quantity": null,            "unit_amount_minor": null,            "product_id": null          }        ],        "notes": "string",        "metadata": {},        "subscription_terms": {          "collection_method": null,          "start_mode": null,          "start_date": null,          "duration_type": null,          "duration_count": null,          "end_date": null,          "first_payment_behavior": null        },        "external_type": "appointment",        "external_updated_at": "2026-01-01T00:00:00Z"      }    ]  }'
{
  "created": 5,
  "updated": 10,
  "skipped": 2,
  "blocked": 1,
  "failed": [
    {
      "external_id": "string",
      "error": "string",
      "reason_code": "string"
    }
  ]
}
Empty
Empty
Empty
Edit on GitHub