{
  "slug": "stripe-payment-link-update-endpoint-adds-shipping-consent-and-future-usage-param-53f27274d051",
  "title": "Stripe Payment Link update endpoint adds shipping, consent, and future-usage parameters",
  "tools": [
    "stripe"
  ],
  "tags": [
    "agent"
  ],
  "introduced_at": "2026-07-29T00:00:00.000Z",
  "announced_at": "2026-07-29T00:00:00.000Z",
  "effective_at": null,
  "date_basis": "source-publication",
  "status": "unknown",
  "how": {
    "incantation": "When updating an existing Payment Link, send the needed `shipping_options`, `consent_collection`, or `payment_intent_data.setup_future_usage` fields. Use the documented values for future usage; the update API requires the Payment Link ID and secret-key authentication.",
    "examples": [
      "curl https://api.stripe.com/v1/payment_links/<PAYMENT_LINK_ID> \\\n  -u \"<YOUR_SECRET_KEY>\" \\\n  -H \"Stripe-Version: 2026-07-29.dahlia\" \\\n  -d \"shipping_options[0][shipping_rate]=<SHIPPING_RATE_ID>\"",
      "curl https://api.stripe.com/v1/payment_links/<PAYMENT_LINK_ID> \\\n  -u \"<YOUR_SECRET_KEY>\" \\\n  -H \"Stripe-Version: 2026-07-29.dahlia\" \\\n  -d \"payment_intent_data[setup_future_usage]=off_session\"",
      "curl https://api.stripe.com/v1/payment_links/<PAYMENT_LINK_ID> \\\n  -u \"<YOUR_SECRET_KEY>\" \\\n  -H \"Stripe-Version: 2026-07-29.dahlia\" \\\n  -d \"consent_collection[promotions]=auto\""
    ],
    "gotchas": [
      "<PAYMENT_LINK_ID> (required): ID of the Payment Link to update.",
      "<YOUR_SECRET_KEY> (required): Stripe secret API key used for HTTP basic authentication.",
      "shipping_options: Shipping rate options applied to checkout sessions created by the Payment Link; release note specifies up to five objects and empty array removes all options.",
      "shipping_options[].shipping_rate (required): Existing Shipping Rate ID for the shipping option, per the release note.",
      "consent_collection: Optional object to configure active customer consent collection.",
      "consent_collection.payment_method_reuse_agreement.position: Controls where the payment method reuse agreement is displayed; allowed values not found.",
      "consent_collection.promotions: Controls whether to display a promotional communications consent checkbox; allowed values not found.",
      "consent_collection.terms_of_service: Controls whether to display a terms of service acceptance checkbox; allowed values not found.",
      "payment_intent_data.setup_future_usage: Indicates whether payment methods collected during checkout are intended for reuse; release note allows `on_session` or `off_session`.",
      "Prerequisite: Authenticate the request with a Stripe secret key and provide the Payment Link ID.",
      "Prerequisite: A Payment Link must already exist. Stripe's page prerequisite example creates a Price and then a Payment Link.",
      "Prerequisite: Each shipping rate must already exist, per the release note.",
      "Each shipping_options array can contain up to five shipping rate objects, each referencing an existing Shipping Rate ID.",
      "payment_intent_data.setup_future_usage accepts `on_session` or `off_session`.",
      "The consent settings described are payment method reuse agreement position, promotions consent checkbox, and terms of service checkbox."
    ]
  },
  "why_it_matters": "Update an existing Payment Link's shipping options, consent settings, or payment method reuse behavior through the API.",
  "before": "These parameters were previously configurable only through the Dashboard; requests including `payment_intent_data.setup_future_usage` returned HTTP 400.",
  "sources": [
    "https://docs.stripe.com/changelog/dahlia/2026-07-29/payment-links-update-endpoint-new-parameters",
    "https://docs.stripe.com/api/payment-link/update?api-version=2026-07-29.dahlia"
  ],
  "rank": 0.97031,
  "judge": {
    "publish": true,
    "judge_model": "codex-cli/gpt-6-luna+typesafe/jev-1.13.0",
    "prompt_version": "extract-v7+enrich-v2+judge-v2x3+jev-publish-v1"
  },
  "review_state": "approved",
  "provenance": {
    "run_id": "wave1b-tools-20261017",
    "verdict_id": "wave1b-tools-20261017:wave1b-tools-20261017-db3dae4502fe88c5-0:gate",
    "evidence_hash": "c2c9ae29db521fa2b06168c391366cb046a0c9fa4963b43a33cf153cb61be04c"
  },
  "review": {
    "draft_hash": "d97cee10c5640d9ff8c1aa3686697780ce27988ed38bb50328cc0b3d765741b9",
    "reviewer": "publication-gate",
    "reviewed_at": "2026-10-07T00:00:00.000Z",
    "decision": "wave1b-tools-20261017:gate",
    "reason": "3 of 3 judge runs approved with p_yes >= 0.9 (mean 0.97 >= 0.9; 2 needed) and Jev gave 0.78 (>= 0.6 needed)."
  }
}