Skip to content

Update payment settings

API v2 is in public beta: endpoints and fields can change before general availability. See the changelog

PATCH/preorders/offers/{id}/payments

Costs 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

Headers

  • Idempotency-Keystring

    A 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 (422 idempotency_key_reused); a retry while the first is still running gets 409 idempotency_key_in_progress. Keys are per store. Server errors and rate limits are not kept, so their retry runs.

Request body

  • options_offeredstring

    Explicitly add or remove full/partial payment kinds. Omitted kinds remain offered. Mode changes initialize payment widget and cart attributes.

    One of fullpartialfull_and_partial
  • default_optionstring

    Select an offered, synced full or partial kind as the default.

    One of fullpartial
  • fullobject

    Settings for the full-payment option, where shoppers pay everything at checkout.

    Show 4 child attributesHide child attributes
    • option_titlestring, nullable

      Billing Title for full payment.

    • option_descriptionstring, nullable

      Billing Description for full payment.

    • discount_textstring, nullable

      Discount copy for full payment.

    • price_adjustmentobject, nullable
      Show 2 child attributesHide child attributes
      • adjustment_typestring, nullable

        Percentage or fixed amount discount. Null clears the discount.

        One of percentagefixed_amountnull
      • adjustment_amountnumber, nullable

        Discount amount; an omitted type uses the saved type.

  • partialobject

    Settings for the partial-payment option, where shoppers pay a deposit at checkout and the balance later.

    Show 6 child attributesHide child attributes
    • option_titlestring, nullable

      Billing Title for partial payment.

    • option_descriptionstring, nullable

      Billing Description for partial payment.

    • discount_textstring, nullable

      Discount copy for partial payment.

    • price_adjustmentobject, nullable
      Show 2 child attributesHide child attributes
      • adjustment_typestring, nullable

        Percentage or fixed amount discount. Null clears the discount.

        One of percentagefixed_amountnull
      • adjustment_amountnumber, nullable

        Discount amount; an omitted type uses the saved type.

    • checkout_chargeobject
      Show 2 child attributesHide child attributes
      • charge_typestring

        Deposit as percentage or price.

        One of percentageprice
      • charge_amountnumber

        Checkout deposit; percentage must not exceed 100. 0 is the editor's "No upfront payment": nothing is charged at checkout.

    • remaining_balanceobject
      Show 3 child attributesHide child attributes
      • charge_triggerstring

        Collect at an exact time or days after checkout.

        One of exact_timetime_after_checkout
      • charge_exact_timestring, nullable

        ISO 8601 datetime, required for exact_time; otherwise null.

      • days_after_checkoutinteger, nullable

        Positive days, required for time_after_checkout; otherwise null.

  • collection_schedulestring

    Collect 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 of manualscheduledon_fulfillment
  • show_payment_widgetboolean

    Show payment & discount savings. Also turns the payment cart attribute (advanced.cart_attributes.show_payment) on or off, as the editor does.

  • show_discounted_priceboolean

    Show discounted price.

  • localestring

    Language the translated fields are written in, such as 'fr' or 'pt-BR'. Omitted: the shop's default language. Untranslated fields ignore it.

Returns

  • options_offeredstring

    Payment options the offer has.

    One of fullpartialfull_and_partial
  • default_optionstring

    Payment option selected by default at checkout.

    One of fullpartial
  • partialobject

    The 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, nullable

      This option's Shopify selling plan, as gid://shopify/SellingPlan/<id>. Null until it exists in Shopify.

    • checkout_chargeobject

      The deposit charged at checkout.

      Show 2 child attributesHide child attributes
      • charge_typestring

        percentage charges charge_amount percent of the price; price charges charge_amount in the shop's currency.

        One of percentageprice
      • charge_amountnumber

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

      When the remaining balance is charged.

      Show 3 child attributesHide child attributes
      • charge_triggerstring

        exact_time charges the balance on charge_exact_time; time_after_checkout charges it days_after_checkout days after checkout.

        One of exact_timeno_remaining_balancetime_after_checkout
      • charge_exact_timestring, nullable

        When the balance is due, ISO 8601 in UTC. Null unless charge_trigger is exact_time.

      • days_after_checkoutinteger, nullable

        Days after checkout that the balance is due. Null unless charge_trigger is time_after_checkout.

    • price_adjustmentobject

      Discount on this option's price.

      Show 2 child attributesHide child attributes
      • adjustment_typestring, nullable

        percentage 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 of percentagepricefixed_amount
      • adjustment_amountinteger, nullable

        Discount size: a percent, or an amount in the shop's currency (not minor units), per adjustment_type. Null when there is no discount.

    • option_titlestring

      Title of the partial-payment option in the payment widget.

    • option_descriptionstring

      Description of the partial-payment option in the payment widget. Null when not set.

    • discount_textstring

      Text describing the partial-payment discount.

  • collection_schedulestring

    How the remaining balance is collected: manual by the merchant, scheduled on its due date, or on_fulfillment.

    One of manualscheduledon_fulfillment
  • show_payment_widgetboolean

    Whether the payment and discount savings widget shows on the product page.

  • show_discounted_priceboolean, nullable

    Whether the discounted price shows. Null when never set.

  • currency_codenull

    The shop's currency, as an ISO 4217 code such as USD. Amounts in this section are in it.

  • fullobject

    The 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, nullable

      This option's Shopify selling plan, as gid://shopify/SellingPlan/<id>. Null until it exists in Shopify.

    • checkout_chargeobject

      What is charged at checkout. Always 100 percent for full payment.

      Show 2 child attributesHide child attributes
      • charge_typestring

        Always percentage for full payment.

        One of percentageprice
      • charge_amountinteger

        Always 100 for full payment.

    • remaining_balanceobject

      When the remaining balance is charged. Nothing remains on full payment.

      Show 3 child attributesHide child attributes
      • charge_triggerstring

        Always no_remaining_balance for full payment.

        One of exact_timeno_remaining_balancetime_after_checkout
      • charge_exact_timenull

        Always null for full payment.

      • days_after_checkoutnull

        Always null for full payment.

    • price_adjustmentobject

      Discount on this option's price.

      Show 2 child attributesHide child attributes
      • adjustment_typestring, nullable

        percentage 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 of percentagepricefixed_amount
      • adjustment_amountinteger, nullable

        Discount size: a percent, or an amount in the shop's currency (not minor units), per adjustment_type. Null when there is no discount.

    • option_titlestring

      Title of the full-payment option in the payment widget.

    • option_descriptionstring, nullable

      Description of the full-payment option in the payment widget. Null when not set.

    • discount_textstring

      Text describing the full-payment discount.

  • also_changedarray of objects

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

      Dotted path of the changed field in this response, when it is one.

    • settingstring

      The setting that changed, as the dashboard names it.

    • fromboolean, nullable

      Its value before the write.

    • tostring

      Its value after the write.

    • reasonstring

      Why it changed.

Errors

404
not_found

The path is valid but nothing with that id exists in this store.

409
idempotency_key_in_progress

An earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key.

422
invalid_params

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

PATCH/preorders/offers/{id}/payments
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"
  }'
Response
{
  "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."
    }
  ]
}