Invoice

Invoices describe the amount due to a user for a given subscription period, including any relevant taxes and fees.

  • Name
    object
    Type
    string
    Description

    Type of object is always invoice.

    Allowed values: invoice 
  • Name
    id
    Type
    string
    Description

    Unique identifier for the invoice.

    Example: "inv_0SNlurA049MEWV1QTRqvd18YuG25"
  • Name
    address
    Type
    nullable string
    Description

    The unique identifier for the address this invoice relates to.

    Example: "adr_0SNlurA049MEWV5ELDmnaqVXgTFT"
  • Name
    createdAt
    Type
    string
    Description

    Time when the invoice was created.

    Example: "2024-01-09T15:00:51Z"
  • Name
    discount
    Type
    object
    Description
    The total discount applied. This is the sum of the discounts of each line item.
    Example: {"amount":100,"currency":"USD"}
    • Name
      amount
      Type
      integer
      Description

      The price amount in the currency's minor unit, e.g. "cents" for many currencies.

      Example: 999
      >= 0
    • Name
      currency
      Type
      string
      Description

      Three-letter ISO 4217 currency code. Must be a supported currency.

      Example: "USD"
  • Name
    dueAt
    Type
    nullable string
    Description

    Time when the invoice is due to be paid. From that moment after invoiceOverdueDays, which can be configured on project or subscription level, the invoice will be considered overdue.

    This field will have a value for invoices in the finalized state that have a reason of subscriptionRenewal. For all other invoices, this field will be null.

    Example: "2024-02-01T11:12:13Z"
  • Name
    fees
    Type
    array
    Description
    The fees for the invoice.
    • Name
      amount
      Type
      object
      Description
      The amount of the fee.
      Example: {"amount":100,"currency":"USD"}
      Optional: This property may not always be included.
    • Name
      name
      Type
      string
      Description

      The name of the fee.

      Optional: This property may not always be included.
      Example: "Recovery Fee"
    • Name
      type
      Type
      string
      Description

      The type of the fee.

      Optional: This property may not always be included.
      Allowed values: recoveryFee 
  • Name
    finalizedAt
    Type
    nullable string
    Description

    Time when the invoice was finalized and could no longer be changed.

    Example: "2024-02-01T11:12:13Z"
  • Name
    lineItems
    Type
    array
    Description
    The line items that make up the invoice.
  • Name
    overdueAt
    Type
    nullable string
    Description

    Time when the invoice is considered overdue. Once this happens, invoiceOverdueAction, which can be configured on project or subscription level, is applied.

    This field will have a value for invoices in the finalized state that have a reason of subscriptionRenewal. For all other invoices, this field will be null.

    Example: "2024-02-01T11:13:13Z"
  • Name
    paidAt
    Type
    nullable string
    Description

    Time when the invoice was paid.

    Example: "2024-02-01T11:13:13Z"
  • Name
    payment
    Type
    nullable string
    Description

    The unique identifier for the payment associated with the invoice, if any. Only present if the invoice has been paid using Gigs Payments.

    Example: "pay_0SNlurA049MEWV2HRA0slWFuS8DV"
  • Name
    period
    Type
    nullable object
    Description
    The subscription period that this invoice relates to. It might not be present for new subscriptions if the period has not been defined yet.
    • Name
      number
      Type
      integer
      Description

      Sequence number of the period.

      Example: 1
      >= 1
    • Name
      start
      Type
      string
      Description

      Beginning of the period.

      Example: "2021-01-21T19:32:13Z"
    • Name
      end
      Type
      string
      Description

      End of the period.

      Example: "2021-02-20T19:38:34Z"
  • Name
    reason
    Type
    string
    Description

    The reason this invoice was created. It can have one of the following values:

    • subscriptionCreation: The invoice is due to a new subscription.
    • subscriptionRenewal: The invoice is due to a recurring subscription renewal.
    • subscriptionChange: The invoice is due to a subscription change (e.g. plan upgrade).
    • other: The invoice is not related to a subscription but due an e.g. one-time addon.
    Allowed values: other subscriptionChange subscriptionCreation subscriptionRenewal 
  • Name
    status
    Type
    string
    Description

    The status of the invoice. It can have one of the following values:

    • draft: The invoice is still being edited.
    • finalized: The invoice can no longer be changed and is awaiting payment.
    • paid: The invoice was paid. This causes the associated resources to activated.
    • voided: The invoice was voided and no longer has any effect.
    Example: "draft"
    Allowed values: draft finalized paid voided 
  • Name
    subscription
    Type
    string
    Description

    The unique identifier for the subscription that this invoice relates to.

    Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
  • Name
    subtotal
    Type
    object
    Description
    The total amount before any discounts, taxes or fees are applied.
    Example: {"amount":999,"currency":"USD"}
    • Name
      amount
      Type
      integer
      Description

      The price amount in the currency's minor unit, e.g. "cents" for many currencies.

      Example: 999
      >= 0
    • Name
      currency
      Type
      string
      Description

      Three-letter ISO 4217 currency code. Must be a supported currency.

      Example: "USD"
  • Name
    tax
    Type
    object
    Description
    The total amount of taxes. This is the sum of the taxes of each line item.
    Example: {"amount":200,"currency":"USD"}
    • Name
      amount
      Type
      integer
      Description

      The price amount in the currency's minor unit, e.g. "cents" for many currencies.

      Example: 999
      >= 0
    • Name
      currency
      Type
      string
      Description

      Three-letter ISO 4217 currency code. Must be a supported currency.

      Example: "USD"
  • Name
    taxExemptionReason
    Type
    nullable string
    Description

    The reason for the invoice having no taxes calculated, if any. It can have one of the following values:

    • calculationFailed: The tax calculation failed for an unspecified reason.
    • fullyDiscounted: The invoice is fully discounted due to a voucher or a free product.
    • inclusiveTaxExceedsPrice: The calculated tax is too large to be included in the price.
    • userExempted: The user is marked as exempted from taxes.
    Example: "calculationFailed"
    Allowed values: calculationFailed fullyDiscounted inclusiveTaxExceedsPrice userExempted 
  • Name
    total
    Type
    object
    Description
    The total amount after all discounts, taxes and fees are applied.
    Example: {"amount":1199,"currency":"USD"}
    • Name
      amount
      Type
      integer
      Description

      The price amount in the currency's minor unit, e.g. "cents" for many currencies.

      Example: 999
      >= 0
    • Name
      currency
      Type
      string
      Description

      Three-letter ISO 4217 currency code. Must be a supported currency.

      Example: "USD"
  • Name
    voucher
    Type
    nullable string
    Description

    The unique identifier for the voucher applied to the invoice, if any.

    Example: "vou_0SNlurA049MEWV0h2jfjkdiOdplN"

Example

{
  "object": "invoice",
  "id": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
  "address": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT",
  "createdAt": "2024-01-09T15:01:51.0Z",
  "discount": {
    "amount": 100,
    "currency": "USD"
  },
  "dueAt": "2024-02-01T11:12:13Z",
  "fees": [
    {
      "amount": {
        "amount": 100,
        "currency": "USD"
      },
      "name": "Recovery Fee",
      "type": "recoveryFee"
    }
  ],
  "finalizedAt": "2024-02-01T11:12:13Z",
  "lineItems": [
    {
      "object": "invoiceLineItem",
      "id": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
      "addon": "add_0SNlurA049MEWV4VxLfwJc7PJtHc",
      "creditedPlan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
      "discount": {
        "amount": 100,
        "currency": "USD"
      },
      "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
      "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
      "subscriptionAddon": "sad_0SNlurA049MEWV2UNWPbDfW5B40U",
      "subscriptionChange": "sch_0SNlurA049MEWV3bE0SMtbIEJApp",
      "subtotal": {
        "amount": 999,
        "currency": "USD"
      },
      "tax": {
        "amount": 200,
        "currency": "USD"
      },
      "taxes": [
        {
          "object": "invoiceTax",
          "id": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3",
          "amount": {
            "amount": 200,
            "currency": "USD"
          },
          "inclusive": false,
          "jurisdiction": "Federal",
          "name": "Federal TRS Fund"
        }
      ],
      "total": {
        "amount": 1099,
        "currency": "USD"
      }
    }
  ],
  "overdueAt": "2024-02-01T11:13:13Z",
  "paidAt": "2024-02-01T11:13:13Z",
  "payment": "pay_0SNlurA049MEWV2HRA0slWFuS8DV",
  "period": {
    "number": 1,
    "start": "2021-01-21T19:32:13.0Z",
    "end": "2021-02-20T19:38:34.0Z"
  },
  "reason": "other",
  "status": "draft",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "subtotal": {
    "amount": 999,
    "currency": "USD"
  },
  "tax": {
    "amount": 200,
    "currency": "USD"
  },
  "taxExemptionReason": "calculationFailed",
  "total": {
    "amount": 1199,
    "currency": "USD"
  },
  "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN"
}