Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions content/docs/admin-api/guides/subscription-management.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,29 @@ The endpoint returns the full subscription object with updated renewal details o
The subscription must be in an `active` status to trigger a renewal. For subscriptions in `past_due` status, use the [subscriptionsRetryCreate](/docs/admin-api/reference/subscriptions/subscriptionsRetryCreate) endpoint instead.
</Callout>

### Identifying Subscription Charges

When a `transaction.created` webhook is associated with a subscription, `data.subscription` contains the subscription ID and billing cycle:

```json title="Subscription Transaction"
{
"event_type": "transaction.created",
"data": {
"id": 10416,
"subscription": {
"id": 12345,
"billing_cycle": 3
}
}
}
```

- `billing_cycle: 0` identifies the initial subscription charge.
- `billing_cycle: 1` identifies the first renewal.
- Each subsequent renewal increments the value by one.

The subscription object is empty when the transaction is not associated with a subscription.

### Updating Payment Details

Updating the Payment Gateway of a subscription can done through the [subscriptionsPartialUpdate](/docs/admin-api/reference/subscriptions/subscriptionsPartialUpdate) endpoint.
Expand Down
4 changes: 4 additions & 0 deletions content/docs/webhooks/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,10 @@ Returning a `410` response code indicates the target resource is no longer avail
| `ticket.created` | Triggers a new support ticket is created. | [View Example](/docs/webhooks/reference/support/ticket.created) |
| `ticket.updated` | Triggers when an existing support ticket is updated. | [View Example](/docs/webhooks/reference/support/ticket.updated) |

<Callout type="info" title="Handling subscription charges">
The `subscription` object on a `transaction.created` webhook links the charge to its subscription and identifies the billing cycle. See [Identifying Subscription Charges](/docs/admin-api/guides/subscription-management#identifying-subscription-charges).
</Callout>

### Webhook Data Structure

Webhook payloads follow the same structure as Admin API data serializers, which makes them predictable. In general, the data in a webhook payload matches the data you would get by retrieving the same resource through the API. You can set up test webhooks and view the webhook logs in the dashboard to help build and verify your receiver.
Expand Down