> For the complete documentation index, see [llms.txt](https://docs.peakcommerce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.peakcommerce.com/integrations/billing-and-payments/stripe-payments/stripe-subscription-sync.md).

# Stripe subscription sync

When Stripe is your billing provider, Stripe decides what happens to a subscription after checkout: renewals, failed payments, cancellations at the end of a paid period. Subscription sync keeps PeakCommerce in step with those decisions, so the subscription your team and your own systems see in PeakCommerce matches what Stripe is actually doing.

## What stays in sync

For every subscription created through a PeakCommerce journey, Stripe's events update the PeakCommerce subscription:

| When Stripe…                                                                      | PeakCommerce…                                                                                                                                                                                     |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| creates or changes the subscription                                               | refreshes its **status**, **current period**, **billing interval** and whether it **cancels at period end**, then sends the `subscription.changed` webhook — only when something actually changed |
| ends the subscription (for example, at the end of the paid period after a cancel) | marks it **cancelled** and sends `subscription.cancelled`, once                                                                                                                                   |
| records an invoice as paid                                                        | sends `payment.succeeded`                                                                                                                                                                         |
| records a failed invoice payment                                                  | sends `payment.failed`                                                                                                                                                                            |

Access therefore ends when the paid period does, not at the moment someone clicks cancel. Subscriptions that were not created through PeakCommerce are left alone.

## Connect Stripe's events to PeakCommerce

Sync runs on Stripe's webhooks, so Stripe needs to know where to send them and PeakCommerce needs to be able to verify them.

1. **Find your Stripe integration's id.** In PeakCommerce, open **Settings → Integrations → Stripe** and choose **Edit** on your Stripe integration. The id is the part of the browser address after `/instances/`.
2. **Add the endpoint in Stripe.** In your Stripe Dashboard, go to **Developers → Webhooks** and add an endpoint with this URL:

   `https://[your PeakCommerce domain]/api/stripe/webhook/[integration id]`

   Select these events:

   * `customer.subscription.created`
   * `customer.subscription.updated`
   * `customer.subscription.deleted`
   * `invoice.paid`
   * `invoice.payment_failed`
3. **Copy the signing secret.** Stripe shows a signing secret (it starts with `whsec_`) for the new endpoint.
4. **Paste it into PeakCommerce.** Back on the Stripe integration's **Edit** page, paste it into **Webhook Secret** and save.

Each Stripe integration has its own endpoint and its own secret. If you run more than one Stripe integration, repeat these steps for each.

> **The signing secret is required for sync.** The field is marked optional, but PeakCommerce refuses every Stripe event it cannot verify. Without a secret, nothing syncs.

## What PeakCommerce does with each event

* **Every event is verified** against that integration's signing secret before anything changes. An event that fails verification is refused and changes nothing.
* **A repeated event is safe.** Stripe sometimes sends the same event more than once; PeakCommerce recognizes an event it has already handled and doesn't apply it twice.
* **A failure is retried, not lost.** If PeakCommerce can't process an event, it tells Stripe so, and Stripe retries it on its usual schedule.

## Bringing existing subscriptions up to date

Subscriptions that changed in Stripe before sync was connected can be refreshed from Stripe with the admin API's `POST /api/v1/billing/stripe/resync`. It needs an API key with the `admin` scope and works in two steps:

1. Call it **without** `?execute=true` for a dry run. Nothing changes; the response lists what would change and includes a `planToken`.
2. Review the plan, then call it again with `?execute=true` and that `planToken` in the body to apply exactly the reviewed plan.

You can limit it to one subscription (`subscriptionId`) or one Stripe integration (`integrationId`).

## Related

* [Stripe](/integrations/billing-and-payments/stripe-payments.md) — connecting Stripe as your payment processor
* [Webhooks](https://gitlab.com/peakcommerce/peak-help-docs/-/tree/main/product/settings/developer-tools/webhooks.md) — receiving `subscription.changed`, `subscription.cancelled` and payment events in your own systems
* [Subscriptions API](https://gitlab.com/peakcommerce/peak-help-docs/-/tree/main/developers/api-reference/subscriptions.md) — including cancelling a Stripe subscription at the end of its paid period


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.peakcommerce.com/integrations/billing-and-payments/stripe-payments/stripe-subscription-sync.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.