POST /api/v1/apps/:appUuid/tenants/:tenantUuid/payment-providers/:paymentProvider/invoices

Creates a new invoices resource.

This endpoint documentation is generated from the current Fastify route implementation and should be treated as the implementation-level contract for this version of the API.

Source route file: src/api/routes/external/private/apiKey/app/tenants/paymentProviders/invoices/post.ts

Request Method

POST

Base URL

https://api.userdocks.local:5000

Endpoint

/api/v1/apps/:appUuid/tenants/:tenantUuid/payment-providers/:paymentProvider/invoices

Path Variables

Variable	Type	Required	Description
appUuid	string	true	Path variable from route pattern.
tenantUuid	string	true	Path variable from route pattern.
paymentProvider	string	true	Path variable from route pattern.

Query Parameters

No query parameters.

HTTP Headers

Variable	Type	Required	Description
x-api-key	string	true	API key value for the app.
x-client-id	string	true	Must match :appUuid path variable.
x-api-key-type	string	true	Use read for GET and write for POST/PUT/DELETE.
Content-Type	string	true	Use application/json for JSON request bodies.

Request Body

Schema reference: createInvoicesSchema

{
  "tenantUuid": "11111111-1111-1111-1111-111111111111",
  "lineItems": [
    {
      "name": "Pro Plan",
      "price": "price_12345"
    }
  ],
  "taxRateId": "txr_12345",
  "type": "subscription"
}

Successful Response

Success status code(s): 200.

For Stripe, the returned billing document is usually an invoice. For Mollie, the returned billing document is always a payment object/document, and type: "subscription" creates the recurring subscription only after the first payment succeeds and the Mollie webhook is processed.

{
  "kind": "invoices",
  "totalItems": 1,
  "itemsLength": 1,
  "items": [
    {
      "status": "open",
      "providerObjectType": "payment",
      "providerObjectId": "tr_12345",
      "nextAction": {
        "url": "https://checkout.mollie.com/pay/tr_12345"
      },
      "documentUrl": "https://my.mollie.com/dashboard/payments/tr_12345",
      "providerResponse": {
        "id": "tr_12345",
        "status": "open",
        "method": "creditcard",
        "customerId": "cst_12345",
        "sequenceType": "first"
      }
    }
  ]
}

Provider Notes

• Stripe: providerObjectType is typically invoice.
• Mollie: providerObjectType is payment, and invoiceId/invoiceUrl style fields in downstream resources refer to the Mollie payment id and payment document URL rather than a native Mollie sales invoice.

Error Responses

HTTP Status	Example Error
401	{"errors":[{"validation":"error","code":"[E4010]","message":"Unauthorized Token or API key"}]}
401	{"errors":[{"validation":"error","code":"[E4011]","message":"Unauthorized API key type"}]}
403	{"errors":[{"validation":"error","code":"[E4030]","message":"App Is Disabled"}]}
400	{"errors":[{"validation":"error","code":"[E4000]","message":"Bad Request / validation error"}]}
500	{"errors":[{"validation":"error","code":"[E0000]","message":"Internal Server Error"}]}

Example

const url = `https://api.userdocks.local:5000/api/v1/apps/appUuid-value/tenants/tenantUuid-value/payment-providers/mollie/invoices`;

const response = await fetch(url, {
  method: 'POST',
  headers: {
    'x-api-key': '<api-key>',
    'x-client-id': 'appUuid-value',
    'x-api-key-type': 'write',
    'Content-Type': 'application/json',
  },
  body: '{"tenantUuid":"11111111-1111-1111-1111-111111111111","lineItems":[{"name":"Pro Plan","price":"price_12345"}],"taxRateId":"txr_12345","paymentMethod":"card","type":"subscription"}',
});
const data = await response.json();
console.log(response.status, data);