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

# Create one invoice per contact in an audience (bulk).

> Bills a whole class, segment, tag or list of contacts with the same line items: one invoice per contact, each with its own number from the workspace sequence. Name exactly one audience: contact_ids (up to 1000 contact uuids), segment_id (a segment uuid), tag (a tag uuid or name) or class_session_id (a class session uuid; its roster is everyone booked, attended or marked no-show). line_items, currency, dates, client_notes and discount_total take the same shape as POST /invoices. The run is queued and returns 202 with its summary, whose id you poll on the retrieve-a-bulk-run endpoint. Contacts that no longer exist are skipped and listed with a reason. With send true, each invoice is posted and delivered on WhatsApp, else SMS, else email (or on the channels you name), under the same opt-out and template rules as sending one invoice; anyone not reached is listed under not_delivered. Each invoice fires its invoice.created (and, when sent, invoice.sent) event from a background job, once per invoice: webhooks always hear it, and run_automations (default true) decides whether the workspace automations for those events start. Pass run_automations false to raise the run without them. A retried run never raises a second invoice for a contact, and never fires an invoice event twice.



## OpenAPI

````yaml /api-reference/openapi.json post /invoices/bulk
openapi: 3.1.0
info:
  title: DMLY REST API
  version: 1.0.0
  description: >-
    DMLY's public REST API — contacts/CRM, the unified inbox, broadcasts and
    automations,

    appointments and classes, the commerce catalogue, finance, webhooks and
    media.


    ## Authentication


    Every request carries a **workspace API key**, which both authenticates the
    caller and

    selects the workspace — so there is no workspace id in the URL.


    ```

    x-api-key: dmly_xxxxxxxx…

    ```


    `Authorization: Bearer dmly_xxxxxxxx…` is also accepted.


    Mint keys from the DMLY dashboard (Salesbot → Integrations → API), or from
    the CLI with

    `php artisan dmly:api-key create`. The plaintext key is shown **once** on
    creation; only

    its sha256 hash is stored.


    ## Conventions


    - Resources are identified by their public `uuid`, returned as `id`.

    - Lists are paginated with `?per_page` (alias `?limit`) — default 25, hard
    cap 100 — and
      return `{ "data": [...], "links": {...}, "meta": {...} }`.
    - Single resources return `{ "data": { ... } }`.


    ## Rate limiting


    **60 requests per minute, per API key.** Each key gets its own budget, so
    two integrations

    calling from the same server or office network do not compete, as long as
    they use separate

    keys. Requests without a valid key (missing, mistyped, or revoked) share one
    60/minute

    budget per IP address instead; they fail with `401` regardless.


    Exceeding the limit returns `429` with a `Retry-After` header and a JSON
    body:

    `{"message": "Too many requests. Retry after 42 seconds."}`. Full detail:

    [Rate limits](/api-reference/rate-limits).
  contact:
    name: DMLY
    url: https://dmly.io
servers:
  - url: https://dash.dmly.io/api/v1
    description: DMLY
security:
  - apiKeyAuth: []
  - bearerAuth: []
tags:
  - name: Account
    description: Endpoints for Account.
  - name: Channels
    description: Endpoints for Channels.
  - name: Contacts
    description: Endpoints for Contacts.
  - name: Tags
    description: Endpoints for Tags.
  - name: Segments
    description: Endpoints for Segments.
  - name: Conversations & Messages
    description: Endpoints for Conversations & Messages.
  - name: Broadcasts
    description: Endpoints for Broadcasts.
  - name: Automations
    description: Endpoints for Automations.
  - name: Appointments
    description: Endpoints for Appointments.
  - name: Services & Service Categories
    description: Endpoints for Services & Service Categories.
  - name: Staff
    description: Endpoints for Staff.
  - name: Classes
    description: Endpoints for Classes.
  - name: Offerings — Products & Plans
    description: Endpoints for Offerings — Products & Plans.
  - name: Finance — Invoices
    description: Endpoints for Finance — Invoices.
  - name: Finance — Orders
    description: Endpoints for Finance — Orders.
  - name: Finance — Payments & Coupons
    description: Endpoints for Finance — Payments & Coupons.
  - name: Finance — Subscriptions
    description: Endpoints for Finance — Subscriptions.
  - name: Gift Cards
    description: Endpoints for Gift Cards.
  - name: Webhooks
    description: Endpoints for Webhooks.
  - name: Media
    description: Endpoints for Media.
  - name: Webhooks Contacts and clients
    description: 'Webhook events: Contacts & clients.'
  - name: Webhooks Conversations
    description: 'Webhook events: Conversations.'
  - name: Webhooks Calls
    description: 'Webhook events: Calls.'
  - name: Webhooks Message lifecycle
    description: 'Webhook events: Message lifecycle.'
  - name: Webhooks Appointments
    description: 'Webhook events: Appointments.'
  - name: Webhooks Classes
    description: 'Webhook events: Classes.'
  - name: Webhooks Invoices
    description: 'Webhook events: Invoices.'
  - name: Webhooks Orders
    description: 'Webhook events: Orders.'
  - name: Webhooks Payments
    description: 'Webhook events: Payments.'
  - name: Webhooks Subscriptions
    description: 'Webhook events: Subscriptions.'
  - name: Webhooks Offerings and credits
    description: 'Webhook events: Offerings & credits.'
  - name: Webhooks Store e commerce
    description: 'Webhook events: Store (e-commerce).'
  - name: Webhooks Automations
    description: 'Webhook events: Automations.'
  - name: Webhooks Broadcasts
    description: 'Webhook events: Broadcasts.'
paths:
  /invoices/bulk:
    post:
      tags:
        - Finance — Invoices
      summary: Create one invoice per contact in an audience (bulk).
      description: >-
        Bills a whole class, segment, tag or list of contacts with the same line
        items: one invoice per contact, each with its own number from the
        workspace sequence. Name exactly one audience: contact_ids (up to 1000
        contact uuids), segment_id (a segment uuid), tag (a tag uuid or name) or
        class_session_id (a class session uuid; its roster is everyone booked,
        attended or marked no-show). line_items, currency, dates, client_notes
        and discount_total take the same shape as POST /invoices. The run is
        queued and returns 202 with its summary, whose id you poll on the
        retrieve-a-bulk-run endpoint. Contacts that no longer exist are skipped
        and listed with a reason. With send true, each invoice is posted and
        delivered on WhatsApp, else SMS, else email (or on the channels you
        name), under the same opt-out and template rules as sending one invoice;
        anyone not reached is listed under not_delivered. Each invoice fires its
        invoice.created (and, when sent, invoice.sent) event from a background
        job, once per invoice: webhooks always hear it, and run_automations
        (default true) decides whether the workspace automations for those
        events start. Pass run_automations false to raise the run without them.
        A retried run never raises a second invoice for a contact, and never
        fires an invoice event twice.
      operationId: invoices.bulk.store.post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                segment_id:
                  type: string
                  format: uuid
                currency:
                  type: string
                issue_date:
                  type: string
                  format: date
                due_date:
                  type: string
                  format: date
                client_notes:
                  type: string
                line_items:
                  type: array
                  items:
                    type: object
                    properties:
                      item_type:
                        type: string
                      name:
                        type: string
                      description:
                        type: string
                      unit_price:
                        type: number
                      quantity:
                        type: integer
                      tax:
                        type: object
                        properties:
                          rate:
                            type: integer
                          inclusive:
                            type: boolean
                send:
                  type: boolean
                run_automations:
                  type: boolean
                  default: true
                contact_ids:
                  type: array
                  items:
                    type: string
                    format: uuid
                tag:
                  type: string
                class_session_id:
                  type: string
                  format: uuid
                discount_total:
                  type: number
                channels:
                  type: array
                  items:
                    type: string
                    enum:
                      - whatsapp
                      - sms
                      - email
              required:
                - line_items
            example:
              segment_id: 5b2a8f0e-1c3d-4e5f-9a7b-6c8d0e1f2a3b
              currency: USD
              issue_date: '2026-09-01'
              due_date: '2026-09-15'
              client_notes: Autumn term tuition.
              line_items:
                - item_type: custom
                  name: Autumn term tuition
                  unit_price: 450
                  quantity: 1
              send: true
              run_automations: true
      responses:
        '202':
          description: Accepted. The run is queued; the body is its summary.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  responses:
    Unauthorized:
      description: The API key is missing, invalid, or its workspace no longer exists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: >-
        The workspace for this API key has been suspended, either directly or
        because its agency is no longer active.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: No such resource in this workspace.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: Validation failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
    RateLimited:
      description: >-
        Rate limit exceeded: 60 requests per minute per API key. Requests
        without a valid key share a per-IP budget instead.
      headers:
        Retry-After:
          description: Seconds until the limit resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
    ValidationError:
      type: object
      properties:
        message:
          type: string
        errors:
          type: object
          description: Field name → array of messages.
          additionalProperties:
            type: array
            items:
              type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your workspace API key. It both authenticates the caller and selects the
        workspace.
    bearerAuth:
      type: http
      scheme: bearer
      description: 'The same workspace API key, sent as `Authorization: Bearer <key>`.'

````

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