Update payment settings
API v2 is in public beta: endpoints and fields can change before general availability. See the changelog
/preorders/offers/{id}/paymentsCosts 2 rate-limit points · Rate limits
Update a deep partial of the canonical payment settings. Full and partial are stable kind selectors.
Omitted fields stay unchanged. Null clears copy or price_adjustment. Explicit options_offered adds/removes kinds. Choose full or partial for ambiguous billing copy. Read-only and unknown fields are rejected. Invalid patches write nothing locally; publication runs after commit.
Also searched asedit paymentschange payment settingsmodify billingupdate remaining balance settingschange discountset discountapply discountset percentage offset amount offclear discountremove discountno discountstop discountremove preorder discountenable auto collectenable auto chargeauto-charge balanceautomatically charge balanceturn on auto collectdisable auto collectdisable auto chargestop auto chargeturn off auto collectmanual balance collectiondisable auto collect on fulfillmentdon't charge on fulfillmentturn off charge at ship timestop collecting on shipenable auto collect on fulfillmentcharge on fulfillmentauto charge at ship timecollect balance on shipshow partial payment option firstpreselect deposit optiondefault to full paymentdisable payment optionenable payment optionadd full payment optionadd partial payment optionset payment modechange payment optionsremove full payment optionstop offering full paymentpartial payment onlydeposit onlyremove partial payment optionstop offering depositfull payment onlyoffer both payment optionslet customers choose how to payoffer both full and partial paymentset balance due dayscharge balance after n dayscollect balance days after checkoutbalance due in dayscharge remaining balance laterset days after checkoutcollect balance a week after checkoutshow payment widgetshow payment and savingsenable billing widgetshow savings breakdownshow payment schedule to customersshow payment breakdownturn on billing widgethide payment widgethide payment and savingsdisable billing widgethide savings breakdownhide payment breakdownturn off billing widgetset deposit amountset a fixed depositcharge a fixed amount upfrontset upfront payment amountchange down payment amountchange deposit amountchange down paymentset deposit percentset deposit percentageset upfront payment percentset discount textchange discount blurbset discount messagechange discount copyset savings textset option copychange billing titleset payment option textset partial option copyset deposit option textset full option copyset payment datebalance due datecharge on a specific datefinal payment datecollect balance on dateshow discounted pricedisplay sale priceshow discount pricehide discounted priceset billing widget titleset billing widget descriptionchange payment breakdown textedit billing widget copy
Path parameters
idstringRequiredThe offer's ID, from
GET /preorders/offers.
Headers
Idempotency-KeystringA fresh unique key for every write (a new UUID, say); reuse it only to retry that write. Keys are remembered for 1 hour: the same key and the same request within that hour returns the first result, with
Idempotent-Replayed: true, without running again; the same key with a different method, path or body is refused (422idempotency_key_reused); a retry while the first is still running gets 409idempotency_key_in_progress. Keys are per store. Server errors and rate limits are not kept, so their retry runs.
Request body
options_offeredstringExplicitly add or remove full/partial payment kinds. Omitted kinds remain offered. Mode changes initialize payment widget and cart attributes.
One offullpartialfull_and_partialdefault_optionstringSelect an offered, synced full or partial kind as the default.
One offullpartialfullobjectSettings for the full-payment option, where shoppers pay everything at checkout.
Show 4 child attributesHide child attributes
option_titlestring, nullableBilling Title for full payment.
option_descriptionstring, nullableBilling Description for full payment.
discount_textstring, nullableDiscount copy for full payment.
price_adjustmentobject, nullableShow 2 child attributesHide child attributes
adjustment_typestring, nullablePercentage or fixed amount discount. Null clears the discount.
One ofpercentagefixed_amountnulladjustment_amountnumber, nullableDiscount amount; an omitted type uses the saved type.
partialobjectSettings for the partial-payment option, where shoppers pay a deposit at checkout and the balance later.
Show 6 child attributesHide child attributes
option_titlestring, nullableBilling Title for partial payment.
option_descriptionstring, nullableBilling Description for partial payment.
discount_textstring, nullableDiscount copy for partial payment.
price_adjustmentobject, nullableShow 2 child attributesHide child attributes
adjustment_typestring, nullablePercentage or fixed amount discount. Null clears the discount.
One ofpercentagefixed_amountnulladjustment_amountnumber, nullableDiscount amount; an omitted type uses the saved type.
checkout_chargeobjectShow 2 child attributesHide child attributes
charge_typestringDeposit as percentage or price.
One ofpercentagepricecharge_amountnumberCheckout deposit; percentage must not exceed 100. 0 is the editor's "No upfront payment": nothing is charged at checkout.
remaining_balanceobjectShow 3 child attributesHide child attributes
charge_triggerstringCollect at an exact time or days after checkout.
One ofexact_timetime_after_checkoutcharge_exact_timestring, nullableISO 8601 datetime, required for exact_time; otherwise null.
days_after_checkoutinteger, nullablePositive days, required for time_after_checkout; otherwise null.
collection_schedulestringCollect the remaining balance manually, on its scheduled date, or on fulfillment. A balance due date alone charges nothing: "charge the rest after N days" also needs scheduled, and while it stays manual say the merchant collects it.
One ofmanualscheduledon_fulfillmentshow_payment_widgetbooleanShow payment & discount savings. Also turns the payment cart attribute (advanced.cart_attributes.show_payment) on or off, as the editor does.
show_discounted_pricebooleanShow discounted price.
localestringLanguage the translated fields are written in, such as 'fr' or 'pt-BR'. Omitted: the shop's default language. Untranslated fields ignore it.
Returns
options_offeredstringPayment options the offer has.
One offullpartialfull_and_partialdefault_optionstringPayment option selected by default at checkout.
One offullpartialpartialobjectThe partial-payment option, where shoppers pay a deposit at checkout and the balance later. Absent when the offer has no partial-payment option.
Show 7 child attributesHide child attributes
selling_plan_idstring, nullableThis option's Shopify selling plan, as gid://shopify/SellingPlan/<id>. Null until it exists in Shopify.
checkout_chargeobjectThe deposit charged at checkout.
Show 2 child attributesHide child attributes
charge_typestringpercentage charges charge_amount percent of the price; price charges charge_amount in the shop's currency.
One ofpercentagepricecharge_amountnumberThe deposit: a percent from 0 to 100 when charge_type is percentage, or an amount in the shop's currency (not minor units) when it is price. 0 charges nothing at checkout.
remaining_balanceobjectWhen the remaining balance is charged.
Show 3 child attributesHide child attributes
charge_triggerstringexact_time charges the balance on charge_exact_time; time_after_checkout charges it days_after_checkout days after checkout.
One ofexact_timeno_remaining_balancetime_after_checkoutcharge_exact_timestring, nullableWhen the balance is due, ISO 8601 in UTC. Null unless charge_trigger is exact_time.
days_after_checkoutinteger, nullableDays after checkout that the balance is due. Null unless charge_trigger is time_after_checkout.
price_adjustmentobjectDiscount on this option's price.
Show 2 child attributesHide child attributes
adjustment_typestring, nullablepercentage takes adjustment_amount percent off; fixed_amount and price take adjustment_amount off in the shop's currency. Null when there is no discount.
One ofpercentagepricefixed_amountadjustment_amountinteger, nullableDiscount size: a percent, or an amount in the shop's currency (not minor units), per adjustment_type. Null when there is no discount.
option_titlestringTitle of the partial-payment option in the payment widget.
option_descriptionstringDescription of the partial-payment option in the payment widget. Null when not set.
discount_textstringText describing the partial-payment discount.
collection_schedulestringHow the remaining balance is collected: manual by the merchant, scheduled on its due date, or on_fulfillment.
One ofmanualscheduledon_fulfillmentshow_payment_widgetbooleanWhether the payment and discount savings widget shows on the product page.
show_discounted_priceboolean, nullableWhether the discounted price shows. Null when never set.
currency_codenullThe shop's currency, as an ISO 4217 code such as USD. Amounts in this section are in it.
fullobjectThe full-payment option, where shoppers pay everything at checkout. Absent when the offer has no full-payment option.
Show 7 child attributesHide child attributes
selling_plan_idstring, nullableThis option's Shopify selling plan, as gid://shopify/SellingPlan/<id>. Null until it exists in Shopify.
checkout_chargeobjectWhat is charged at checkout. Always 100 percent for full payment.
Show 2 child attributesHide child attributes
charge_typestringAlways percentage for full payment.
One ofpercentagepricecharge_amountintegerAlways 100 for full payment.
remaining_balanceobjectWhen the remaining balance is charged. Nothing remains on full payment.
Show 3 child attributesHide child attributes
charge_triggerstringAlways no_remaining_balance for full payment.
One ofexact_timeno_remaining_balancetime_after_checkoutcharge_exact_timenullAlways null for full payment.
days_after_checkoutnullAlways null for full payment.
price_adjustmentobjectDiscount on this option's price.
Show 2 child attributesHide child attributes
adjustment_typestring, nullablepercentage takes adjustment_amount percent off; fixed_amount and price take adjustment_amount off in the shop's currency. Null when there is no discount.
One ofpercentagepricefixed_amountadjustment_amountinteger, nullableDiscount size: a percent, or an amount in the shop's currency (not minor units), per adjustment_type. Null when there is no discount.
option_titlestringTitle of the full-payment option in the payment widget.
option_descriptionstring, nullableDescription of the full-payment option in the payment widget. Null when not set.
discount_textstringText describing the full-payment discount.
also_changedarray of objectsSettings this write changed on its own because they depend on what you changed (turning one option off can reset another). Absent when nothing else changed.
Show 5 child attributesHide child attributes
field_pathstringDotted path of the changed field in this response, when it is one.
settingstringThe setting that changed, as the dashboard names it.
fromboolean, nullableIts value before the write.
tostringIts value after the write.
reasonstringWhy it changed.
Errors
not_foundThe path is valid but nothing with that id exists in this store.
idempotency_key_in_progressAn earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key.
invalid_paramsOne or more fields failed the action's schema.
Any request can also fail with auth_invalid (401) or rate_limited (429).
Every error has the same shape: see Errors and the list of error codes.
curl -X PATCH "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/payments" \
-H "X-Auth-Token: $STOQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"options_offered": "full_and_partial",
"partial": {
"checkout_charge": {
"charge_type": "percentage",
"charge_amount": 25
},
"remaining_balance": {
"charge_trigger": "exact_time",
"charge_exact_time": "2026-09-15T12:00:00-04:00"
}
},
"collection_schedule": "scheduled"
}'const res = await fetch("https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/payments", {
method: "PATCH",
headers: {
"X-Auth-Token": process.env.STOQ_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"options_offered": "full_and_partial",
"partial": {
"checkout_charge": {
"charge_type": "percentage",
"charge_amount": 25
},
"remaining_balance": {
"charge_trigger": "exact_time",
"charge_exact_time": "2026-09-15T12:00:00-04:00"
}
},
"collection_schedule": "scheduled"
}),
});
const data = await res.json();import os
import requests
res = requests.patch(
"https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/payments",
headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
json={
"options_offered": "full_and_partial",
"partial": {
"checkout_charge": {
"charge_type": "percentage",
"charge_amount": 25
},
"remaining_balance": {
"charge_trigger": "exact_time",
"charge_exact_time": "2026-09-15T12:00:00-04:00"
}
},
"collection_schedule": "scheduled"
},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/payments")
req = Net::HTTP::Patch.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"], "Content-Type" => "application/json")
req.body = {
options_offered: "full_and_partial",
partial: {
checkout_charge: {
charge_type: "percentage",
charge_amount: 25
},
remaining_balance: {
charge_trigger: "exact_time",
charge_exact_time: "2026-09-15T12:00:00-04:00"
}
},
collection_schedule: "scheduled"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body){
"options_offered": "full_and_partial",
"default_option": "full",
"full": {
"selling_plan_id": "gid://shopify/SellingPlan/101",
"checkout_charge": {
"charge_type": "percentage",
"charge_amount": 100
},
"remaining_balance": {
"charge_trigger": "no_remaining_balance",
"charge_exact_time": null,
"days_after_checkout": null
},
"price_adjustment": {
"adjustment_type": null,
"adjustment_amount": null
},
"option_title": "Full payment",
"option_description": "Pay the full price now",
"discount_text": "Save {{ discount }}"
},
"partial": {
"selling_plan_id": "gid://shopify/SellingPlan/102",
"checkout_charge": {
"charge_type": "percentage",
"charge_amount": 25
},
"remaining_balance": {
"charge_trigger": "exact_time",
"charge_exact_time": "2026-09-15T16:00:00Z",
"days_after_checkout": null
},
"price_adjustment": {
"adjustment_type": null,
"adjustment_amount": null
},
"option_title": "Reserve now, pay later",
"option_description": "Pay {{ payment }} now and the remaining will be charged when your product is shipped.",
"discount_text": "Save {{ discount }}"
},
"collection_schedule": "scheduled",
"show_payment_widget": true,
"show_discounted_price": null,
"currency_code": "USD",
"also_changed": [
{
"field_path": "payments.show_payment_widget",
"setting": "show_payment_widget",
"from": false,
"to": true,
"reason": "Initialized by the payment mode change."
},
{
"field_path": "advanced.cart_attributes.show_payment",
"setting": "Payment cart attribute",
"from": false,
"to": true,
"reason": "Enabled for partial payment."
}
]
}{
"errors": [
"Invalid API key"
],
"code": "auth_invalid",
"details": [
{
"code": "auth_invalid",
"message": "Invalid API key",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"Offer not found"
],
"code": "not_found",
"details": [
{
"code": "not_found",
"message": "Offer not found",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"A request with this Idempotency-Key is still running"
],
"code": "idempotency_key_in_progress",
"details": [
{
"code": "idempotency_key_in_progress",
"message": "A request with this Idempotency-Key is still running",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"widget.button.text_color must be a hex color"
],
"code": "invalid_params",
"details": [
{
"code": "invalid_params",
"message": "must be a hex color",
"path": "widget.button.text_color",
"value": "blue",
"expected": {
"type": "string"
}
}
]
}{
"errors": [
"Rate limit exceeded"
],
"code": "rate_limited",
"details": [
{
"code": "rate_limited",
"message": "Rate limit exceeded",
"path": null,
"value": null,
"expected": null
}
]
}