Abonnements hoch- oder herabstufen

Wenn ein Kunde/eine Kundin sein/ihr Abonnement ändert, müssen Sie den Abonnement-Artikel entsprechend der neuen Auswahl ändern. Beispielsweise kann ein Kunde/eine Kundin ein Upgrade auf eine Premium-Stufe oder ein Downgrade auf eine Basic-Stufe vornehmen. Dadurch werden Sie aufgefordert, den zugrunde liegenden Preis dieses Abonnement-Artikels zu ersetzen. Hierfür stehen Ihnen verschiedene Methoden zur Verfügung.

Kennungen abrufen

Unabhängig von der gewählten Methode müssen Sie Kennungen für die zu aktualisierenden Objekte angeben. Verwenden Sie die Methode zum Auflisten von Abonnements mit einem relevanten Filter (z. B. der Kunden-ID), um das zu aktualisierende Abonnement und den Artikel zu finden.

curl -G https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d customer={{CUSTOMER_ID}}

Dadurch werden die Abonnements für den angegebenen Kunden/ die angegebene Kundin zurückgegeben, von denen Sie die Abonnement-ID (id), alle Abonnement-Artikel-IDs (items.data.id) und die Preis-ID für Abonnement-Artikel (items.data.price.id) abrufen können.

{
  "object": "list",
  "url": "/v1/subscriptions",
  "has_more": false,
  "data": [
    {
      "id": "su_1NXPiE2eZvKYlo2COk9fohqA",
      "object": "subscription",
      "application": null,
      "application_fee_percent": null,
      "automatic_tax": {
        "enabled": false
      },
      "items": {
        "object": "list",
        "data": [
          {
            "id": "si_OK3pbS1dvdQYJP",
            "object": "subscription_item",
            "billing_thresholds": null,
            "created": 1690208774,
            "metadata": {},
            "price": {
              "id": "price_1NOhvg2eZvKYlo2CqkpQDVRT",
              "object": "price"
            }
          }
        ]
      }
    }
  ]
}

Abonnement aktualisieren

Abonnement aktualisieren mit folgenden Parametern:

• item ID: Sie müssen den Abonnement-Artikel angeben, um den aktuellen Preis durch den neuen Preis zu ersetzen. Andernfalls wird durch die Aktualisierung des Abonnements mit einem neuen Preis ein neuer Abonnement-Artikel hinzugefügt, sodass beide Preise für das Abonnement aktiv sind.
• item price: Geben Sie die Kennung für den Ersatzpreis an.
• item quantity: Durch das Aktualisieren eines Abonnementpreises wird die Menge automatisch auf den Standardwert von 1 zurückgesetzt. Wenn die vorhandene Abonnementmenge nicht 1 ist und Sie diesen Wert beibehalten möchten, müssen Sie ihn in die Aktualisierung aufnehmen.

curl https://api.stripe.com/v1/subscriptions/sub_xxxxxxxxx \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "items[0][id]"={{SUB_ITEM_ID}} \
  -d "items[0][price]"={{NEW_PRICE_ID}}

Alternativ können Sie den aktuellen Abonnement-Artikel löschen und einen neuen Abonnement-Artikel mit dem aktualisierten Preis erstellen.

curl https://api.stripe.com/v1/subscriptions/sub_xxxxxxxxx \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "items[0][id]"={{SUB_ITEM_ID}} \
  -d "items[0][deleted]"=true \
  -d "items[1][price]"={{NEW_PRICE_ID}}

Abonnement-Artikel aktualisieren

Abonnement aktualisieren mit dem folgenden Parameter:

• item price: Geben Sie die Kennung für den Ersatzpreis an.
• item quantity: Durch das Aktualisieren eines Abonnementpreises wird die Menge automatisch auf den Standardwert von 1 zurückgesetzt. Wenn die vorhandene Abonnementmenge nicht 1 ist und Sie diesen Wert beibehalten möchten, müssen Sie ihn in die Aktualisierung aufnehmen.

Verwenden Sie diese Option, wenn Sie auf Abonnement-Ebene keine weiteren Änderungen vornehmen müssen.

curl https://api.stripe.com/v1/subscription_items/si_xxxxxxxxx \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d price={{NEW_PRICE_ID}}

Abrechnungszeiträume

Wenn für beide Preise derselbe Abrechnungszeitraum (die Kombination aus interval und interval_count) gilt, wird für das Abonnement derselbe Abrechnungszeitraum beibehalten. Wenn unterschiedliche Abrechnungszeiträume für die Preise gelten, wird der neue Preis ab dem Tag der Umstellung gemäß dem neuen Intervall abgerechnet. Beispiel: Bei einer Umstellung von einem monatlichen Abonnement auf ein anderes wird das Abrechnungsdatum nicht geändert. Bei einer Umstellung von einem monatlichen auf ein jährliches Abonnement ändert sich das Abrechnungsdatum in das Datum der Umstellung. Wenn bei einer Umstellung von einem monatlichen Abonnement auf ein anderes monatliches Abonnement ein Testzeitraum eingeführt wird, wird das Abrechnungsdatum ebenfalls (auf das Ende des Testzeitraums) verschoben.

Abonnementpläne

Wenn Sie ein Abonnement am Ende des Abrechnungszyklus ändern, sollten Sie einen Abonnementplan verwenden, um den Wechsel reibungslos zu gestalten. Achten Sie bei der Verwendung von Abonnementplänen darauf, dass Sie die Best Practices zum Verhindern unerwarteter Überschreibungen von Abonnements befolgen.

Metered billing with Billing Meters

Details on mid-cycle updates for prices attached to a Billing Meter are described in the pricing models section. Passing clear_usage when updating a price with a Billing Meter has no effect.

Metered billing with Usage Records Legacy

If you have a metered price backed by legacy usage records and update to a new usage records price, the usage is transferred to the new price.

curl https://api.stripe.com/v1/subscriptions/sub_xxxxxxxxx \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "items[0][id]"={{SUB_ITEM_ID}} \
  -d "items[0][price]"={{NEW_PRICE_ID}} \
  -d "items[0][clear_usage]"=true

Anteilmäßige Verrechnung

Wird ein Abonnement geändert, führt dies häufig zu einer anteiligen Verrechnung, um den neuen Preis auf die verbleibenden Tage des Abrechnungszeitraums anzuwenden. Sie können Ihre Kundinnen und Kunden auf zusätzliche Ausgaben vorbereiten, die sich aus einer Preisänderung ergeben, indem Sie eine Vorschau einer anteilmäßigen Verrechnung anzeigen. Alternativ können Sie die anteilmäßige Verrechnung deaktivieren.

Sofortige Zahlung

Bei folgenden Abonnementänderungen führt Stripe sofort einen Zahlungsversuch durch:

• Umstellung von einem Abonnement, das keine Zahlung erfordert (z. B. aufgrund eines Testzeitraums oder bei einem kostenlosen Abonnement), auf ein kostenpflichtiges Abonnement
• Änderung des Abrechnungszeitraums

Wenn die Abrechnung sofort erfolgt, die erforderliche Zahlung jedoch fehlschlägt, ist die Anfrage zur Abonnementänderung erfolgreich und das Abonnement wird zu past_due.

Um einem Kunden/einer Kundin eine Änderung an einem Abonnement im selben Abrechnungszyklus sofort in Rechnung zu stellen, legen Sie proration_behavior auf always_invoice fest. Dadurch wird die anteilige Verrechnung berechnet und nach dem Wechsel sofort eine Rechnung erstellt. Kombinieren Sie diese Einstellung mit ausstehenden Aktualisierungen, damit das Abonnement nicht aktualisiert wird, es sei denn, die Zahlung für die neue Rechnung ist erfolgreich.

Gutschriften für Downgrades

Bei der sofortigen Rechnungsstellung für ein Downgrade hat der Kunde/die Kundin möglicherweise Anspruch auf eine Gutschrift, die seinem/ihrem Guthaben hinzugefügt wird, um auf zukünftige Rechnungen angewendet zu werden. Um Ihrem Kunden/Ihrer Kundin eine Rückerstattung zu gewähren, stellen Sie Rückerstattungen aus und passen Sie dann seinen/ihren Kontostand wieder auf null an. Erfahren Sie mehr über Kundenrückerstattungen auf unserer speziellen Support-Seite.

Abwicklung von Nullbetragspreisen und -mengen

Wenn Sie für einen Kunden/eine Kundin ein Abonnement mit einem Betrag von Null abgeschlossen haben (z. B. im Rahmen einer Testversion), wird durch die Änderung des Preises auf einen Betrag ungleich Null eine Rechnung erstellt und der Abrechnungszeitraum auf das Datum der Änderung zurückgesetzt.

Wenn Sie für einen Kunden/eine Kundin einen Preis mit einem Betrag ungleich Null und einer Menge mit einem Betrag von Null abonniert haben, wird durch die Änderung der Menge in einen Betrag ungleich Null keine Rechnung erstellt oder der Abrechnungszeitraum zurückgesetzt.