# Credit Notes

## The CreditNote object

Credit notes adjust an invoice amount after it has been finalized. Used to issue credit or refunds.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `creditNote`. |
| `id` | string | Yes | Unique identifier for the credit note. |
| `createdAt` | string | Yes | Time when the credit note was created. |
| `creditTo` | outOfBand | userBalance | Yes | Specifies where the credit amount should be credited to. It can have one of the following values:    - `outOfBand`: The amount should be handled outside the system by the customer.   - `userBalance`: The amount should be added to the user balance at Gigs.  |
| `fees` | object[] | Yes | The credited fees. |
| `fileUrl` | string,null | Yes | A signed URL to download the credit note 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.  |
| `invoice` | string | Yes | The unique identifier for the invoice that the credit note applies to. |
| `lineItems` | object[] | Yes | The line items for the credit note. |
| `status` | issued | voided | Yes | The status of the credit note. It can have one of the following values:    - `issued`: The credit note was issued.   - `voided`: The credit note was voided and no longer has any effect.  |
| `subtotal` | object | Yes | The total amount credited before any taxes or fees. |
| `tax` | object | Yes | The sum of the amounts in taxes credited for each line item. |
| `total` | object | Yes | The total amount credited after taxes and fees. |
| `voidedAt` | string,null | Yes | Time when the credit note was voided. |

---

## List all credit notes

`GET /projects/{project}/creditNotes`

Returns a list of credit notes.

### 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. |
| `invoice` | string | No | The unique identifier for the invoice to be filtered by. |
| `status` | string[] | No | A comma-separated list of statuses to filter the credit notes by. |

### Responses

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `list`. |
| `items` | object[] | Yes | List of objects of type `creditNote`. |
| `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. |

---

## Create a credit note

`POST /projects/{project}/creditNotes`

Creates a new credit note for an invoice.

When only `invoice` is provided, the full amount of the invoice will be credited, including all taxes and fees.
If the invoice has already been partially credited, the remaining amount will be credited.

When selected `lineItems`, `taxes` or `fees` are provided, only those will be credited. 

Non-refundable taxes will still have to be filed with the tax authorities.

### Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `invoice` | string | Yes | The unique identifier for the invoice that the credit note applies to. |
| `lineItems` | array,null | No | The line items for the credit note. |
| `fees` | array,null | No | The fees to be credited. |

### Path Parameters

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

### Responses

#### 201 — Returns the created credit note.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `creditNote`. |
| `id` | string | Yes | Unique identifier for the credit note. |
| `createdAt` | string | Yes | Time when the credit note was created. |
| `creditTo` | outOfBand | userBalance | Yes | Specifies where the credit amount should be credited to. It can have one of the following values:    - `outOfBand`: The amount should be handled outside the system by the customer.   - `userBalance`: The amount should be added to the user balance at Gigs.  |
| `fees` | object[] | Yes | The credited fees. |
| `fileUrl` | string,null | Yes | A signed URL to download the credit note 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.  |
| `invoice` | string | Yes | The unique identifier for the invoice that the credit note applies to. |
| `lineItems` | object[] | Yes | The line items for the credit note. |
| `status` | issued | voided | Yes | The status of the credit note. It can have one of the following values:    - `issued`: The credit note was issued.   - `voided`: The credit note was voided and no longer has any effect.  |
| `subtotal` | object | Yes | The total amount credited before any taxes or fees. |
| `tax` | object | Yes | The sum of the amounts in taxes credited for each line item. |
| `total` | object | Yes | The total amount credited after taxes and fees. |
| `voidedAt` | string,null | Yes | Time when the credit note was voided. |

#### 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 a credit note

`GET /projects/{project}/creditNotes/{creditNote}`

Retrieves the details of an existing credit note.

### Path Parameters

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

### Responses

#### 200 — Returns the credit note.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `creditNote`. |
| `id` | string | Yes | Unique identifier for the credit note. |
| `createdAt` | string | Yes | Time when the credit note was created. |
| `creditTo` | outOfBand | userBalance | Yes | Specifies where the credit amount should be credited to. It can have one of the following values:    - `outOfBand`: The amount should be handled outside the system by the customer.   - `userBalance`: The amount should be added to the user balance at Gigs.  |
| `fees` | object[] | Yes | The credited fees. |
| `fileUrl` | string,null | Yes | A signed URL to download the credit note 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.  |
| `invoice` | string | Yes | The unique identifier for the invoice that the credit note applies to. |
| `lineItems` | object[] | Yes | The line items for the credit note. |
| `status` | issued | voided | Yes | The status of the credit note. It can have one of the following values:    - `issued`: The credit note was issued.   - `voided`: The credit note was voided and no longer has any effect.  |
| `subtotal` | object | Yes | The total amount credited before any taxes or fees. |
| `tax` | object | Yes | The sum of the amounts in taxes credited for each line item. |
| `total` | object | Yes | The total amount credited after taxes and fees. |
| `voidedAt` | string,null | Yes | Time when the credit note was voided. |

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

---

## Void a credit note

`POST /projects/{project}/creditNotes/{creditNote}/void`

Marks the credit note as void. This reverses the credited amount in the invoice and reported taxes.

### Path Parameters

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

### Responses

#### 200 — Returns the voided credit note.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `creditNote`. |
| `id` | string | Yes | Unique identifier for the credit note. |
| `createdAt` | string | Yes | Time when the credit note was created. |
| `creditTo` | outOfBand | userBalance | Yes | Specifies where the credit amount should be credited to. It can have one of the following values:    - `outOfBand`: The amount should be handled outside the system by the customer.   - `userBalance`: The amount should be added to the user balance at Gigs.  |
| `fees` | object[] | Yes | The credited fees. |
| `fileUrl` | string,null | Yes | A signed URL to download the credit note 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.  |
| `invoice` | string | Yes | The unique identifier for the invoice that the credit note applies to. |
| `lineItems` | object[] | Yes | The line items for the credit note. |
| `status` | issued | voided | Yes | The status of the credit note. It can have one of the following values:    - `issued`: The credit note was issued.   - `voided`: The credit note was voided and no longer has any effect.  |
| `subtotal` | object | Yes | The total amount credited before any taxes or fees. |
| `tax` | object | Yes | The sum of the amounts in taxes credited for each line item. |
| `total` | object | Yes | The total amount credited after taxes and fees. |
| `voidedAt` | string,null | Yes | Time when the credit note was voided. |

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

---