Manage subscriptions

Use this page to retrieve, update, cancel, and recover subscriptions after creation.

Management actions should update your internal records and keep access aligned with invoice events and the latest subscription state.

What this page is for

This page covers:

• retrieving a subscription;
• updating supported fields;
• canceling a subscription;
• understanding period-end cancellation fields;
• resuming eligible past_due subscriptions;
• storing state after management actions.

Before you start

Store the subscription_id when the subscription is created. You need it to retrieve the subscription, update it, cancel it, and reconcile invoice events.

Also store your internal user, account, workspace, or tenant ID so management actions affect the correct product account.

Retrieve a subscription

Retrieve the subscription before making customer-visible decisions.

curl https://api.paypercut.io/v1/subscriptions/01HD7M6DRKZ4Q4QEVWJB0RC1S6 \
  -H "Authorization: Bearer $PAYPERCUT_SECRET_KEY"

Use the response to inspect:

• status;
• customer;
• current_period_start;
• current_period_end;
• next_billing_date;
• cancel_at_period_end;
• cancel_at;
• canceled_at;
• default_payment_method;
• items.

Update a subscription

Use the update endpoint for supported changes such as changing the default payment method, replacing items, ending a trial, updating metadata, or setting cancellation-related fields.

curl https://api.paypercut.io/v1/subscriptions/01HD7M6DRKZ4Q4QEVWJB0RC1S6 \
  -X POST \
  -H "Authorization: Bearer $PAYPERCUT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: update-subscription-payment-method-01" \
  -d '{
    "default_payment_method": "01NEWPAYMENTMETHODXXXXXXXX"
  }'

When updating items, the public API replaces the subscription item set with the provided items. Do not treat item updates as an append operation.

send_invoice is not available for public subscription updates even though it appears in schema descriptions as coming soon.

Cancel a subscription

The public API exposes cancellation through:

curl https://api.paypercut.io/v1/subscriptions/01HD7M6DRKZ4Q4QEVWJB0RC1S6 \
  -X DELETE \
  -H "Authorization: Bearer $PAYPERCUT_SECRET_KEY"

After cancellation, retrieve or use the returned Subscription object and update your internal state from these fields:

• status;
• canceled_at;
• ended_at;
• cancel_at_period_end;
• current_period_end;
• cancellation_details.

Do not rely on public subscription.canceled webhooks for your integration unless they are exposed in the public event enum for your account. Use the API response and your own action log, and continue processing invoice events.

Cancel at period end

The public OpenAPI describes cancel_at_period_end and cancel_at fields. The verified service implementation needs product/API confirmation before this guide can give a fully reliable period-end cancellation task flow.

Until that is resolved:

1. Prefer retrieving the subscription after any cancellation request.
2. Use the returned status, cancel_at_period_end, cancel_at, canceled_at, ended_at, and current_period_end fields as the source of truth.
3. Keep customer access aligned with your product policy and the returned effective end fields.

Resume or recover a subscription

Use resume for eligible past_due subscriptions that use automatic collection.

Resume attempts to collect the outstanding billing-cycle payment. If payment succeeds, the subscription moves back to active. If payment fails, the API returns 402 and the subscription remains past_due.

curl https://api.paypercut.io/v1/subscriptions/01HD7M6DRKZ4Q4QEVWJB0RC1S6/resume \
  -X POST \
  -H "Authorization: Bearer $PAYPERCUT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: resume-subscription-01" \
  -d '{
    "billing_cycle_anchor": "now"
  }'

Use billing_cycle_anchor: "now" to reset the billing cycle anchor to the resume time. Use billing_cycle_anchor: "unchanged" to keep the original billing cadence.

Before calling resume, make sure the customer has a valid default payment method. This phase did not verify a hosted payment recovery flow, so do not assume one exists.

What changes immediately

What changes at the end of the billing period

Use current_period_end as the billing-period boundary for access decisions. For period-end cancellation behavior, retrieve the latest subscription and follow the returned fields until the cancellation behavior mismatch is resolved.

What to store after changes

After a management action, store:

• subscription_id;
• latest status;
• current_period_start;
• current_period_end;
• next_billing_date;
• cancel_at_period_end;
• cancel_at;
• canceled_at;
• ended_at;
• latest default_payment_method when relevant;
• the action your backend initiated and its idempotency key.

What events and invoices to monitor

Continue handling:

Payment and PaymentIntent events can help with support and reconciliation, but they are not the primary subscription lifecycle source.

Common mistakes

• Updating a subscription but not storing the returned state.
• Assuming item updates append instead of replacing items.
• Calling resume before the customer has a valid default payment method.
• Treating a failed resume as a successful recovery.
• Depending on public subscription.* webhooks that are not exposed in the public event enum.
• Assuming period-end cancellation behavior without retrieving the returned subscription.

Troubleshooting

Related pages

• Lifecycle and statuses
• Invoices and payment collection
• Webhooks for subscription integrations
• Create subscriptions directly