# Invoice

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

## Properties

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `invoice`. |
| `id` | string | Yes | Unique identifier for the invoice. |
| `address` | string,null | Yes | The unique identifier for the address this invoice relates to. |
| `appliedBalance` | mixed | Yes | The amount of user balance applied to pay this invoice. |
| `createdAt` | string | Yes | Time when the invoice was created. |
| `discount` | object | Yes | The total discount applied. This is the sum of the discounts of each line item. |
| `dueAt` | string,null | Yes | Time when the invoice is due to be paid. After this time and the `invoiceGracePeriodDays`, which can be configured on project or subscription level, the invoice becomes 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`.  |
| `fees` | object[] | Yes | The fees for the invoice. |
| `fileUrl` | string,null | Yes | A signed URL to download the invoice PDF file. The URL is valid for 1 minute.  This field is only available for select projects and will be `null` for all others.   <!-- theme: info --> > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.  |
| `finalizedAt` | string,null | Yes | Time when the invoice was finalized and could no longer be changed. |
| `lineItems` | object[] | Yes | The line items that make up the invoice. |
| `overdueAt` | string,null | Yes | 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`.  |
| `paidAt` | string,null | Yes | Time when the invoice was paid. |
| `payment` | string,null | Yes | The unique identifier for the payment associated with the invoice, if any. Only present if the invoice has been paid using Gigs Payments. |
| `period` | mixed | Yes | The subscription period that this invoice relates to. It might not be present for new subscriptions if the period has not been defined yet. |
| `reason` | other | subscriptionChange | subscriptionCreation | subscriptionRenewal | subscriptionRestore | Yes | 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).   - `subscriptionRestore`: The invoice is due to a subscription restore.   - `other`: The invoice is not related to a subscription but due an e.g. one-time addon.  |
| `status` | draft | finalized | paid | voided | Yes | 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.  |
| `subscription` | string | Yes | The unique identifier for the subscription that this invoice relates to. |
| `subtotal` | object | Yes | The total amount before any discounts, taxes or fees are applied. |
| `tax` | object | Yes | The total amount of taxes. This is the sum of the taxes of each line item. |
| `taxExemptionReason` | null | calculationFailed | fullyDiscounted | inclusiveTaxExceedsPrice | userExempted | Yes | 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.  |
| `total` | object | Yes | The total amount after all discounts, taxes and fees are applied. |
| `voucher` | string,null | Yes | The unique identifier for the voucher applied to the invoice, if any. |