# Invoices

## The Invoice object

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

| 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. |

---

## List all invoices

`GET /projects/{project}/invoices`

Returns a list of invoices.

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). |

### Query Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `after` | string | No | A cursor for use in pagination. The `after` parameter takes an object ID that defines the position in the list, only items immediately following the item with that ID will be returned. |
| `before` | string | No | A cursor for use in pagination. The `before` parameter takes an object ID that defines the position in the list, only items immediately preceding the item with that ID will be returned. |
| `limit` | integer | No | The limit of items to be returned in the list, between 0 and 200. |
| `user` | string | No | The unique identifier of the user to filter by. |
| `subscription` | string | No | The unique identifier of the subscription to filter by. |
| `subscriptionAddon` | string | No | The unique identifier of the subscription addon to filter by. |
| `subscriptionChange` | string | No | The unique identifier of the subscription change to filter by. |
| `status` | string[] | No | A comma-separated list of statuses to filter by. |
| `reason` | string[] | No | A comma-separated list of reasons to filter by. |

### Responses

#### 200 — Returns a dictionary with an items property that contains an array of invoices.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `list`. |
| `items` | object[] | Yes | List of objects of type `invoice`. |
| `moreItemsAfter` | string,null | Yes | A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items. |
| `moreItemsBefore` | string,null | Yes | A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items. |

#### 403 — The authenticated user doesn't have permissions to perform the request.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- 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.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

#### 404 — The requested resource doesn't exist.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- 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.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

#### 422 — The request can't be processed, often due to an invalid parameter or incompatible system state.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- 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.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

---

## Retrieve an invoice

`GET /projects/{project}/invoices/{invoice}`

Retrieves the details of an existing invoice.

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). |
| `invoice` | string | Yes | The unique identifier for the invoice. |

### Responses

#### 200 — Returns the invoice.

| 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. |

#### 403 — The authenticated user doesn't have permissions to perform the request.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- 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.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

#### 404 — The requested resource doesn't exist.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- 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.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

---

## Pay an invoice

`POST /projects/{project}/invoices/{invoice}/pay`

Marks the invoice as paid. This activates or allows to renew the products associated with the invoice.

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). |
| `invoice` | string | Yes | The unique identifier for the invoice. |

### Responses

#### 200 — Returns the invoice.

| 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. |

#### 403 — The authenticated user doesn't have permissions to perform the request.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- 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.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

#### 404 — The requested resource doesn't exist.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- 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.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

---