# Quotes

## The Quote object

Quotes provide a preview of the invoices, including taxes and fees, that will occur when creating a subscription or add-on.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `quote`. |
| `id` | string | Yes | Unique identifier for the quote. |
| `address` | string,null | Yes | The unique identifier for the address that the taxes were quoted for. Present when quoting local plans. |
| `createdAt` | string | Yes | Time when the quote was created. |
| `discount` | object | Yes | The total discount applied. This is the sum of the discounts of each line item. |
| `expiredAt` | string | Yes | The timestamp indicating when the quote expires. Set to 2 hours after the quote's creation time. |
| `fees` | object[] | Yes | The fees for the quote. |
| `lineItems` | object[] | Yes | The line items that make up the quote. |
| `reason` | other | subscriptionChange | subscriptionCreation | Yes | The reason this quote was created. It can have one of the following values:    - `subscriptionCreation`: The quote is for a new subscription.   - `subscriptionChange`: The quote is for a subscription change (e.g. plan upgrade).   - `other`: The quote is not related to a subscription but due an e.g. one-time addon.  |
| `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 taxes not being calculated, if any. It can have one of the following values:    - `calculationFailed`: The tax calculation failed for an unspecified reason.   - `inclusiveTaxExceedsPrice`: The calculated tax is too large to be included in the price.   - `fullyDiscounted`: The quote is fully discounted due to a voucher or a free product.   - `userExempted`: The user is marked as exempted from taxes.  |
| `total` | object | Yes | The total amount after all discounts, taxes and fees are applied. |
| `user` | string | Yes | The unique identifier for the user that this quote belongs to. |
| `voucher` | string,null | Yes | The unique identifier for the voucher applied to the quote, if any. |

---

## Create a quote

`POST /projects/{project}/quotes`

Creates a quote for the given plan or add-on, allowing you to preview its final price with all applicable taxes and fees.

### Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `addon` | string,null | No | The unique identifier for the addon for which this quote is being created. Either plan or addon should be present, but not both. |
| `address` | string,null | No | The unique identifier representing the address for tax calculation purposes. Required when quoting local plans or addons for local plans. |
| `creditedPlan` | string,null | No | The unique identifier for the credited plan this quote is being created with. The price of the credited plan is used to adjust the final plan price when quoting immediate subscription changes. |
| `plan` | string,null | No | The unique identifier for the plan for which this quote is being created. Either plan or addon should be present, but not both. |
| `user` | string | Yes | The unique identifier for the user for which this quote is being created. |
| `voucher` | string,null | No | The unique identifier for the voucher to apply to this quote. |

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

#### 200 — Returns the created quote.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `quote`. |
| `id` | string | Yes | Unique identifier for the quote. |
| `address` | string,null | Yes | The unique identifier for the address that the taxes were quoted for. Present when quoting local plans. |
| `createdAt` | string | Yes | Time when the quote was created. |
| `discount` | object | Yes | The total discount applied. This is the sum of the discounts of each line item. |
| `expiredAt` | string | Yes | The timestamp indicating when the quote expires. Set to 2 hours after the quote's creation time. |
| `fees` | object[] | Yes | The fees for the quote. |
| `lineItems` | object[] | Yes | The line items that make up the quote. |
| `reason` | other | subscriptionChange | subscriptionCreation | Yes | The reason this quote was created. It can have one of the following values:    - `subscriptionCreation`: The quote is for a new subscription.   - `subscriptionChange`: The quote is for a subscription change (e.g. plan upgrade).   - `other`: The quote is not related to a subscription but due an e.g. one-time addon.  |
| `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 taxes not being calculated, if any. It can have one of the following values:    - `calculationFailed`: The tax calculation failed for an unspecified reason.   - `inclusiveTaxExceedsPrice`: The calculated tax is too large to be included in the price.   - `fullyDiscounted`: The quote is fully discounted due to a voucher or a free product.   - `userExempted`: The user is marked as exempted from taxes.  |
| `total` | object | Yes | The total amount after all discounts, taxes and fees are applied. |
| `user` | string | Yes | The unique identifier for the user that this quote belongs to. |
| `voucher` | string,null | Yes | The unique identifier for the voucher applied to the quote, 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. |

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

`GET /projects/{project}/quotes/{quote}`

Retrieves the details of an existing quote.

### Path Parameters

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

### Responses

#### 200 — Returns the quote.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `quote`. |
| `id` | string | Yes | Unique identifier for the quote. |
| `address` | string,null | Yes | The unique identifier for the address that the taxes were quoted for. Present when quoting local plans. |
| `createdAt` | string | Yes | Time when the quote was created. |
| `discount` | object | Yes | The total discount applied. This is the sum of the discounts of each line item. |
| `expiredAt` | string | Yes | The timestamp indicating when the quote expires. Set to 2 hours after the quote's creation time. |
| `fees` | object[] | Yes | The fees for the quote. |
| `lineItems` | object[] | Yes | The line items that make up the quote. |
| `reason` | other | subscriptionChange | subscriptionCreation | Yes | The reason this quote was created. It can have one of the following values:    - `subscriptionCreation`: The quote is for a new subscription.   - `subscriptionChange`: The quote is for a subscription change (e.g. plan upgrade).   - `other`: The quote is not related to a subscription but due an e.g. one-time addon.  |
| `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 taxes not being calculated, if any. It can have one of the following values:    - `calculationFailed`: The tax calculation failed for an unspecified reason.   - `inclusiveTaxExceedsPrice`: The calculated tax is too large to be included in the price.   - `fullyDiscounted`: The quote is fully discounted due to a voucher or a free product.   - `userExempted`: The user is marked as exempted from taxes.  |
| `total` | object | Yes | The total amount after all discounts, taxes and fees are applied. |
| `user` | string | Yes | The unique identifier for the user that this quote belongs to. |
| `voucher` | string,null | Yes | The unique identifier for the voucher applied to the quote, 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. |

---