---
title: "Sandbox only: advance a subscription to its next billing event"
method: POST
path: "/api/v1/test-helpers/subscriptions/{id}/advance"
tags: ["Subscriptions"]
---

# Sandbox only: advance a subscription to its next billing event

`POST /api/v1/test-helpers/subscriptions/{id}/advance`

## Request

- Base URL: `https://merchant.zahlo.eu`
- URL: `https://merchant.zahlo.eu/api/v1/test-helpers/subscriptions/{id}/advance`
- Auth: API key in header `x-api-key`

Moves the subscription's own dates like a test clock and feeds a synthetic outcome to the real billing handlers, so the real subscription events and customer notices follow. Nothing is charged and no Payment is written. 404 resource_not_available outside the sandbox.

## Path parameters

- `id` string, required

## Request body

- SubscriptionAdvanceRequest
  - `to` 'trial_will_end' | 'renewal_succeeded' | 'renewal_failed' | 'renewal_requires_action' | 'sepa_returned' | 'period_end', required

## Response `200`

Successful response

- Subscription
  - `id` string, required
  - `object` 'subscription', required
  - `livemode` boolean
  - `createdAt` string, date-time
  - `customerId` string, required
  - `priceId` string, required
  - `quantity` integer
  - `status` 'incomplete' | 'trialing' | 'active' | 'past_due' | 'paused' | 'cancelled', required
  - `currency` string, required
  - `amountMinor` integer, required: The current or next period's charge, after discount.
  - `couponId` string, nullable
  - `discountEndsAt` string, date-time, nullable
  - `paymentMethodId` string, nullable
  - `rail` 'card' | 'sepa_debit'
  - `trialEnd` string, date-time, nullable
  - `currentPeriodStart` string, date-time, nullable
  - `currentPeriodEnd` string, date-time, nullable
  - `cancelAtPeriodEnd` boolean, required
  - `cancelledAt` string, date-time, nullable
  - `cancellationReason` 'requested' | 'payment_failed', nullable
  - `pastDueSince` string, date-time, nullable
  - `latestPaymentId` string, nullable
  - `pendingUpdate` object, nullable
    - `priceId` string
    - `quantity` integer
    - `effectiveAt` string, date-time
  - `prorationMinor` integer: Proration for an upgrade or seat increase, added to the next period's charge.
  - `addOns` object[]: More recurring prices billed with the main price every period, discounted with it. `pendingQuantity` takes effect at the period end (0 removes the add-on).
    - `priceId` string, required
    - `quantity` integer, required
    - `pendingQuantity` integer, nullable, required
  - `metadata` object: Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.

## Other responses

- `400`: Invalid request
- `401`: Authentication failed
- `404`: Resource not found
- `409`: Request conflicts with existing state

---

[API](https://skmtc.dev/zahlo/apis/zahlo-merchant-api.md) - [All operations](https://skmtc.dev/zahlo/apis/zahlo-merchant-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zahlo/apis/zahlo-merchant-api/revisions/8fcbef981e0d?raw)