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
Price
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
Price
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
Price
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
Price
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
Price
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"
}

POST/projects/{project}/quotes

Retrieve a quote

Retrieves the details of an existing quote.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
quote
Type
string
required
Description
The unique identifier for the quote.
Example: "quo_0SNlurA049MEWV2X9NicYieFQ4Kc"

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

GET

/projects/{project}/quotes/{quote}

curl https://api.gigs.com/projects/${GIGS_PROJECT}/quotes/{quote} \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_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"
}

{ "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
required
Description
The unique identifier for the user for which this quote is being created.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
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
required
Description
The unique identifier for the project.
Example: "gigs"

curl https://api.gigs.com/projects/${GIGS_PROJECT}/quotes \ -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${GIGS_TOKEN}" \ -H "Accept: application/json" \ -d '{ "addon": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "address": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "creditedPlan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN" }'

{ "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" }