Stripe Invoice API — Invoices

naftiko: 1.0.0-alpha2
info:
  label: Stripe Invoice API — Invoices
  description: 'Stripe Invoice API — Invoices. 15 operations. Lead operation: Invoices. Self-contained Naftiko capability
    covering one Stripe business surface.'
  tags:
  - Stripe
  - Invoices
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    STRIPE_API_KEY: STRIPE_API_KEY
capability:
  consumes:
  - type: http
    namespace: invoice-invoices
    baseUri: https://api.stripe.com
    description: Stripe Invoice API — Invoices business capability. Self-contained, no shared references.
    resources:
    - name: v1-invoices
      path: /v1/invoices
      operations:
      - name: getinvoices
        method: GET
        description: <p>You can list all invoices, or list the invoices for a specific customer. The invoices are returned
          sorted by creation date, with the most recently created invoices appearing first.</p>
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: collection_method
          in: query
          type: string
          description: The collection method of the invoice to retrieve. Either `charge_automatically` or `send_invoice`.
        - name: created
          in: query
          type: string
        - name: customer
          in: query
          type: string
          description: Only return invoices for the customer specified by this customer ID.
        - name: due_date
          in: query
          type: string
        - name: ending_before
          in: query
          type: string
          description: A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list.
            For instance, if you make a list request and receive 100 ob
        - name: expand
          in: query
          type: array
          description: Specifies which fields in the response should be expanded.
        - name: limit
          in: query
          type: integer
          description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default
            is 10.
        - name: starting_after
          in: query
          type: string
          description: A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list.
            For instance, if you make a list request and receive 100 o
        - name: status
          in: query
          type: string
          description: The status of the invoice, one of `draft`, `open`, `paid`, `uncollectible`, or `void`. [Learn more](https://stripe.com/docs/billing/invoices/workflow#workflow-o
        - name: subscription
          in: query
          type: string
          description: Only return invoices for the subscription specified by this subscription ID.
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: postinvoices
        method: POST
        description: <p>This endpoint creates a draft invoice for a given customer. The invoice remains a draft until you
          <a href="#finalize_invoice">finalize</a> the invoice, which allows you to <a href="#pay_invoice">pay</a> or <a href="#send_invoice">send</a
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: v1-invoices-search
      path: /v1/invoices/search
      operations:
      - name: getinvoicessearch
        method: GET
        description: <p>Search for invoices you’ve previously created using Stripe’s <a href="/docs/search#search-query-language">Search
          Query Language</a>.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: expand
          in: query
          type: array
          description: Specifies which fields in the response should be expanded.
        - name: limit
          in: query
          type: integer
          description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default
            is 10.
        - name: page
          in: query
          type: string
          description: A cursor for pagination across multiple pages of results. Don't include this parameter on the first
            call. Use the next_page value returned in a previous respons
        - name: query
          in: query
          type: string
          description: The search query string. See [search query language](https://stripe.com/docs/search#search-query-language)
            and the list of supported [query fields for invoices]
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: v1-invoices-upcoming
      path: /v1/invoices/upcoming
      operations:
      - name: getinvoicesupcoming
        method: GET
        description: <p>At any time, you can preview the upcoming invoice for a customer. This will show you all the charges
          that are pending, including subscription renewal charges, invoice item charges, etc. It will also show you any discounts
          that are applic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: automatic_tax
          in: query
          type: object
          description: Settings for automatic tax lookup for this invoice preview.
        - name: coupon
          in: query
          type: string
          description: The code of the coupon to apply. If `subscription` or `subscription_items` is provided, the invoice
            returned will preview updating or creating a subscription wi
        - name: currency
          in: query
          type: string
          description: The currency to preview this invoice in. Defaults to that of `customer` if not specified.
        - name: customer
          in: query
          type: string
          description: The identifier of the customer whose upcoming invoice you'd like to retrieve. If `automatic_tax` is
            enabled then one of `customer`, `customer_details`, `subscri
        - name: customer_details
          in: query
          type: object
          description: 'Details about the customer you want to invoice or overrides for an existing customer. If `automatic_tax`
            is enabled then one of `customer`, `customer_details`, '
        - name: discounts
          in: query
          type: string
          description: The coupons to redeem into discounts for the invoice preview. If not specified, inherits the discount
            from the customer or subscription. This only works for cou
        - name: expand
          in: query
          type: array
          description: Specifies which fields in the response should be expanded.
        - name: invoice_items
          in: query
          type: array
          description: List of invoice items to add or update in the upcoming invoice preview.
        - name: schedule
          in: query
          type: string
          description: The identifier of the schedule whose upcoming invoice you'd like to retrieve. Cannot be used with subscription
            or subscription fields.
        - name: subscription
          in: query
          type: string
          description: The identifier of the subscription for which you'd like to retrieve the upcoming invoice. If not provided,
            but a `subscription_items` is provided, you will prev
        - name: subscription_billing_cycle_anchor
          in: query
          type: string
          description: For new subscriptions, a future timestamp to anchor the subscription's [billing cycle](https://stripe.com/docs/subscriptions/billing-cycle).
            This is used to det
        - name: subscription_cancel_at
          in: query
          type: string
          description: A timestamp at which the subscription should cancel. If set to a date before the current period ends,
            this will cause a proration if prorations have been enable
        - name: subscription_cancel_at_period_end
          in: query
          type: boolean
          description: Boolean indicating whether this subscription should cancel at the end of the current period.
        - name: subscription_cancel_now
          in: query
          type: boolean
          description: This simulates the subscription being canceled or expired immediately.
        - name: subscription_default_tax_rates
          in: query
          type: string
          description: If provided, the invoice returned will preview updating or creating a subscription with these default
            tax rates. The default tax rates will apply to any line it
        - name: subscription_items
          in: query
          type: array
          description: A list of up to 20 subscription items, each with an attached price.
        - name: subscription_proration_behavior
          in: query
          type: string
          description: Determines how to handle [prorations](https://stripe.com/docs/subscriptions/billing-cycle#prorations)
            when the billing cycle changes (e.g., when switching plans
        - name: subscription_proration_date
          in: query
          type: integer
          description: If previewing an update to a subscription, and doing proration, `subscription_proration_date` forces
            the proration to be calculated as though the update was don
        - name: subscription_resume_at
          in: query
          type: string
          description: For paused subscriptions, setting `subscription_resume_at` to `now` will preview the invoice that will
            be generated if the subscription is resumed.
        - name: subscription_start_date
          in: query
          type: integer
          description: Date a subscription is intended to start (can be future or past).
        - name: subscription_trial_end
          in: query
          type: string
          description: If provided, the invoice returned will preview updating or creating a subscription with that trial
            end. If set, one of `subscription_items` or `subscription` is
        - name: subscription_trial_from_plan
          in: query
          type: boolean
          description: Indicates if a plan's `trial_period_days` should be applied to the subscription. Setting `subscription_trial_end`
            per subscription is preferred, and this defaul
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: v1-invoices-upcoming-lines
      path: /v1/invoices/upcoming/lines
      operations:
      - name: getinvoicesupcominglines
        method: GET
        description: <p>When retrieving an upcoming invoice, you’ll get a <strong>lines</strong> property containing the total
          count of line items and the first handful of those items. There is also a URL where you can retrieve the full (paginated)
          list of line
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: automatic_tax
          in: query
          type: object
          description: Settings for automatic tax lookup for this invoice preview.
        - name: coupon
          in: query
          type: string
          description: The code of the coupon to apply. If `subscription` or `subscription_items` is provided, the invoice
            returned will preview updating or creating a subscription wi
        - name: currency
          in: query
          type: string
          description: The currency to preview this invoice in. Defaults to that of `customer` if not specified.
        - name: customer
          in: query
          type: string
          description: The identifier of the customer whose upcoming invoice you'd like to retrieve. If `automatic_tax` is
            enabled then one of `customer`, `customer_details`, `subscri
        - name: customer_details
          in: query
          type: object
          description: 'Details about the customer you want to invoice or overrides for an existing customer. If `automatic_tax`
            is enabled then one of `customer`, `customer_details`, '
        - name: discounts
          in: query
          type: string
          description: The coupons to redeem into discounts for the invoice preview. If not specified, inherits the discount
            from the customer or subscription. This only works for cou
        - name: ending_before
          in: query
          type: string
          description: A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list.
            For instance, if you make a list request and receive 100 ob
        - name: expand
          in: query
          type: array
          description: Specifies which fields in the response should be expanded.
        - name: invoice_items
          in: query
          type: array
          description: List of invoice items to add or update in the upcoming invoice preview.
        - name: limit
          in: query
          type: integer
          description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default
            is 10.
        - name: schedule
          in: query
          type: string
          description: The identifier of the schedule whose upcoming invoice you'd like to retrieve. Cannot be used with subscription
            or subscription fields.
        - name: starting_after
          in: query
          type: string
          description: A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list.
            For instance, if you make a list request and receive 100 o
        - name: subscription
          in: query
          type: string
          description: The identifier of the subscription for which you'd like to retrieve the upcoming invoice. If not provided,
            but a `subscription_items` is provided, you will prev
        - name: subscription_billing_cycle_anchor
          in: query
          type: string
          description: For new subscriptions, a future timestamp to anchor the subscription's [billing cycle](https://stripe.com/docs/subscriptions/billing-cycle).
            This is used to det
        - name: subscription_cancel_at
          in: query
          type: string
          description: A timestamp at which the subscription should cancel. If set to a date before the current period ends,
            this will cause a proration if prorations have been enable
        - name: subscription_cancel_at_period_end
          in: query
          type: boolean
          description: Boolean indicating whether this subscription should cancel at the end of the current period.
        - name: subscription_cancel_now
          in: query
          type: boolean
          description: This simulates the subscription being canceled or expired immediately.
        - name: subscription_default_tax_rates
          in: query
          type: string
          description: If provided, the invoice returned will preview updating or creating a subscription with these default
            tax rates. The default tax rates will apply to any line it
        - name: subscription_items
          in: query
          type: array
          description: A list of up to 20 subscription items, each with an attached price.
        - name: subscription_proration_behavior
          in: query
          type: string
          description: Determines how to handle [prorations](https://stripe.com/docs/subscriptions/billing-cycle#prorations)
            when the billing cycle changes (e.g., when switching plans
        - name: subscription_proration_date
          in: query
          type: integer
          description: If previewing an update to a subscription, and doing proration, `subscription_proration_date` forces
            the proration to be calculated as though the update was don
        - name: subscription_resume_at
          in: query
          type: string
          description: For paused subscriptions, setting `subscription_resume_at` to `now` will preview the invoice that will
            be generated if the subscription is resumed.
        - name: subscription_start_date
          in: query
          type: integer
          description: Date a subscription is intended to start (can be future or past).
        - name: subscription_trial_end
          in: query
          type: string
          description: If provided, the invoice returned will preview updating or creating a subscription with that trial
            end. If set, one of `subscription_items` or `subscription` is
        - name: subscription_trial_from_plan
          in: query
          type: boolean
          description: Indicates if a plan's `trial_period_days` should be applied to the subscription. Setting `subscription_trial_end`
            per subscription is preferred, and this defaul
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: v1-invoices-invoice
      path: /v1/invoices/{invoice}
      operations:
      - name: deleteinvoicesinvoice
        method: DELETE
        description: <p>Permanently deletes a one-off invoice draft. This cannot be undone. Attempts to delete invoices that
          are no longer in a draft state will fail; once an invoice has been finalized or if an invoice is for a subscription,
          it must be <a href=
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: invoice
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: getinvoicesinvoice
        method: GET
        description: <p>Retrieves the invoice with the given ID.</p>
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: expand
          in: query
          type: array
          description: Specifies which fields in the response should be expanded.
        - name: invoice
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: postinvoicesinvoice
        method: POST
        description: <p>Draft invoices are fully editable. Once an invoice is <a href="/docs/billing/invoices/workflow#finalized">finalized</a>,
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: invoice
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: v1-invoices-invoice-finalize
      path: /v1/invoices/{invoice}/finalize
      operations:
      - name: postinvoicesinvoicefinalize
        method: POST
        description: <p>Stripe automatically finalizes drafts before sending and attempting payment on invoices. However,
          if you’d like to finalize a draft invoice manually, you can do so using this method.</p>
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: invoice
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: v1-invoices-invoice-lines
      path: /v1/invoices/{invoice}/lines
      operations:
      - name: getinvoicesinvoicelines
        method: GET
        description: <p>When retrieving an invoice, you’ll get a <strong>lines</strong> property containing the total count
          of line items and the first handful of those items. There is also a URL where you can retrieve the full (paginated)
          list of line items.</
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: ending_before
          in: query
          type: string
          description: A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list.
            For instance, if you make a list request and receive 100 ob
        - name: expand
          in: query
          type: array
          description: Specifies which fields in the response should be expanded.
        - name: invoice
          in: path
          type: string
          required: true
        - name: limit
          in: query
          type: integer
          description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default
            is 10.
        - name: starting_after
          in: query
          type: string
          description: A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list.
            For instance, if you make a list request and receive 100 o
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: v1-invoices-invoice-lines-line_item_id
      path: /v1/invoices/{invoice}/lines/{line_item_id}
      operations:
      - name: postinvoicesinvoicelineslineitemid
        method: POST
        description: <p>Updates an invoice’s line item. Some fields, such as <code>tax_amounts</code>, only live on the invoice
          line item,
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: invoice
          in: path
          type: string
          description: Invoice ID of line item
          required: true
        - name: line_item_id
          in: path
          type: string
          description: Invoice line item ID
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: v1-invoices-invoice-mark_uncollectible
      path: /v1/invoices/{invoice}/mark_uncollectible
      operations:
      - name: postinvoicesinvoicemarkuncollectible
        method: POST
        description: <p>Marking an invoice as uncollectible is useful for keeping track of bad debts that can be written off
          for accounting purposes.</p>
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: invoice
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: v1-invoices-invoice-pay
      path: /v1/invoices/{invoice}/pay
      operations:
      - name: postinvoicesinvoicepay
        method: POST
        description: <p>Stripe automatically creates and then attempts to collect payment on invoices for customers on subscriptions
          according to your <a href="https://dashboard.stripe.com/account/billing/automatic">subscriptions settings</a>. However,
          if you’d
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: invoice
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: v1-invoices-invoice-send
      path: /v1/invoices/{invoice}/send
      operations:
      - name: postinvoicesinvoicesend
        method: POST
        description: <p>Stripe will automatically send invoices to customers according to your <a href="https://dashboard.stripe.com/account/billing/automatic">subscriptions
          settings</a>. However, if you’d like to manually send an invoice to your customer out o
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: invoice
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: v1-invoices-invoice-void
      path: /v1/invoices/{invoice}/void
      operations:
      - name: postinvoicesinvoicevoid
        method: POST
        description: <p>Mark a finalized invoice as void. This cannot be undone. Voiding an invoice is similar to <a href="#delete_invoice">deletion</a>,
          however it only applies to finalized invoices and maintains a papertrail where the invoice can still be fou
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: invoice
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    authentication:
      type: bearer
      token: '{{env.STRIPE_API_KEY}}'
  exposes:
  - type: rest
    namespace: invoice-invoices-rest
    port: 8080
    description: REST adapter for Stripe Invoice API — Invoices. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/v1/invoices
      name: v1-invoices
      description: REST surface for v1-invoices.
      operations:
      - method: GET
        name: getinvoices
        description: <p>You can list all invoices, or list the invoices for a specific customer. The invoices are returned
          sorted by creation date, with the most recently created invoices appearing first.</p>
        call: invoice-invoices.getinvoices
        with:
          collection_method: rest.collection_method
          created: rest.created
          customer: rest.customer
          due_date: rest.due_date
          ending_before: rest.ending_before
          expand: rest.expand
          limit: rest.limit
          starting_after: rest.starting_after
          status: rest.status
          subscription: rest.subscription
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: postinvoices
        description: <p>This endpoint creates a draft invoice for a given customer. The invoice remains a draft until you
          <a href="#finalize_invoice">finalize</a> the invoice, which allows you to <a href="#pay_invoice">pay</a> or <a href="#send_invoice">send</a
        call: invoice-invoices.postinvoices
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/invoices/search
      name: v1-invoices-search
      description: REST surface for v1-invoices-search.
      operations:
      - method: GET
        name: getinvoicessearch
        description: <p>Search for invoices you’ve previously created using Stripe’s <a href="/docs/search#search-query-language">Search
          Query Language</a>.
        call: invoice-invoices.getinvoicessearch
        with:
          expand: rest.expand
          limit: rest.limit
          page: rest.page
          query: rest.query
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/invoices/upcoming
      name: v1-invoices-upcoming
      description: REST surface for v1-invoices-upcoming.
      operations:
      - method: GET
        name: getinvoicesupcoming
        description: <p>At any time, you can preview the upcoming invoice for a customer. This will show you all the charges
          that are pending, including subscription renewal charges, invoice item charges, etc. It will also show you any discounts
          that are applic
        call: invoice-invoices.getinvoicesupcoming
        with:
          automatic_tax: rest.automatic_tax
          coupon: rest.coupon
          currency: rest.currency
          customer: rest.customer
          customer_details: rest.customer_details
          discounts: rest.discounts
          expand: rest.expand
          invoice_items: rest.invoice_items
          schedule: rest.schedule
          subscription: rest.subscription
          subscription_billing_cycle_anchor: rest.subscription_billing_cycle_anchor
          subscription_cancel_at: rest.subscription_cancel_at
          subscription_cancel_at_period_end: rest.subscription_cancel_at_period_end
          subscription_cancel_now: rest.subscription_cancel_now
          subscription_default_tax_rates: rest.subscription_default_tax_rates
          subscription_items: rest.subscription_items
          subscription_proration_behavior: rest.subscription_proration_behavior
          subscription_proration_date: rest.subscription_proration_date
          subscription_resume_at: rest.subscription_resume_at
          subscription_start_date: rest.subscription_start_date
          subscription_trial_end: rest.subscription_trial_end
          subscription_trial_from_plan: rest.subscription_trial_from_plan
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/invoices/upcoming/lines
      name: v1-invoices-upcoming-lines
      description: REST surface for v1-invoices-upcoming-lines.
      operations:
      - method: GET
        name: getinvoicesupcominglines
        description: <p>When retrieving an upcoming invoice, you’ll get a <strong>lines</strong> property containing the total
          count of line items and the first handful of those items. There is also a URL where you can retrieve the full (paginated)
          list of line
        call: invoice-invoices.getinvoicesupcominglines
        with:
          automatic_tax: rest.automatic_tax
          coupon: rest.coupon
          currency: rest.currency
          customer: rest.customer
          customer_details: rest.customer_details
          discounts: rest.discounts
          ending_before: rest.ending_before
          expand: rest.expand
          invoice_items: rest.invoice_items
          limit: rest.limit
          schedule: rest.schedule
          starting_after: rest.starting_after
          subscription: rest.subscription
          subscription_billing_cycle_anchor: rest.subscription_billing_cycle_anchor
          subscription_cancel_at: rest.subscription_cancel_at
          subscription_cancel_at_period_end: rest.subscription_cancel_at_period_end
          subscription_cancel_now: rest.subscription_cancel_now
          subscription_default_tax_rates: rest.subscription_default_tax_rates
          subscription_items: rest.subscription_items
          subscription_proration_behavior: rest.subscription_proration_behavior
          subscription_proration_date: rest.subscription_proration_date
          subscription_resume_at: rest.subscription_resume_at
          subscription_start_date: rest.subscription_start_date
          subscription_trial_end: rest.subscription_trial_end
          subscription_trial_from_plan: rest.subscription_trial_from_plan
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/invoices/{invoice}
      name: v1-invoices-invoice
      description: REST surface for v1-invoices-invoice.
      operations:
      - method: DELETE
        name: deleteinvoicesinvoice
        description: <p>Permanently deletes a one-off invoice draft. This cannot be undone. Attempts to delete invoices that
          are no longer in

# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stripe/refs/heads/main/capabilities/invoice-invoices.yaml