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

POST/projects/{project}/quotes

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"

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

POST
/projects/{project}/quotes
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"
}

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

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

GET
/projects/{project}/quotes/{quote}
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"
}