Invoice

An invoice represents the amount due for a billing period and the payment attempts used to collect it. Subscription invoice webhook events include this object in data.object.

  • id
    Type: string
    max length:  
    100
    required

    Unique identifier for the invoice.

  • created
    Type: stringFormat: date-time
    required

    Time at which the invoice was created.

  • updated
    Type: stringFormat: date-time
    required

    Time at which the invoice was last updated.

  • customer
    required

    Customer associated with the invoice. Pass expand[]=customer to include the full Customer object.

    • Type: string · Customer ID
      max length:  
      100

      Customer associated with the invoice. Pass expand[]=customer to include the full Customer object.

  • status
    Type: stringenum
    required

    Current invoice status. Use the invoice event type and payment attempts to distinguish a failed collection attempt from the invoice lifecycle state.

    values
    • draft

      Invoice is being prepared and is not ready for collection.

    • open

      Invoice is finalized and payment is still due.

    • paid

      Invoice has been fully paid.

    • void

      Invoice was voided and will not be collected.

    • uncollectible

      Invoice was marked uncollectible after collection was abandoned.

  • billing_reason
    Type: string | nullenum

    Reason the invoice was created. Use this to choose the right recovery or fulfillment flow for subscription invoices.

    values
    • subscription_create

      First invoice created when a subscription starts and payment is due immediately.

    • subscription_cycle

      Recurring invoice created for a subscription billing period.

    • subscription_update

      Invoice created because a subscription changed in a way that produced an amount due.

    • manual

      Invoice created directly rather than by subscription automation.

  • collection_method
    Type: stringenum
    required

    How Paypercut collects payment for the invoice.

    values
    • charge_automatically

      Paypercut attempts to collect the invoice using a saved payment method.

    • send_invoice

      Payment is expected through an invoice collection flow rather than an immediate automatic charge.

  • currency
    Type: string
    required

    ISO 4217 currency codes (alpha3) supported for payments

  • amount_due
    Type: integer · amountWithCurrencyPrecisionFormat: int64
    required

    Total amount due on the invoice, in the smallest currency unit.

  • amount_paid
    Type: integer · amountWithCurrencyPrecisionFormat: int64
    required

    Amount successfully collected for the invoice, in the smallest currency unit.

  • amount_remaining
    Type: integer · amountWithCurrencyPrecisionFormat: int64
    required

    Amount still outstanding on the invoice, in the smallest currency unit.

  • period
    Type: object
    required

    Billing period covered by an invoice or invoice line.

    • end
      Type: stringFormat: date-time
      required

      End of the billing period covered by the invoice.

    • start
      Type: stringFormat: date-time
      required

      Start of the billing period covered by the invoice.

  • parent
    Type: object
    required

    Resource that caused the invoice to be created.

    • type
      Type: stringenum
      required

      Resource type that caused the invoice to be created.

      values
      • subscription_details

        Invoice was created from a subscription.

      • quote_details

        Invoice was created from a quote.

      • manual_details

        Invoice was created directly.

    • subscription_details
      Type: object · InvoiceSubscriptionParentDetails nullable

      Subscription context for an invoice created by subscription billing.

  • lines
    Type: object
    required

    Invoice line items included with the invoice. Additional lines can be fetched from url when has_more is true.

    • data
      Type: array object[] · InvoiceLine[]
      required

      Line items on the current page.

      Individual line item that contributes to the invoice total.

    • has_more
      Type: boolean
      required

      Whether more line items are available after the items returned in data.

    • object
      enum
      const:  
      list
      required

      String representing the collection type.

      values
      • list
    • url
      Type: string
      required

      API URL that can be used to list the full invoice line collection.

  • payments
    Type: object
    required

    Payment attempts associated with the invoice.

    • data
      Type: array object[] · InvoicePayment[]
      required

      Payment attempts on the current page.

      A single attempt to collect payment for an invoice.

    • has_more
      Type: boolean
      required

      Whether more payment attempts are available after the items returned in data.

    • object
      enum
      const:  
      list
      required

      String representing the collection type.

      values
      • list
    • url
      Type: string
      required

      API URL that can be used to list the full invoice payment collection.

  • status_transitions
    Type: object
    required

    Timestamps for important invoice lifecycle transitions.

    • finalized_at
      Type: stringFormat: date-time
      required

      Time at which the invoice was finalized.

    • marked_uncollectible_at
      Type: string | nullFormat: date-time

      Time at which the invoice was marked uncollectible.

    • paid_at
      Type: string | nullFormat: date-time

      Time at which the invoice was paid.

    • voided_at
      Type: string | nullFormat: date-time

      Time at which the invoice was voided.

  • last_finalization_error
    Type: object · InvoiceLastFinalizationError nullable

    Error details from the last failed invoice finalization attempt.

    • advice_code
      Type: string | null

      Processor advice code that can help decide whether retrying is useful.

    • code
      Type: string | null

      Paypercut error code for the finalization failure.

    • doc_url
      Type: string | null

      Documentation URL for the error, when one is available.

    • message
      Type: string | null

      Human-readable explanation of the finalization failure.

    • network_advice_code
      Type: string | null

      Network-provided advice code returned with the failure, when available.

    • network_decline_code
      Type: string | null

      Network-provided decline code returned with the failure, when available.

    • param
      Type: string | null

      Request parameter associated with the error, when the failure maps to a specific field.

    • payment_method_type
      Type: string | null

      Payment method type involved in the failure.

    • type
      Type: string | null

      Error category.

  • livemode
    Type: boolean
    required

    Has the value true if the invoice exists in live mode or false if it exists in test mode.

  • metadata

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

    • propertyName
      Type: string
  • object
    enum
    const:  
    invoice
    required

    String representing the object's type.

    values
    • invoice