> ## Documentation Index > Fetch the complete documentation index at: https://docs.paygood.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi.json post /invoices openapi: 3.0.0 info: title: PayGood Merchant API description: Server-to-server integration surface for merchant API keys. version: '1.0' contact: {} servers: - url: https://api-sandbox.paygood.co description: Sandbox - url: https://api.paygood.co description: Production security: [] paths: /invoices: post: tags: - invoices summary: Create a draft invoice description: >- 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. operationId: InvoicesController_create parameters: [] requestBody: required: true description: >- Create payload with idempotency key, merchant/customer references, and mixed line items. content: application/json: schema: $ref: '#/components/schemas/CreateInvoiceDto' examples: productLines: summary: Product line items only value: idempotencyKey: idem-inv-01 merchantId: mer_01hxy8m1nqk9g3x3y3p0azq2bg customerId: cust_01hxy8m1nqk9g3x3y3p0azq2zz currency: usd lineItems: - kind: product_charge productId: prod_01hxy8m1nqk9g3x3y3p0azq2c1 priceId: price_01hxy8m1nqk9g3x3y3p0azq2f1 description: Monthly subscription quantity: 2 unitAmount: 2500 manualAdjustmentLines: summary: Manual adjustment lines (tax/shipping) value: idempotencyKey: idem-inv-02 merchantId: mer_01hxy8m1nqk9g3x3y3p0azq2bg customerId: cust_01hxy8m1nqk9g3x3y3p0azq2zz currency: usd lineItems: - kind: manual_adjustment description: Sales tax amount: 1300 - kind: manual_adjustment description: Promotional discount amount: -500 mixedLines: summary: Mixed product and manual line items value: idempotencyKey: idem-inv-03 merchantId: mer_01hxy8m1nqk9g3x3y3p0azq2bg customerId: cust_01hxy8m1nqk9g3x3y3p0azq2zz currency: usd lineItems: - kind: product_charge productId: prod_01hxy8m1nqk9g3x3y3p0azq2c1 description: Consulting package quantity: 1 unitAmount: 10000 - kind: manual_adjustment description: Tax amount: 800 dueDate: '2026-08-15T00:00:00.000Z' responses: '201': description: >- Draft invoice created successfully with assigned invoice number and computed totals. content: application/json: schema: $ref: '#/components/schemas/InvoiceResponseDto' '400': description: >- Validation failed (invalid TypeIDs, empty line items, non-integer amounts, currency mismatch, or non-positive total). '401': description: Missing or invalid authentication credentials. '403': description: >- Authenticated principal lacks `invoices.create` capability or merchant scope. security: - bearer: [] components: schemas: CreateInvoiceDto: type: object properties: idempotencyKey: type: string minLength: 1 merchantId: type: string customerId: type: string currency: description: Supported currency code (USD, CAD) type: string minLength: 3 maxLength: 3 lineItems: minItems: 1 type: array items: oneOf: - type: object properties: kind: type: string enum: - product_charge productId: type: string priceId: type: string description: type: string minLength: 1 maxLength: 500 quantity: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 unitAmount: type: integer minimum: 0 maximum: 9007199254740991 required: - kind - productId - description - quantity - unitAmount additionalProperties: false - type: object properties: kind: type: string enum: - manual_adjustment description: type: string minLength: 1 maxLength: 500 amount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 quantity: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 required: - kind - description - amount additionalProperties: false dueDate: type: string format: date-time pattern: >- ^(?:(?:\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))$ notes: type: string maxLength: 2000 metadata: type: object additionalProperties: {} required: - idempotencyKey - merchantId - customerId - currency - lineItems InvoiceResponseDto: type: object properties: invoiceId: type: string invoiceNumber: type: string minLength: 1 invoiceUrlSlug: type: string minLength: 1 description: >- Secret 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. idempotencyKey: type: string minLength: 1 merchantId: type: string customerId: type: string currentRevisionNumber: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 status: type: string enum: - draft - issued - partially_paid - paid - void currency: description: Supported currency code (USD, CAD) type: string minLength: 3 maxLength: 3 lineItems: type: array items: oneOf: - type: object properties: kind: type: string enum: - product_charge productId: type: string priceId: type: string description: type: string minLength: 1 maxLength: 500 quantity: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 unitAmount: type: integer minimum: 0 maximum: 9007199254740991 lineTotal: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - kind - productId - description - quantity - unitAmount - lineTotal additionalProperties: false - type: object properties: kind: type: string enum: - manual_adjustment description: type: string minLength: 1 maxLength: 500 amount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 quantity: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 lineTotal: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - kind - description - amount - quantity - lineTotal additionalProperties: false productTotal: type: object properties: amount: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 currency: description: Supported currency code (USD, CAD) type: string minLength: 3 maxLength: 3 required: - amount - currency total: type: object properties: amount: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 currency: description: Supported currency code (USD, CAD) type: string minLength: 3 maxLength: 3 required: - amount - currency amountPaid: type: object properties: amount: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 currency: description: Supported currency code (USD, CAD) type: string minLength: 3 maxLength: 3 required: - amount - currency description: Sum of applied payment allocations, both processed and out-of-band. amountRemaining: type: object properties: amount: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 currency: description: Supported currency code (USD, CAD) type: string minLength: 3 maxLength: 3 required: - amount - currency description: >- Computed as `total` minus `amountPaid`. Zero when the invoice is fully paid. dueDate: type: string format: date-time pattern: >- ^(?:(?:\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))$ paidAt: type: string format: date-time pattern: >- ^(?:(?:\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))$ notes: type: string metadata: type: object additionalProperties: {} createdAt: type: string format: date-time pattern: >- ^(?:(?:\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))$ updatedAt: type: string format: date-time pattern: >- ^(?:(?:\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))$ required: - invoiceId - invoiceNumber - invoiceUrlSlug - idempotencyKey - merchantId - customerId - currentRevisionNumber - status - currency - lineItems - productTotal - total - amountPaid - amountRemaining - createdAt - updatedAt securitySchemes: bearer: scheme: bearer bearerFormat: merchant__ type: http description: >- Merchant API key bearer token. Legacy wire prefixes `api_key_` and `api_` are also accepted. ````