subscription.created

Occurs when a subscription is created. Paddle automatically creates subscriptions for recurring items when automatically-collected transactions are completed, or when manually-collected transactions are billed.

subscription.trialing or subscription.activated typically follow.

Payload includes the complete subscription entity, except management_urls. Subscription management links are temporary, so they're not included. Get a subscription using the API to get management links for a subscription.

It also includes a transaction_id field, which contains the Paddle ID of the completed or billed transaction that caused Paddle to create this subscription. You can use this to match the created subscription with related transaction events as part of provisioning. Other subscription events do not include this field, and it is not returned by the API when working with subscription entities.

event_idstring

Unique Paddle ID for this event, prefixed with evt_.

event_typestring

Type of event sent by Paddle, in the format entity.event_type.

occurred_atstring<date-time>

RFC 3339 datetime string of when this event occurred.

dataobject

New or changed entity.

idstring

Unique Paddle ID for this subscription entity, prefixed with sub_.

transaction_idstring

Paddle ID for the transaction entity that resulted in this subscription being created, prefixed with txn_.

statusstring

Status of this subscription. Set automatically by Paddle. Use the pause subscription or cancel subscription operations to change.

customer_idstring

Paddle ID of the customer that this subscription is for, prefixed with ctm_.

address_idstring

Paddle ID of the address that this subscription is for, prefixed with add_.

business_idstring or null

Paddle ID of the business that this subscription is for, prefixed with biz_.

currency_codestring

Supported three-letter ISO 4217 currency code. Transactions for this subscription are created in this currency. Must be USD, EUR, or GBP if collection_mode is manual.

created_atstring<date-time>

RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.

updated_atstring<date-time>

RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.

started_atstring<date-time> or null

RFC 3339 datetime string of when this subscription started. This may be different from first_billed_at if the subscription started in trial.

first_billed_atstring<date-time> or null

RFC 3339 datetime string of when this subscription was first billed. This may be different from started_at if the subscription started in trial.

next_billed_atstring<date-time> or null

RFC 3339 datetime string of when this subscription is next scheduled to be billed.

paused_atstring<date-time> or null

RFC 3339 datetime string of when this subscription was paused. Set automatically by Paddle when the pause subscription operation is used. null if not paused.

canceled_atstring<date-time> or null

RFC 3339 datetime string of when this subscription was canceled. Set automatically by Paddle when the cancel subscription operation is used. null if not canceled.

discountobject or null

Details of the discount applied to this subscription.

collection_modestring

How payment is collected for transactions created for this subscription. automatic for checkout, manual for invoices.

billing_detailsobject or null

Details for invoicing. Required if collection_mode is manual.

current_billing_periodobject or null

Current billing period for this subscription. Set automatically by Paddle based on the billing cycle. null for paused and canceled subscriptions.

billing_cycleobject

How often this subscription renews. Set automatically by Paddle based on the prices on this subscription.

scheduled_changeobject or null

Change that's scheduled to be applied to a subscription. Use the pause subscription, cancel subscription, and resume subscription operations to create scheduled changes. null if no scheduled changes.

itemsarray[object]

Represents a subscription item.

custom_dataobject or null

Your own structured key-value data.

import_metaobject or null

Import information for this entity. null if this entity is not imported.

notification_idstring

Unique Paddle ID for this notification, prefixed with ntf_.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "event_id": "evt_01hv8x2acma2gz7he8kg2s0hna",
3  "event_type": "subscription.created",
4  "occurred_at": "2024-04-12T10:18:49.621022Z",
5  "notification_id": "ntf_01hv8x2af22vrrz7k67g06x1kq",
6  "data": {
7    "id": "sub_01hv8x29kz0t586xy6zn1a62ny",
8    "items": [
9      {
10        "price": {
11          "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
12          "name": "Monthly (per seat)",
13          "type": "standard",
14          "status": "active",
15          "quantity": {
16            "maximum": 999,
17            "minimum": 1
18          },
19          "tax_mode": "account_setting",
20          "created_at": "2023-02-23T13:55:22.538367Z",