> ## Documentation Index
> Fetch the complete documentation index at: https://docs.marro.si/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a invoice

> A invoice for a lead (its customer details are taken from the lead unless given) or for a customer with no lead. Prices are before GST; GST is worked out from the organization's and the customer's states. A draft unless `issue` is true, which gives it its number and marks it sent. Issuing fires "An invoice is sent" automations. Not idempotent: reconcile an uncertain request before retrying.

Scope: `money.write`.



## OpenAPI

````yaml /openapi.json post /api/v1/invoices
openapi: 3.1.0
info:
  title: Marro API
  version: 1.0.0
  description: >-
    Server-to-server access to one organization’s data in Marro. Each key
    belongs to an organization and can use only the scopes it was given for
    modules the organization subscribes to. Keys go only in the Authorization
    header, over HTTPS, from a server: never in browser code or a URL. A key
    that was ever sent over plain HTTP or in a URL must be treated as leaked:
    revoke it and create a new one. The API sends no CORS headers.


    Every response carries `X-Request-Id`, to quote to support. Once the key is
    checked, responses also carry `RateLimit-Limit`, `RateLimit-Remaining` and
    `RateLimit-Reset` (seconds until the window resets) for whichever limit is
    closer to running out. An address that is not an endpoint answers 404
    `NOT_FOUND` in the same error shape.
servers:
  - url: https://app.marro.si
security: []
tags:
  - name: Leads
    description: >-
      Record-link custom fields accept numeric target ID arrays (one or up to 20
      according to recordLink.multiple). Reads resolve accessible targets to
      id/kind/name/href objects. Deleted, archived, disabled and inaccessible
      targets are omitted. Destinations require the corresponding leads.read or
      crm.records.read scope; user destinations have no public API scope. Object
      destinations use object:<id>, require objects.records.read and the key
      creator current object grants.
  - name: Customers
    description: >-
      Contacts, companies and enabled opportunities with record-type custom
      fields. Dedicated crm.records scopes are required.
  - name: Reference
    description: 'How this organization is set up: fields, stages, sources and people.'
  - name: Money
    description: >-
      Products, quotes, invoices and payments. Amounts are integers in the
      smallest currency unit (paise, cents); a new document is in the
      organization's own currency. Tax follows the organization's regional
      settings: under India GST an invoice carries CGST and SGST inside the
      organization's state, IGST outside it, and no GST without a supplier
      GSTIN; under a single-rate tax (Australia GST 10%, UK VAT) each taxed line
      carries that tax (singleTaxMinor), and none without the supplier's
      registration number. Each document keeps the tax it was issued under
      (tax.model).
  - name: Reports
    description: >-
      Custom reports shared with everyone in the organization, and their
      figures. Built in the app under Reports → Custom reports; a key reads them
      over every lead.
paths:
  /api/v1/invoices:
    post:
      tags:
        - Money
      summary: Create a invoice
      description: >-
        A invoice for a lead (its customer details are taken from the lead
        unless given) or for a customer with no lead. Prices are before GST; GST
        is worked out from the organization's and the customer's states. A draft
        unless `issue` is true, which gives it its number and marks it sent.
        Issuing fires "An invoice is sent" automations. Not idempotent:
        reconcile an uncertain request before retrying.


        Scope: `money.write`.
      operationId: create-invoice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                leadId:
                  anyOf:
                    - type: integer
                      exclusiveMinimum: 0
                      maximum: 2147483647
                    - type: 'null'
                issueDate:
                  type: string
                  pattern: ^\d{4}-\d{2}-\d{2}$
                  description: YYYY-MM-DD.
                dueDate:
                  anyOf:
                    - type: string
                      pattern: ^\d{4}-\d{2}-\d{2}$
                      description: YYYY-MM-DD.
                    - type: 'null'
                customer:
                  description: 'Left out: taken from the lead.'
                  type: object
                  properties:
                    name:
                      type: string
                      minLength: 1
                      maxLength: 200
                    phone:
                      anyOf:
                        - type: string
                          maxLength: 20
                        - type: 'null'
                    email:
                      anyOf:
                        - type: string
                          maxLength: 200
                        - type: 'null'
                    gstin:
                      anyOf:
                        - type: string
                          maxLength: 15
                        - type: 'null'
                    taxNumber:
                      anyOf:
                        - type: string
                          maxLength: 40
                        - type: 'null'
                    stateCode:
                      anyOf:
                        - type: string
                          pattern: ^\d{2}$
                        - type: 'null'
                    address:
                      type: string
                      maxLength: 500
                  required:
                    - name
                placeOfSupply:
                  anyOf:
                    - type: string
                      pattern: ^\d{2}$
                    - type: 'null'
                lines:
                  minItems: 1
                  maxItems: 100
                  type: array
                  items:
                    type: object
                    properties:
                      productId:
                        anyOf:
                          - type: integer
                            exclusiveMinimum: 0
                            maximum: 2147483647
                          - type: 'null'
                      name:
                        type: string
                        minLength: 1
                        maxLength: 200
                      description:
                        type: string
                        maxLength: 1000
                      hsnSac:
                        type: string
                        maxLength: 8
                      unit:
                        type: string
                        maxLength: 20
                      quantity:
                        type: number
                        exclusiveMinimum: 0
                      unitPrice:
                        type: number
                        minimum: 0
                        description: >-
                          In the main unit of the organization's currency
                          (rupees, dollars), before tax unless its prices
                          include tax.
                      discount:
                        description: '"10%" or an amount in the main unit.'
                        type: string
                        maxLength: 20
                      gstRate:
                        description: 'India GST only: GST in percent. Defaults to 0.'
                        anyOf:
                          - type: number
                            const: 0
                          - type: number
                            const: 5
                          - type: number
                            const: 12
                          - type: number
                            const: 18
                          - type: number
                            const: 28
                      taxRateBasisPoints:
                        description: >-
                          Single-rate tax only: 0 for a tax-free line; left out,
                          the organization's rate.
                        type: integer
                        minimum: 0
                        maximum: 10000
                    required:
                      - name
                      - quantity
                      - unitPrice
                notes:
                  type: string
                  maxLength: 4000
                terms:
                  type: string
                  maxLength: 4000
                issue:
                  description: >-
                    true: give it its number and mark it sent at once. Otherwise
                    it stays a draft.
                  type: boolean
              required:
                - issueDate
                - lines
            example:
              leadId: 1842
              issueDate: '2026-11-12'
              issue: true
              lines:
                - productId: 7
                  name: Teeth whitening
                  quantity: 1
                  unitPrice: 15000
                  discount: 10%
                  gstRate: 18
      responses:
        '201':
          description: The invoice as saved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoice:
                    $ref: '#/components/schemas/SalesDocument'
                required:
                  - invoice
                additionalProperties: false
              example:
                invoice:
                  id: 311
                  kind: invoice
                  number: INV/2026-27/0042
                  status: sent
                  overdue: false
                  leadId: 1842
                  quoteId: 298
                  currency: INR
                  issueDate: '2026-11-12'
                  dueDate: '2026-11-19'
                  customer:
                    name: Priya Sharma
                    gstin: null
                    address: Banjara Hills, Hyderabad
                    stateCode: '36'
                    phone: '+919812345678'
                    email: priya@example.com
                  supplier:
                    name: Bright Smiles Dental
                    gstin: 36ABCDE1234F1Z5
                    address: Jubilee Hills, Hyderabad
                    stateCode: '36'
                    phone: null
                    email: accounts@example.com
                  placeOfSupply: '36'
                  taxMode: intra
                  tax:
                    model: in_gst
                    label: null
                    registrationLabel: null
                    inclusive: false
                  singleTaxMinor: 0
                  subtotalMinor: 1500000
                  discountMinor: 150000
                  taxableMinor: 1350000
                  cgstMinor: 121500
                  sgstMinor: 121500
                  igstMinor: 0
                  roundOffMinor: 0
                  totalMinor: 1593000
                  paidMinor: 0
                  dueMinor: 1593000
                  createdAt: '2026-11-12T05:30:00Z'
        '400':
          description: >-
            VALIDATION_FAILED: A line, date, GSTIN or state is not valid; the
            message says which.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'UNAUTHORIZED: The key is missing, wrong, revoked or expired.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            FORBIDDEN: The key lacks the scope, or the organization’s plan does
            not include it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'NOT_FOUND: leadId names no lead in this organization.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            SETUP_REQUIRED: issue is true for an invoice before the business
            details are set in Settings → Quotes and invoices.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            RATE_LIMITED: More than 600 requests in an hour with this key, or
            3000 with all of the organization’s keys together. `Retry-After`
            says how many seconds to wait.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: >-
            INTERNAL: Something failed on our side. Retry; if it persists,
            contact support quoting the `X-Request-Id` response header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKey:
            - money.write
components:
  schemas:
    SalesDocument:
      type: object
      properties:
        id:
          type: integer
          exclusiveMinimum: 0
          maximum: 2147483647
        kind:
          type: string
          enum:
            - quote
            - invoice
        number:
          description: >-
            Null while a draft. Invoices: PREFIX/2026-27/0001, a new series each
            April.
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - draft
            - sent
            - accepted
            - declined
            - partly_paid
            - paid
            - void
        overdue:
          type: boolean
          description: A sent, unpaid invoice past its due date.
        leadId:
          anyOf:
            - type: integer
              exclusiveMinimum: 0
              maximum: 2147483647
            - type: 'null'
        quoteId:
          anyOf:
            - type: integer
              exclusiveMinimum: 0
              maximum: 2147483647
            - type: 'null'
          description: For an invoice made from a quote.
        currency:
          type: string
        issueDate:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: YYYY-MM-DD.
        dueDate:
          anyOf:
            - type: string
              pattern: ^\d{4}-\d{2}-\d{2}$
              description: YYYY-MM-DD.
            - type: 'null'
          description: A quote's valid-until day, an invoice's due day.
        customer:
          $ref: '#/components/schemas/DocumentParty'
        supplier:
          $ref: '#/components/schemas/DocumentParty'
        placeOfSupply:
          type:
            - string
            - 'null'
        taxMode:
          type: string
          enum:
            - intra
            - inter
            - none
          description: >-
            India GST only. intra: CGST and SGST; inter: IGST; none: no GST (no
            supplier GSTIN, or another tax model).
        tax:
          type: object
          properties:
            model:
              type: string
              enum:
                - in_gst
                - single
                - none
              description: >-
                The tax the document was issued under: India GST, one named tax
                (Australia GST, UK VAT), or none. It never changes after issue.
            label:
              description: The single tax's name, like "GST" or "VAT".
              type:
                - string
                - 'null'
            registrationLabel:
              description: What the registration number is called, like "ABN".
              type:
                - string
                - 'null'
            inclusive:
              type: boolean
              description: Whether the prices include the single tax.
          required:
            - model
            - label
            - registrationLabel
            - inclusive
          additionalProperties: false
        singleTaxMinor:
          description: The single-rate tax charged; 0 under India GST.
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        subtotalMinor:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: >-
            In the smallest unit of the currency (paise for rupees, cents for
            dollars).
        discountMinor:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: >-
            In the smallest unit of the currency (paise for rupees, cents for
            dollars).
        taxableMinor:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: >-
            In the smallest unit of the currency (paise for rupees, cents for
            dollars).
        cgstMinor:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: >-
            In the smallest unit of the currency (paise for rupees, cents for
            dollars).
        sgstMinor:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: >-
            In the smallest unit of the currency (paise for rupees, cents for
            dollars).
        igstMinor:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: >-
            In the smallest unit of the currency (paise for rupees, cents for
            dollars).
        roundOffMinor:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: >-
            In the smallest unit of the currency (paise for rupees, cents for
            dollars).
        totalMinor:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: >-
            In the smallest unit of the currency (paise for rupees, cents for
            dollars).
        paidMinor:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: >-
            In the smallest unit of the currency (paise for rupees, cents for
            dollars).
        dueMinor:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: >-
            In the smallest unit of the currency (paise for rupees, cents for
            dollars).
        lines:
          description: Only when reading one document.
          type: array
          items:
            $ref: '#/components/schemas/DocumentLine'
        createdAt:
          type: string
      required:
        - id
        - kind
        - number
        - status
        - overdue
        - leadId
        - quoteId
        - currency
        - issueDate
        - dueDate
        - customer
        - supplier
        - placeOfSupply
        - taxMode
        - subtotalMinor
        - discountMinor
        - taxableMinor
        - cgstMinor
        - sgstMinor
        - igstMinor
        - roundOffMinor
        - totalMinor
        - paidMinor
        - dueMinor
        - createdAt
      additionalProperties: false
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: >-
                Stable, machine-readable: UNAUTHORIZED, FORBIDDEN, NOT_FOUND,
                VALIDATION_FAILED, DUPLICATE_LEAD, RATE_LIMITED…
            message:
              type: string
              description: A sentence for people.
            details:
              description: >-
                For VALIDATION_FAILED, `fields` maps each field key to its
                problem.
              type: object
              propertyNames:
                type: string
              additionalProperties: {}
          required:
            - code
            - message
          additionalProperties: false
      required:
        - error
      additionalProperties: false
    DocumentParty:
      type: object
      properties:
        name:
          type: string
        gstin:
          type:
            - string
            - 'null'
        address:
          type: string
        stateCode:
          description: GST state code, like "29" for Karnataka.
          type:
            - string
            - 'null'
        phone:
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
        taxNumber:
          description: >-
            Under a single-rate tax: the registration number, like an Australian
            ABN.
          type:
            - string
            - 'null'
      required:
        - name
        - gstin
        - address
        - stateCode
        - phone
        - email
      additionalProperties: false
    DocumentLine:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        hsnSac:
          type: string
        unit:
          type: string
        quantity:
          type: number
          description: Up to three decimals.
        unitPriceMinor:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: >-
            In the smallest unit of the currency (paise for rupees, cents for
            dollars).
        discountMinor:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: >-
            In the smallest unit of the currency (paise for rupees, cents for
            dollars).
        gstRate:
          anyOf:
            - type: number
              const: 0
            - type: number
              const: 5
            - type: number
              const: 12
            - type: number
              const: 18
            - type: number
              const: 28
          description: GST in percent.
        taxRateBasisPoints:
          anyOf:
            - type: integer
              minimum: 0
              maximum: 10000
              description: >-
                Single-rate tax only: the line's rate in basis points (1000 =
                10%; 0 = tax-free).
            - type: 'null'
        taxableMinor:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: >-
            In the smallest unit of the currency (paise for rupees, cents for
            dollars).
        taxMinor:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: >-
            In the smallest unit of the currency (paise for rupees, cents for
            dollars).
        totalMinor:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: >-
            In the smallest unit of the currency (paise for rupees, cents for
            dollars).
      required:
        - name
        - description
        - hsnSac
        - unit
        - quantity
        - unitPriceMinor
        - discountMinor
        - gstRate
        - taxableMinor
        - taxMinor
        - totalMinor
      additionalProperties: false
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      description: >-
        An organization API key, created in Settings → Integrations → API keys.
        Keys start with `mk_live_`. Marro stores only a hash of a key, so it is
        shown once, when it is created: copy it then. Revoking a key ends its
        access at once. To replace a key without downtime, create the new one,
        switch your server to it, then revoke the old one. Changes made with a
        key appear on the lead’s timeline as made by the person who created the
        key, via the API. Scopes: `objects.records.read` (Read custom objects),
        `objects.records.write` (Create and update custom-object records),
        `objects.records.delete` (Delete custom-object records), `leads.read`
        (Read leads), `leads.write` (Create and update leads), `leads.capture`
        (Capture leads), `crm.records.read` (Read customers and opportunities),
        `crm.records.write` (Create and update customers and opportunities),
        `reports.read` (Read reports), `money.read` (Read products, quotes,
        invoices and payments), `money.write` (Create quotes and invoices and
        record payments), `agent.tools` (AI agent tools (MCP)).
      x-scopes:
        objects.records.read:
          label: Read custom objects
          description: >-
            Read definitions and records within the key creator’s current
            per-object access.
          module: objects
        objects.records.write:
          label: Create and update custom-object records
          description: >-
            Create and edit within current per-object grants. Needs
            objects.records.read.
          module: objects
        objects.records.delete:
          label: Delete custom-object records
          description: >-
            Permanently delete with current object delete grant, version and
            exact title. Needs objects.records.read.
          module: objects
        leads.read:
          label: Read leads
          description: >-
            Leads with every field, and the lists that describe them: fields,
            stages, sources and people.
          module: leads
        leads.write:
          label: Create and update leads
          description: >-
            Create leads, change their fields, stage and owner, and add notes.
            Needs leads.read.
          module: leads
        leads.capture:
          label: Capture leads
          description: >-
            Capture leads from a website or form: add a lead or update the
            existing one with the same phone or email. Cannot read, list or
            change anything else.
          module: leads
        crm.records.read:
          label: Read customers and opportunities
          description: >-
            Read contacts, companies and enabled opportunities, including their
            custom fields.
          module: customers
        crm.records.write:
          label: Create and update customers and opportunities
          description: >-
            Create and update contacts, companies and enabled opportunities with
            validated custom fields. Needs crm.records.read.
          module: customers
        reports.read:
          label: Read reports
          description: >-
            List the custom reports shared with everyone in the organization and
            read their figures for any period.
          module: reports.custom
        money.read:
          label: Read products, quotes, invoices and payments
          description: >-
            Read the product catalogue, quotes and GST invoices with their lines
            and totals, and payments received.
          module: finance.quotes
        money.write:
          label: Create quotes and invoices and record payments
          description: >-
            Create quotes and invoices (as drafts, or issued with their number)
            and record payments against invoices. Needs money.read.
          module: finance.quotes
        agent.tools:
          label: AI agent tools (MCP)
          description: >-
            Connect another AI agent over MCP: find and read leads, see what
            your agents may do, and ask Marro's agent to act on a lead within
            your agents' permissions.
          module: ai.agents
      x-key-types:
        - name: Website form
          scopes:
            - leads.capture
          lifetimeDays: 730
          description: >-
            A website or landing-page form that sends enquiries in as leads. Can
            do nothing else.
        - name: Another application
          lifetimeDays: 90
          description: >-
            Any other integration. Choose the scopes it needs when you create
            it.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.