Quotes
Quotes provide a preview of the invoices, including taxes and fees, that will occur when creating a subscription or add-on.
Properties
- Name
- object
- Type
- string
- Description
Type of object is always
quote
.Allowed values:quote
- Name
- id
- Type
- string
- Description
Unique identifier for the quote.
Example:"quo_0SNlurA049MEWV2X9NicYieFQ4Kc"
- Name
- address
- Type
- nullable string
- Description
The unique identifier for the address that the taxes were quoted for. Present when quoting local plans.
Example:"adr_0SNlurA049MEWV5ELDmnaqVXgTFT"
- Name
- createdAt
- Type
- string
- Description
Time when the quote 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
- expiredAt
- Type
- string
- Description
The timestamp indicating when the quote expires. Set to 2 hours after the quote's creation time.
Example:"2024-02-01T11:12:13Z"
- Name
- fees
- Type
- array
- Description
- The fees for the quote.
- 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
- lineItems
- Type
- array
- Description
- The line items that make up the quote.
- Name
- reason
- Type
- string
- Description
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.
Allowed values:other
subscriptionChange
subscriptionCreation
- 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 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.
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
- user
- Type
- string
- Description
The unique identifier for the user that this quote belongs to.
Example:"usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
- Name
- voucher
- Type
- nullable string
- Description
The unique identifier for the voucher applied to the quote, if any.
Example:"vou_0SNlurA049MEWV0h2jfjkdiOdplN"
Example
{
"object": "quote",
"id": "quo_0SNlurA049MEWV2X9NicYieFQ4Kc",
"address": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT",
"createdAt": "2024-01-09T15:01:51.0Z",
"discount": {
"amount": 100,
"currency": "USD"
},
"expiredAt": "2024-02-01T11:12:13.0Z",
"fees": [
{
"amount": {
"amount": 100,
"currency": "USD"
},
"name": "Recovery Fee",
"type": "recoveryFee"
}
],
"lineItems": [
{
"addon": "add_0SNlurA049MEWV4VxLfwJc7PJtHc",
"creditedPlan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
"discount": {
"amount": 100,
"currency": "USD"
},
"plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
"subtotal": {
"amount": 999,
"currency": "USD"
},
"tax": {
"amount": 200,
"currency": "USD"
},
"taxes": [
{
"amount": {
"amount": 200,
"currency": "USD"
},
"inclusive": false,
"jurisdiction": "Federal",
"name": "Federal TRS Fund"
}
],
"total": {
"amount": 1099,
"currency": "USD"
}
}
],
"reason": "other",
"subtotal": {
"amount": 999,
"currency": "USD"
},
"tax": {
"amount": 200,
"currency": "USD"
},
"taxExemptionReason": "calculationFailed",
"total": {
"amount": 1199,
"currency": "USD"
},
"user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
"voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN"
}
Create a quote
Creates a quote for the given plan or add-on, allowing you to preview its final price with all applicable taxes and fees.
Body
- Name
- addon
- Type
- nullable string
- Description
The unique identifier for the addon for which this quote is being created. Either plan or addon should be present, but not both.
Example:"add_0SNlurA049MEWV4VxLfwJc7PJtHc"
- Name
- address
- Type
- nullable string
- Description
The unique identifier representing the address for tax calculation purposes. Required when quoting local plans or addons for local plans.
Example:"adr_0SNlurA049MEWV5ELDmnaqVXgTFT"
- Name
- creditedPlan
- Type
- nullable string
- Description
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.
Example:"pln_0SNlurA049MEWV3V0q7gjQbM4EVo"
- Name
- plan
- Type
- nullable string
- Description
The unique identifier for the plan for which this quote is being created. Either plan or addon should be present, but not both.
Example:"pln_0SNlurA049MEWV3V0q7gjQbM4EVo"
- Name
- user
- Type
- string
- Description
The unique identifier for the user for which this quote is being created.
Example:"usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
required- Name
- voucher
- Type
- nullable string
- Description
The unique identifier for the voucher to apply to this quote.
Example:"vou_0SNlurA049MEWV0h2jfjkdiOdplN"
Path Parameters
- Name
- project
- Type
- string
- Description
The unique identifier for the project.
Example:"gigs"
required
Responses
Returns the created quote.
- Name
- object
- Type
- string
- Description
Type of object is always
quote
.Allowed values:quote
- Name
- id
- Type
- string
- Description
Unique identifier for the quote.
Example:"quo_0SNlurA049MEWV2X9NicYieFQ4Kc"
- Name
- address
- Type
- nullable string
- Description
The unique identifier for the address that the taxes were quoted for. Present when quoting local plans.
Example:"adr_0SNlurA049MEWV5ELDmnaqVXgTFT"
- Name
- createdAt
- Type
- string
- Description
Time when the quote 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
- expiredAt
- Type
- string
- Description
The timestamp indicating when the quote expires. Set to 2 hours after the quote's creation time.
Example:"2024-02-01T11:12:13Z"
- Name
- fees
- Type
- array
- Description
- The fees for the quote.
- 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
- lineItems
- Type
- array
- Description
- The line items that make up the quote.
- Name
- reason
- Type
- string
- Description
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.
Allowed values:other
subscriptionChange
subscriptionCreation
- 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 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.
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
- user
- Type
- string
- Description
The unique identifier for the user that this quote belongs to.
Example:"usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
- Name
- voucher
- Type
- nullable string
- Description
The unique identifier for the voucher applied to the quote, if any.
Example:"vou_0SNlurA049MEWV0h2jfjkdiOdplN"
Request
curl https://api.gigs.com/projects/{project}/quotes \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{\"addon\":\"add_0SNlurA049MEWV4VxLfwJc7PJtHc\",\"address\":\"adr_0SNlurA049MEWV5ELDmnaqVXgTFT\",\"creditedPlan\":\"pln_0SNlurA049MEWV3V0q7gjQbM4EVo\",\"plan\":\"pln_0SNlurA049MEWV3V0q7gjQbM4EVo\",\"user\":\"usr_0SNlurA049MEWV4OpCwsNyC9Kn2d\",\"voucher\":\"vou_0SNlurA049MEWV0h2jfjkdiOdplN\"}"
Response
{
"object": "quote",
"id": "quo_0SNlurA049MEWV2X9NicYieFQ4Kc",
"address": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT",
"createdAt": "2024-01-09T15:00:51Z",
"discount": {
"amount": 100,
"currency": "USD"
},
"expiredAt": "2024-02-01T11:12:13Z",
"fees": [
{
"amount": {
"amount": 100,
"currency": "USD"
},
"name": "Recovery Fee",
"type": "recoveryFee"
}
],
"lineItems": [
{
"addon": "add_0SNlurA049MEWV4VxLfwJc7PJtHc",
"creditedPlan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
"discount": {
"amount": 100,
"currency": "USD"
},
"plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
"subtotal": {
"amount": 999,
"currency": "USD"
},
"tax": {
"amount": 200,
"currency": "USD"
},
"taxes": [
{
"amount": {
"amount": 200,
"currency": "USD"
},
"inclusive": false,
"jurisdiction": "Federal",
"name": "Federal TRS Fund"
}
],
"total": {
"amount": 1099,
"currency": "USD"
}
}
],
"reason": "other",
"subtotal": {
"amount": 999,
"currency": "USD"
},
"tax": {
"amount": 200,
"currency": "USD"
},
"taxExemptionReason": "calculationFailed",
"total": {
"amount": 1199,
"currency": "USD"
},
"user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
"voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN"
}
Retrieve a quote
Retrieves the details of an existing quote.
Path Parameters
- Name
- project
- Type
- string
- Description
The unique identifier for the project.
Example:"gigs"
required- Name
- quote
- Type
- string
- Description
The unique identifier for the quote.
Example:"quo_0SNlurA049MEWV2X9NicYieFQ4Kc"
required
Responses
Returns the quote.
- Name
- object
- Type
- string
- Description
Type of object is always
quote
.Allowed values:quote
- Name
- id
- Type
- string
- Description
Unique identifier for the quote.
Example:"quo_0SNlurA049MEWV2X9NicYieFQ4Kc"
- Name
- address
- Type
- nullable string
- Description
The unique identifier for the address that the taxes were quoted for. Present when quoting local plans.
Example:"adr_0SNlurA049MEWV5ELDmnaqVXgTFT"
- Name
- createdAt
- Type
- string
- Description
Time when the quote 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
- expiredAt
- Type
- string
- Description
The timestamp indicating when the quote expires. Set to 2 hours after the quote's creation time.
Example:"2024-02-01T11:12:13Z"
- Name
- fees
- Type
- array
- Description
- The fees for the quote.
- 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
- lineItems
- Type
- array
- Description
- The line items that make up the quote.
- Name
- reason
- Type
- string
- Description
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.
Allowed values:other
subscriptionChange
subscriptionCreation
- 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 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.
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
- user
- Type
- string
- Description
The unique identifier for the user that this quote belongs to.
Example:"usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
- Name
- voucher
- Type
- nullable string
- Description
The unique identifier for the voucher applied to the quote, if any.
Example:"vou_0SNlurA049MEWV0h2jfjkdiOdplN"
Request
curl https://api.gigs.com/projects/{project}/quotes/{quote} \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"
Response
{
"object": "quote",
"id": "quo_0SNlurA049MEWV2X9NicYieFQ4Kc",
"address": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT",
"createdAt": "2024-01-09T15:00:51Z",
"discount": {
"amount": 100,
"currency": "USD"
},
"expiredAt": "2024-02-01T11:12:13Z",
"fees": [
{
"amount": {
"amount": 100,
"currency": "USD"
},
"name": "Recovery Fee",
"type": "recoveryFee"
}
],
"lineItems": [
{
"addon": "add_0SNlurA049MEWV4VxLfwJc7PJtHc",
"creditedPlan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
"discount": {
"amount": 100,
"currency": "USD"
},
"plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
"subtotal": {
"amount": 999,
"currency": "USD"
},
"tax": {
"amount": 200,
"currency": "USD"
},
"taxes": [
{
"amount": {
"amount": 200,
"currency": "USD"
},
"inclusive": false,
"jurisdiction": "Federal",
"name": "Federal TRS Fund"
}
],
"total": {
"amount": 1099,
"currency": "USD"
}
}
],
"reason": "other",
"subtotal": {
"amount": 999,
"currency": "USD"
},
"tax": {
"amount": 200,
"currency": "USD"
},
"taxExemptionReason": "calculationFailed",
"total": {
"amount": 1199,
"currency": "USD"
},
"user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
"voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN"
}