Skip to content
STOQDevelopers
Open STOQ

Offers

View as Markdown

Update a payment on an offer

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

  • idstringRequired

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
    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
      Example: string
      Show 2 child attributesHide child attributes
      • adjustment_typestring, nullable

        Percentage or fixed amount discount. Null clears the discount.

        One of percentagepricefixed_amountnull
      • adjustment_amountnumber, nullable

        Discount amount; an omitted type uses the saved type.

  • partialobject
    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
      Example: string
      Show 2 child attributesHide child attributes
      • adjustment_typestring, nullable

        Percentage or fixed amount discount. Null clears the discount.

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

Errors

401

Missing or invalid X-Auth-Token.

404

The resource does not exist for this shop, or the action path is not registered.

409

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

422

Invalid fields: one details entry per field error, its path the canonical section path. Nothing was saved.

429

Rate limited: cost-weighted per token (read 1, write 2; 360 points / 60s). Check Retry-After.

Every error has the same shape: see Errors.

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",
    "default_option": "full",
    "full": {
      "option_title": "string",
      "option_description": "string",
      "discount_text": "Preorder now",
      "price_adjustment": "string"
    },
    "partial": {
      "option_title": "string",
      "option_description": "string",
      "discount_text": "Preorder now",
      "price_adjustment": "string",
      "checkout_charge": {
        "charge_type": "percentage",
        "charge_amount": 0
      },
      "remaining_balance": {
        "charge_trigger": "exact_time",
        "charge_exact_time": "string",
        "days_after_checkout": "string"
      }
    },
    "collection_schedule": "manual",
    "show_payment_widget": true,
    "show_discounted_price": 5,
    "locale": "fr"
  }'
Response
No body