Create Payment Quote
Prices a purchase the way a payment for it will be charged. The body is the PaymentInput a payment takes plus where the buyer is, which a seller that collects no tax on the purchase can leave out. The purchase is priced from exactly what you send: no buyer is looked up, so no stored registration or purchase history applies. Pass the quote’s id as quote_id when you create the payment to charge exactly the purchase, promo code, and tax shown here. A quote is priced once and may be consumed by one payment before expires_at. Cart entries must name existing variants with plan_id.
Authorizations
An Account API key, an App API key, an account access token, an account-scoped user token, or a user OAuth token. Prepend the key or token with Bearer, for example Bearer ***************************. See Auth & API keys for how to get each one.
Headers
A unique key that makes this request safe to retry. See Idempotent requests.
255"d9105228-4a08-46b1-8b91-42fed586d383"
Pins the request to a dated API version.
"2026-10-15-1"
Body
The account, variant and promo code for a purchase.
The account the purchase belongs to, prefixed biz_.
"biz_xxxxxxxxxxxxxx"
The variant purchased, described by its attributes instead of an id: the variant with exactly these attributes is used, and one is created when none exists. Mutually exclusive with plan_id and line_items. Creating a variant requires plan:create; creating or updating a product requires the corresponding product permission.
The variant purchased, prefixed plan_. It must belong to the account. Mutually exclusive with plan and line_items.
"plan_xxxxxxxxxxxxxx"
The promo code as the buyer typed it, matched within the account regardless of case and surrounding spaces, as checkout matches it. It must be valid for the variant. Send it or promo_code_id, not both; an empty or whitespace-only string counts as not sent. A code the account does not have, or one that is no longer active, is refused before anything is written, with the error code promo_invalid. A code this purchase cannot use, such as one with no uses left or one restricted to other variants, products or buyers, is refused with promo_invalid too, and the error's message says why.
"SHINE20"
An active promo code to apply, prefixed promo_. It must belong to the account and be valid for the variant. Send it or promo_code, not both. A code this purchase cannot use is refused with the error code promo_invalid, and the error's message says why.
"promo_xxxxxxxxxxxxxx"
The buyer's billing address. Where tax is calculated when no shipping address is given, and the address a tax registration belongs to. A seller that collects tax on this purchase needs the buyer located by a country here, on shipping_address, a presentment_country, or an ip_address; without one the quote is refused with quote_location_required. Only the keys you supply are kept. The payment that consumes the quote must put the buyer in the same place, by country, state and postal code, through its own shipping_address or its confirmation token's billing address, or it is refused with quote_mismatch.
The buyer's IP address, when your server makes the call on their behalf. Locates the buyer when neither address carries a country and no presentment_country is sent. A quote located this way (located_by is ip_address) is a preview: a payment refuses it with quote_preview_only, so quote again with the buyer's address before paying. Also where presentment_currency auto and recommended_currencies find the buyer's local currency, and where a payment method must be able to collect it.
"203.0.113.7"
What the buyer is purchasing. Each entry names an existing variant by plan_id. Several entries form a cart, which requires every variant to be compatible, belong to this account, and use the same currency.
1 - 50 elementsThe country to price the purchase for, as an ISO 3166-1 alpha-2 code such as JP, when the buyer chose one: a store's country picker. Prices in the currency auto would pick for a buyer in that country, so send it instead of presentment_currency, never with it. Whether a payment method can collect that currency is still judged where the buyer is: by ip_address, and by this country only without one. With no address that carries a country, tax is estimated for this country (located_by is presentment_country) at the country level, and a quote located this way is a preview a payment refuses with quote_preview_only. Send it only once the buyer has chosen a country: without it, an ip_address estimates more precisely, such as for a US state. For a country Whop has no currency for, the quote is priced as auto for the buyer's ip_address, and tax is still estimated for the country.
"JP"
The currency to price and charge the purchase in. Omit it, or send null, to price in the variants' own currency. auto prices in the currency of the country Whop places the buyer's ip_address in when the purchase can be converted into it and a payment method can collect it, and in the variants' own currency otherwise, including when no ip_address is sent or Whop cannot place it in a country. To choose that country instead, send presentment_country in place of this. A three-letter ISO 4217 code, such as eur, prices in that currency or is refused: with presentment_currency_unsupported when the purchase cannot be converted into it (adaptive pricing is off for the variant, the variant is not a one-time purchase, or plan describes a variant that does not exist yet), and with presentment_currency_not_payable when no payment method can collect it. A converted quote states every amount in this currency at an exchange_rate fixed until expires_at, and the payment that consumes it is charged in this currency at that rate.
"auto"
Where physical goods ship. When present it is where tax is calculated; omit it for digital goods. Only the keys you supply are kept. The payment that consumes the quote must ship to the same place, by country, state and postal code, or it is refused with quote_mismatch.
The buyer's tax registration, for a business purchase. One entry. Prices the purchase as business-to-business where that applies (EU reverse charge, for one) and requires an address to belong to.
1Response
payment quote priced
The account the purchase is priced for, prefixed biz_.
"biz_xxxxxxxxxxxxxx"
The billing address the purchase was priced with, or null. Where tax was calculated when no shipping address was given, and the address the registration belongs to.
Three-letter ISO 4217 code of the variants' own currency, lowercase. Equal to currency when nothing was converted.
"usd"
total in base_currency at exchange_rate: the variants' own prices after the promo code, plus tax_amount converted at exchange_rate when tax is added on top. Equal to total when nothing was converted. The payment charges total, in currency.
When the quote was priced, as an ISO 8601 timestamp.
"2026-01-01T12:00:00.000Z"
Three-letter ISO 4217 currency code the purchase is priced and charged in, lowercase: the variants' own currency, or the presentment_currency it was converted into.
"usd"
What the promo code takes off. Zero without a code.
How many units of currency one unit of base_currency buys, as a decimal string such as "5.4321": the rate the variants' prices were converted at, fixed until expires_at, and the rate a payment consuming the quote is charged at. A string, like money amounts, so no float rounds it in transit. Null when nothing was converted.
"0.918"
When the quote stops being chargeable, as an ISO 8601 timestamp. Quote again after it.
"2026-01-01T12:00:00.000Z"
Payment quote ID, prefixed pq_.
"pq_xxxxxxxxxxxxxx"
Which location tax was calculated for: shipping_address when it carries a country, else the billing address when it does, else the presentment_country sent, else the buyer's ip_address. A quote located by presentment_country or ip_address is a preview that estimates tax: a payment cannot use it, so quote again with the buyer's address to pay. Null when nothing in the request located the buyer, which only a seller that collects no tax on this purchase is quoted without; tax_status is then not_applicable.
shipping_address, address, presentment_country, ip_address, null "address"
The payment holding this quote, prefixed pay_, or null while it is unspent. A declined payment keeps its quote and can be retried; check that payment's status.
"pay_xxxxxxxxxxxxxx"
The promo code the quote applied, prefixed promo_, or null.
null
Lowercase ISO 4217 codes to offer the buyer in a currency picker, most relevant first: the currency of the presentment_country sent, else of the country the buyer's ip_address is in, when this purchase can be converted into it and a payment method can collect it, then base_currency. Quote again with one as presentment_currency to price in it. Only base_currency when the quote was priced without presentment_currency or presentment_country.
The shipping address the purchase was priced with, or null. When present it is where tax was calculated.
The price of every line before the promo code, tax and fees.
The tax a payment consuming this quote charges. Zero unless tax_status is calculated.
Whether tax is added on top of the price (exclusive) or already inside it (inclusive). Null when no tax was calculated.
inclusive, exclusive, null "exclusive"
calculated: every line was priced and a payment may consume the quote. not_applicable: this seller collects no tax on this purchase, so the quote owes none and may still be consumed. unavailable: tax could not be priced — the provider did not answer, or this seller's tax setup cannot price a purchase here — so a payment refuses the quote; quote again, or charge without quote_id to have tax calculated at charge time.
calculated, not_applicable, unavailable "calculated"
What the buyer pays: the subtotal less the discount, plus tax_amount when tax is added on top.