# Subscription Webhooks > This request updates the merchant about statuses of their shoppers' subscriptions. The subscriptions' related events are: - `subscription_created` - `subscription_renewed` - `subscription_canceled` - `subscription_paused` - `subscription_unpaused` - `subscription_payment_failed` - `subscription_ended` Also see [API for managing webhooks](/api-reference/endpoints/webhooks/createwebhook/) for more details Source: https://help.boltapp.com/api-reference/subscriptions/webhooks/subscriptionwebhooks `POST /webhooks_subscriptions` ## OpenAPI definition This endpoint as it appears in the OpenAPI document, with every schema it references included. ```json { "openapi": "3.2.0", "info": { "title": "Subscriptions API", "version": "v1", "description": "API for managing subscriptions and products." }, "servers": [ { "url": "https://api.boltapp.com", "description": "The Production URL (Live Data)." }, { "url": "https://api-sandbox.boltapp.com", "description": "The Sandbox URL (Test Data)." }, { "url": "https://api-staging.boltapp.com", "description": "The Staging URL (Staged Data)." } ], "security": [ { "X-API-Key": [] }, { "X-Publishable-Key": [] } ], "paths": { "/webhooks_subscriptions": { "post": { "summary": "Subscription Webhooks", "operationId": "SubscriptionWebhooks", "security": [ { "X-API-Key": [] } ], "description": "This request updates the merchant about statuses of their shoppers' subscriptions. The subscriptions'\nrelated events are:\n- `subscription_created`\n- `subscription_renewed`\n- `subscription_canceled`\n- `subscription_paused`\n- `subscription_unpaused`\n- `subscription_payment_failed`\n- `subscription_ended`\n\nAlso see [API for managing webhooks](/api-reference/endpoints/webhooks/createwebhook/) for more details\n", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/bolt_hmac_param" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookBody" }, "examples": { "subscription_created": { "summary": "Subscription Created", "value": { "type": "subscription_created", "object": "subscription", "data": { "id": "s_ABC123DEF456", "created_at": "2025-11-01T11:34:23.267804Z", "updated_at": "2025-11-01T11:34:23.267804Z", "merchant_name": "Example Merchant", "consumer_id": 12345678, "email": "customer@example.com", "total_amount": { "amount": 7088, "currency": "USD", "currency_symbol": "$" }, "status_details": { "type": "active" }, "payment_method": { "card_last_4": "1234", "card_network": "Visa" }, "next_renewal_date": "2025-12-01T12:03:23.267804Z", "plan": { "id": "spl_ABC123456789", "name": "Monthly Subscription", "sku": "sku_sample123", "created_at": "2025-10-31T08:12:32.429044Z", "updated_at": "2025-10-31T08:12:32.429044Z", "frequency": 1, "product_id": "sp_DEF456GHI789", "frequency_unit": "month" }, "order": { "id": "so_ABC123DEF456", "sequence_number": 1, "subscription_id": "s_XYZ789ABC123", "transaction_reference": "ABCD-EFGH-IJKL", "placement_time": "2025-11-01T13:20:18.433474Z", "status": "done", "created_at": "2025-11-01T11:34:23.267804Z", "updated_at": "2025-11-01T11:34:23.267804Z", "total_amount": { "amount": 7088, "currency": "USD", "currency_symbol": "$" } }, "product_names": [ "Sample Product" ], "metadata": { "key1": "value1" } } } }, "subscription_renewed": { "summary": "Subscription Renewed", "value": { "type": "subscription_renewed", "object": "subscription", "data": { "id": "s_ABC123DEF456", "created_at": "2025-11-20T11:34:23.267804Z", "updated_at": "2025-11-20T11:34:23.267804Z", "merchant_name": "Example Merchant", "consumer_id": 12345678, "email": "customer@example.com", "total_amount": { "amount": 7088, "currency": "USD", "currency_symbol": "$" }, "status_details": { "type": "active" }, "payment_method": { "card_last_4": "1234", "card_network": "Visa" }, "next_renewal_date": "2025-12-01T12:03:23.267804Z", "plan": { "id": "spl_ABC123456789", "name": "Monthly Subscription", "sku": "sku_sample123", "created_at": "2025-10-31T08:12:32.429044Z", "updated_at": "2025-10-31T08:12:32.429044Z", "frequency": 1, "product_id": "sp_DEF456GHI789", "frequency_unit": "month" }, "previous_order": { "id": "so_ABC123DEF456", "sequence_number": 1, "subscription_id": "s_XYZ789ABC123", "transaction_reference": "ABCD-EFGH-IJKL", "placement_time": "2025-11-01T13:20:18.433474Z", "status": "done", "created_at": "2025-11-01T13:20:18.434332Z", "updated_at": "2025-11-01T13:20:18.442183Z", "total_amount": { "amount": 0, "currency": "USD", "currency_symbol": "$" } }, "new_order": { "id": "so_DEF456GHI789", "sequence_number": 2, "subscription_id": "s_XYZ789ABC123", "transaction_reference": "MNOP-QRST-UVWX", "placement_time": "2025-11-24T13:20:18.433474Z", "status": "done", "created_at": "2025-11-24T13:20:18.434332Z", "updated_at": "2025-11-24T13:20:18.442183Z", "total_amount": { "amount": 7088, "currency": "USD", "currency_symbol": "$" } }, "product_names": [ "Sample Product" ], "metadata": { "key1": "value1" } } } }, "subscription_paused": { "summary": "Subscription Paused", "value": { "type": "subscription_paused", "object": "subscription", "data": { "id": "s_ABC123DEF456", "created_at": "2025-11-01T11:34:23.267804Z", "updated_at": "2025-11-20T11:34:23.267804Z", "merchant_name": "Example Merchant", "consumer_id": 12345678, "email": "customer@example.com", "total_amount": { "amount": 7088, "currency": "USD", "currency_symbol": "$" }, "status_details": { "type": "paused" }, "payment_method": { "card_last_4": "1234", "card_network": "Visa" }, "next_renewal_date": "2026-01-01T12:03:23.267804Z", "plan": { "id": "spl_RtXNF1EYc3hl", "name": "Monthly Subscription", "sku": "sku_12345", "created_at": "2025-10-31T08:12:32.429044Z", "updated_at": "2025-10-31T08:12:32.429044Z", "frequency": 1, "product_id": "sp_3cpB8sldOIrC", "frequency_unit": "month" }, "product_names": [ "Sample Product" ], "metadata": { "key1": "value1" } } } }, "subscription_unpaused": { "summary": "Subscription Unpaused", "value": { "type": "subscription_unpaused", "object": "subscription", "data": { "id": "s_ABC123DEF456", "created_at": "2025-11-20T11:34:23.267804Z", "updated_at": "2025-11-20T11:34:23.267804Z", "merchant_name": "Example Merchant", "consumer_id": 12345678, "email": "customer@example.com", "total_amount": { "amount": 7088, "currency": "USD", "currency_symbol": "$" }, "status_details": { "type": "active" }, "payment_method": { "card_last_4": "1234", "card_network": "Visa" }, "next_renewal_date": "2025-11-20T12:03:23.267804Z", "plan": { "id": "spl_RtXNF1EYc3hl", "name": "Monthly Subscription", "sku": "sku_12345", "created_at": "2025-11-19T08:12:32.429044Z", "updated_at": "2025-11-19T08:12:32.429044Z", "frequency": 1, "product_id": "sp_3cpB8sldOIrC", "frequency_unit": "month" }, "product_names": [ "Sample Product" ], "metadata": { "key1": "value1" } } } }, "subscription_canceled": { "summary": "Subscription Canceled", "value": { "type": "subscription_canceled", "object": "subscription", "data": { "id": "s_ABC123DEF456", "created_at": "2025-11-20T11:34:23.267804Z", "updated_at": "2025-11-20T11:34:23.267804Z", "canceled_date": "2025-11-20T11:34:23.267804Z", "merchant_name": "Example Merchant", "consumer_id": 12345678, "email": "customer@example.com", "total_amount": { "amount": 7088, "currency": "USD", "currency_symbol": "$" }, "status_details": { "reason": "cancelled_manually", "type": "canceled" }, "payment_method": { "card_last_4": "1234", "card_network": "Visa" }, "next_renewal_date": null, "plan": { "id": "spl_RtXNF1EYc3hl", "name": "Monthly Subscription", "sku": "sku_12345", "created_at": "2025-11-19T08:12:32.429044Z", "updated_at": "2025-11-19T08:12:32.429044Z", "frequency": 1, "product_id": "sp_3cpB8sldOIrC", "frequency_unit": "month" }, "last_order": { "id": "so_H8yhsfJkLZr", "sequence_number": 3, "subscription_id": "s_BnZd9TXZ3W9y", "transaction_reference": "8ZNH-NM2P-PBX2", "placement_time": "2025-11-24T13:20:18.433474Z", "status": "done", "created_at": "2025-11-24T13:20:18.434332Z", "updated_at": "2025-11-24T13:20:18.442183Z", "total_amount": { "amount": 7088, "currency": "USD", "currency_symbol": "$" } }, "product_names": [ "Sample Product" ], "metadata": { "key1": "value1" } } } }, "subscription_payment_failed": { "summary": "Subscription Payment Failed", "value": { "type": "subscription_payment_failed", "object": "subscription", "data": { "id": "s_ABC123DEF456", "created_at": "2025-11-01T11:34:23.267804Z", "updated_at": "2025-11-30T11:34:23.267804Z", "merchant_name": "Example Merchant", "consumer_id": 12345678, "email": "customer@example.com", "total_amount": { "amount": 7088, "currency": "USD", "currency_symbol": "$" }, "status_details": { "reason": "payment_failed" }, "payment_method": { "card_last_4": "1234", "card_network": "Visa" }, "next_renewal_date": "2026-01-01T12:03:23.267804Z", "plan": { "id": "spl_RtXNF1EYc3hl", "name": "Monthly Subscription", "sku": "sku_12345", "created_at": "2025-10-31T08:12:32.429044Z", "updated_at": "2025-10-31T08:12:32.429044Z", "frequency": 1, "product_id": "sp_3cpB8sldOIrC", "frequency_unit": "month" }, "order": { "id": "so_H8yhsfJkLZr", "sequence_number": 3, "subscription_id": "s_BnZd9TXZ3W9y", "transaction_reference": "8ZNH-NM2P-PBX2", "placement_time": "2025-11-30T13:20:18.433474Z", "status": "done", "created_at": "2025-11-30T13:20:18.434332Z", "updated_at": "2025-11-30T13:20:18.442183Z", "total_amount": { "amount": 7088, "currency": "USD", "currency_symbol": "$" } }, "product_names": [ "Sample Product" ], "metadata": { "key1": "value1" } } } }, "subscription_ended": { "summary": "Subscription Ended", "value": { "type": "subscription_ended", "object": "subscription", "data": { "id": "s_ABC123DEF456", "created_at": "2025-11-01T11:34:23.267804Z", "updated_at": "2025-11-30T11:34:23.267804Z", "merchant_name": "Example Merchant", "consumer_id": 12345678, "email": "customer@example.com", "total_amount": { "amount": 7088, "currency": "USD", "currency_symbol": "$" }, "status_details": { "reason": "payment_failed" }, "payment_method": { "card_last_4": "1234", "card_network": "Visa" }, "plan": { "id": "spl_RtXNF1EYc3hl", "name": "Monthly Subscription", "sku": "sku_12345", "created_at": "2025-10-31T08:12:32.429044Z", "updated_at": "2025-10-31T08:12:32.429044Z", "frequency": 1, "product_id": "sp_3cpB8sldOIrC", "frequency_unit": "month" }, "product_names": [ "Sample Product" ], "metadata": { "key1": "value1" } } } } } } } }, "responses": { "200": { "$ref": "#/components/responses/WebhookSuccess" }, "422": { "$ref": "#/components/responses/WebhookError" } } } } }, "components": { "parameters": { "bolt_hmac_param": { "in": "header", "name": "X-Bolt-Hmac-Sha256", "schema": { "type": "string" }, "description": "Signed HMAC for hook verification" } }, "schemas": { "WebhookBody": { "oneOf": [ { "$ref": "#/components/schemas/SubscriptionCreatedWebhook" }, { "$ref": "#/components/schemas/SubscriptionRenewedWebhook" }, { "$ref": "#/components/schemas/SubscriptionCanceledWebhook" }, { "$ref": "#/components/schemas/SubscriptionPausedWebhook" }, { "$ref": "#/components/schemas/SubscriptionUnpausedWebhook" }, { "$ref": "#/components/schemas/SubscriptionPaymentFailedWebhook" }, { "$ref": "#/components/schemas/SubscriptionEndedWebhook" } ] }, "SubscriptionCreatedWebhook": { "type": "object", "properties": { "type": { "type": "string", "examples": [ "subscription_created" ] }, "object": { "type": "string", "examples": [ "subscription" ] }, "data": { "allOf": [ { "$ref": "#/components/schemas/Subscription" }, { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/WebhookSubscriptionOrder" } } } ] } }, "examples": [ { "type": "subscription_created", "object": "subscription", "data": { "id": "s_ABC123DEF456", "created_at": "2025-11-01T11:34:23.267804Z", "updated_at": "2025-11-01T11:34:23.267804Z", "merchant_name": "Example Merchant", "consumer_id": 12345678, "email": "customer@example.com", "total_amount": { "amount": 7088, "currency": "USD", "currency_symbol": "$" }, "status_details": { "type": "active" }, "payment_method": { "card_last_4": "1234", "card_network": "Visa" }, "next_renewal_date": "2025-12-01T12:03:23.267804Z", "plan": { "id": "spl_ABC123456789", "name": "Monthly Subscription", "sku": "sku_sample123", "created_at": "2025-10-31T08:12:32.429044Z", "updated_at": "2025-10-31T08:12:32.429044Z", "frequency": 1, "product_id": "sp_DEF456GHI789", "frequency_unit": "month" }, "order": { "id": "so_ABC123DEF456", "sequence_number": 1, "subscription_id": "s_XYZ789ABC123", "transaction_reference": "ABCD-EFGH-IJKL", "placement_time": "2025-11-01T13:20:18.433474Z", "status": "done", "created_at": "2025-11-01T11:34:23.267804Z", "updated_at": "2025-11-01T11:34:23.267804Z", "total_amount": { "amount": 7088, "currency": "USD", "currency_symbol": "$" } }, "product_names": [ "Sample Product" ], "metadata": { "key1": "value1" } } } ] }, "Subscription": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "s_1234567890" ] }, "created_at": { "type": "string", "format": "date-time", "examples": [ "2023-10-01T12:00:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "examples": [ "2023-10-01T12:00:00Z" ] }, "consumer_id": { "type": "integer", "format": "int64" }, "subscription_plan_id": { "type": "string", "description": "ID of the subscription plan.", "examples": [ "spl_ba_PpkW16oIW" ] }, "merchant_name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "price": { "type": "integer", "format": "int64", "description": "Deprecated. Use `total_amount` instead. Represents the price of the subscription in cents, e.g. `199` would translate to `$1.99`.", "deprecated": true, "examples": [ 999 ] }, "currency": { "type": "string", "description": "ISO4217 compatible currency code", "examples": [ "USD" ] }, "quantity": { "type": "integer", "format": "int64" }, "product_names": { "type": "array", "items": { "type": "string", "description": "Product name" } }, "next_renewal_date": { "type": [ "string", "null" ], "format": "date-time" }, "canceled_date": { "type": [ "string", "null" ], "format": "date-time", "examples": [ null ] }, "paused_date": { "type": [ "string", "null" ], "format": "date-time", "examples": [ null ] }, "payment_method": { "$ref": "#/components/schemas/PaymentMethod" }, "status": { "$ref": "#/components/schemas/SubscriptionStatus", "deprecated": true }, "status_details": { "$ref": "#/components/schemas/StatusDetails" }, "total_amount": { "$ref": "#/components/schemas/AmountView" }, "plan": { "$ref": "#/components/schemas/Plan" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "PaymentMethod": { "type": "object", "properties": { "card_last_4": { "type": "string", "examples": [ "4123" ] }, "card_network": { "type": "string", "examples": [ "Visa" ] } }, "required": [ "card_last_4", "card_network" ] }, "SubscriptionStatus": { "type": "string", "enum": [ "active", "paused", "canceled", "payment_failed" ], "examples": [ "active" ] }, "StatusDetails": { "type": "object", "properties": { "reason": { "type": [ "string", "null" ], "description": "Reason for the current status", "enum": [ "payment_failed", "cancelled_manually" ], "examples": [ "payment_failed" ] }, "type": { "type": "string", "description": "Type of status detail", "enum": [ "active", "paused", "canceled", "payment_failed" ], "examples": [ "canceled" ] } } }, "AmountView": { "type": "object", "properties": { "amount": { "type": "integer", "format": "int64", "description": "Amount in cents" }, "currency": { "type": "string", "description": "ISO4217 compatible currency code" }, "currency_symbol": { "type": "string", "description": "Currency symbol" } } }, "Plan": { "type": "object", "properties": { "id": { "type": "string", "description": "unique identifier for the plan.", "examples": [ "spl_ba_PpkW16oIW" ] }, "name": { "type": "string", "description": "Name of the plan.", "examples": [ "Monthly Subscription" ] }, "sku": { "type": "string", "description": "SKU of the product.", "examples": [ "BOLT-12345" ] }, "created_at": { "type": "string", "format": "date-time", "examples": [ "2023-10-01T12:00:00Z" ] }, "updated_at": { "type": "string", "format": "date-time", "examples": [ "2023-10-01T12:00:00Z" ] }, "frequency": { "type": "integer", "format": "int64", "examples": [ 1 ] }, "product_id": { "type": "string", "description": "ID of the product associated with the plan.", "examples": [ "sp_Tlj0Osm0N76T" ] }, "frequency_unit": { "type": "string", "description": "Unit of frequency (e.g., week, month).", "enum": [ "day", "week", "month", "year" ], "examples": [ "month" ] }, "initial_period": { "type": [ "object", "null" ], "description": "How long the initial period lasts before we move over to the regular plan.", "properties": { "frequency": { "type": "integer", "format": "int64", "description": "Number of units the initial period lasts.", "examples": [ 2 ] }, "frequency_unit": { "type": "string", "enum": [ "day", "week", "month", "year" ], "description": "Unit of the initial period (e.g. week, month).", "examples": [ "week" ] } } }, "checkout_link": { "type": "string", "description": "Checkout link for the plan.", "examples": [ "https://your_site.c.boltapp.com/g?merchant_product_id=37&merchant_variant_id=67&publishable_key=BQ9PKQksUGtj.Q9LwVLfV3WF4.32122926f7b9651a416a5099dc92dc2b4c87c8b922c114229f83b345d65f1195" ] } } }, "Metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "WebhookSubscriptionOrder": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the subscription order.", "examples": [ "so_ABC123DEF456" ] }, "sequence_number": { "type": "integer", "description": "Sequential number of the order in the subscription", "examples": [ 1 ] }, "subscription_id": { "type": "string", "description": "ID of the subscription associated with the order.", "examples": [ "s_XYZ789ABC123" ] }, "transaction_reference": { "type": "string", "description": "Reference ID for the transaction", "examples": [ "ABCD-EFGH-IJKL" ] }, "placement_time": { "type": "string", "format": "date-time", "description": "When the order was placed", "examples": [ "2025-11-01T13:20:18.433474Z" ] }, "status": { "type": "string", "description": "Status of the order", "examples": [ "done" ] }, "created_at": { "type": "string", "format": "date-time", "examples": [ "2025-11-01T11:34:23.267804Z" ] }, "updated_at": { "type": "string", "format": "date-time", "examples": [ "2025-11-01T11:34:23.267804Z" ] }, "total_amount": { "$ref": "#/components/schemas/AmountView" } } }, "SubscriptionRenewedWebhook": { "type": "object", "properties": { "type": { "type": "string", "examples": [ "subscription_renewed" ] }, "object": { "type": "string", "examples": [ "subscription" ] }, "data": { "allOf": [ { "$ref": "#/components/schemas/Subscription" }, { "type": "object", "properties": { "previous_order": { "$ref": "#/components/schemas/WebhookSubscriptionOrder" }, "new_order": { "$ref": "#/components/schemas/WebhookSubscriptionOrder" } } } ] } }, "examples": [ { "type": "subscription_renewed", "object": "subscription", "data": { "id": "s_ABC123DEF456", "created_at": "2025-11-20T11:34:23.267804Z", "updated_at": "2025-11-20T11:34:23.267804Z", "merchant_name": "Example Merchant", "consumer_id": 12345678, "email": "customer@example.com", "total_amount": { "amount": 7088, "currency": "USD", "currency_symbol": "$" }, "status_details": { "type": "active" }, "payment_method": { "card_last_4": "1234", "card_network": "Visa" }, "next_renewal_date": "2025-12-01T12:03:23.267804Z", "plan": { "id": "spl_ABC123456789", "name": "Monthly Subscription", "sku": "sku_sample123", "created_at": "2025-10-31T08:12:32.429044Z", "updated_at": "2025-10-31T08:12:32.429044Z", "frequency": 1, "product_id": "sp_DEF456GHI789", "frequency_unit": "month" }, "previous_order": { "id": "so_ABC123DEF456", "sequence_number": 1, "subscription_id": "s_XYZ789ABC123", "transaction_reference": "ABCD-EFGH-IJKL", "placement_time": "2025-11-01T13:20:18.433474Z", "status": "done", "created_at": "2025-11-01T13:20:18.434332Z", "updated_at": "2025-11-01T13:20:18.442183Z", "total_amount": { "amount": 0, "currency": "USD", "currency_symbol": "$" } }, "new_order": { "id": "so_DEF456GHI789", "sequence_number": 2, "subscription_id": "s_XYZ789ABC123", "transaction_reference": "MNOP-QRST-UVWX", "placement_time": "2025-11-24T13:20:18.433474Z", "status": "done", "created_at": "2025-11-24T13:20:18.434332Z", "updated_at": "2025-11-24T13:20:18.442183Z", "total_amount": { "amount": 7088, "currency": "USD", "currency_symbol": "$" } }, "product_names": [ "Sample Product" ], "metadata": { "key1": "value1" } } } ] }, "SubscriptionCanceledWebhook": { "type": "object", "properties": { "type": { "type": "string", "examples": [ "subscription_canceled" ] }, "object": { "type": "string", "examples": [ "subscription" ] }, "data": { "allOf": [ { "$ref": "#/components/schemas/Subscription" }, { "type": "object", "properties": { "last_order": { "$ref": "#/components/schemas/WebhookSubscriptionOrder" } } } ] } }, "examples": [ { "type": "subscription_canceled", "object": "subscription", "data": { "id": "s_ABC123DEF456", "created_at": "2025-11-20T11:34:23.267804Z", "updated_at": "2025-11-20T11:34:23.267804Z", "canceled_date": "2025-11-20T11:34:23.267804Z", "merchant_name": "Example Merchant", "consumer_id": 12345678, "email": "customer@example.com", "total_amount": { "amount": 7088, "currency": "USD", "currency_symbol": "$" }, "status_details": { "reason": "cancelled_manually", "type": "canceled" }, "payment_method": { "card_last_4": "1234", "card_network": "Visa" }, "next_renewal_date": null, "plan": { "id": "spl_RtXNF1EYc3hl", "name": "Monthly Subscription", "sku": "sku_12345", "created_at": "2025-11-19T08:12:32.429044Z", "updated_at": "2025-11-19T08:12:32.429044Z", "frequency": 1, "product_id": "sp_3cpB8sldOIrC", "frequency_unit": "month" }, "last_order": { "id": "so_H8yhsfJkLZr", "sequence_number": 3, "subscription_id": "s_BnZd9TXZ3W9y", "transaction_reference": "8ZNH-NM2P-PBX2", "placement_time": "2025-11-24T13:20:18.433474Z", "status": "done", "created_at": "2025-11-24T13:20:18.434332Z", "updated_at": "2025-11-24T13:20:18.442183Z", "total_amount": { "amount": 7088, "currency": "USD", "currency_symbol": "$" } }, "product_names": [ "Sample Product" ], "metadata": { "key1": "value1" } } } ] }, "SubscriptionPausedWebhook": { "type": "object", "properties": { "type": { "type": "string", "examples": [ "subscription_paused" ] }, "object": { "type": "string", "examples": [ "subscription" ] }, "data": { "$ref": "#/components/schemas/Subscription" } }, "examples": [ { "type": "subscription_paused", "object": "subscription", "data": { "id": "s_ABC123DEF456", "created_at": "2025-11-01T11:34:23.267804Z", "updated_at": "2025-11-20T11:34:23.267804Z", "merchant_name": "Example Merchant", "consumer_id": 12345678, "email": "customer@example.com", "total_amount": { "amount": 7088, "currency": "USD", "currency_symbol": "$" }, "status_details": { "type": "paused" }, "payment_method": { "card_last_4": "1234", "card_network": "Visa" }, "next_renewal_date": "2026-01-01T12:03:23.267804Z", "plan": { "id": "spl_RtXNF1EYc3hl", "name": "Monthly Subscription", "sku": "sku_12345", "created_at": "2025-10-31T08:12:32.429044Z", "updated_at": "2025-10-31T08:12:32.429044Z", "frequency": 1, "product_id": "sp_3cpB8sldOIrC", "frequency_unit": "month" }, "product_names": [ "Sample Product" ], "metadata": { "key1": "value1" } } } ] }, "SubscriptionUnpausedWebhook": { "type": "object", "properties": { "type": { "type": "string", "examples": [ "subscription_unpaused" ] }, "object": { "type": "string", "examples": [ "subscription" ] }, "data": { "$ref": "#/components/schemas/Subscription" } }, "examples": [ { "type": "subscription_unpaused", "object": "subscription", "data": { "id": "s_ABC123DEF456", "created_at": "2025-11-20T11:34:23.267804Z", "updated_at": "2025-11-20T11:34:23.267804Z", "merchant_name": "Example Merchant", "consumer_id": 12345678, "email": "customer@example.com", "total_amount": { "amount": 7088, "currency": "USD", "currency_symbol": "$" }, "status_details": { "type": "active" }, "payment_method": { "card_last_4": "1234", "card_network": "Visa" }, "next_renewal_date": "2025-11-20T12:03:23.267804Z", "plan": { "id": "spl_RtXNF1EYc3hl", "name": "Monthly Subscription", "sku": "sku_12345", "created_at": "2025-11-19T08:12:32.429044Z", "updated_at": "2025-11-19T08:12:32.429044Z", "frequency": 1, "product_id": "sp_3cpB8sldOIrC", "frequency_unit": "month" }, "product_names": [ "Sample Product" ], "metadata": { "key1": "value1" } } } ] }, "SubscriptionPaymentFailedWebhook": { "type": "object", "properties": { "type": { "type": "string", "examples": [ "subscription_payment_failed" ] }, "object": { "type": "string", "examples": [ "subscription" ] }, "data": { "allOf": [ { "$ref": "#/components/schemas/Subscription" }, { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/WebhookSubscriptionOrder" } } } ] } }, "examples": [ { "type": "subscription_payment_failed", "object": "subscription", "data": { "id": "s_ABC123DEF456", "created_at": "2025-11-01T11:34:23.267804Z", "updated_at": "2025-11-30T11:34:23.267804Z", "merchant_name": "Example Merchant", "consumer_id": 12345678, "email": "customer@example.com", "total_amount": { "amount": 7088, "currency": "USD", "currency_symbol": "$" }, "status_details": { "reason": "payment_failed" }, "payment_method": { "card_last_4": "1234", "card_network": "Visa" }, "next_renewal_date": "2026-01-01T12:03:23.267804Z", "plan": { "id": "spl_RtXNF1EYc3hl", "name": "Monthly Subscription", "sku": "sku_12345", "created_at": "2025-10-31T08:12:32.429044Z", "updated_at": "2025-10-31T08:12:32.429044Z", "frequency": 1, "product_id": "sp_3cpB8sldOIrC", "frequency_unit": "month" }, "order": { "id": "so_H8yhsfJkLZr", "sequence_number": 3, "subscription_id": "s_BnZd9TXZ3W9y", "transaction_reference": "8ZNH-NM2P-PBX2", "placement_time": "2025-11-30T13:20:18.433474Z", "status": "done", "created_at": "2025-11-30T13:20:18.434332Z", "updated_at": "2025-11-30T13:20:18.442183Z", "total_amount": { "amount": 7088, "currency": "USD", "currency_symbol": "$" } }, "product_names": [ "Sample Product" ], "metadata": { "key1": "value1" } } } ] }, "SubscriptionEndedWebhook": { "type": "object", "properties": { "type": { "type": "string", "examples": [ "subscription_ended" ] }, "object": { "type": "string", "examples": [ "subscription" ] }, "data": { "allOf": [ { "$ref": "#/components/schemas/Subscription" } ] } }, "examples": [ { "type": "subscription_ended", "object": "subscription", "data": { "id": "s_ABC123DEF456", "created_at": "2025-11-01T11:34:23.267804Z", "updated_at": "2025-11-30T11:34:23.267804Z", "merchant_name": "Example Merchant", "consumer_id": 12345678, "email": "customer@example.com", "total_amount": { "amount": 7088, "currency": "USD", "currency_symbol": "$" }, "status_details": { "reason": "payment_failed" }, "payment_method": { "card_last_4": "1234", "card_network": "Visa" }, "plan": { "id": "spl_RtXNF1EYc3hl", "name": "Monthly Subscription", "sku": "sku_12345", "created_at": "2025-10-31T08:12:32.429044Z", "updated_at": "2025-10-31T08:12:32.429044Z", "frequency": 1, "product_id": "sp_3cpB8sldOIrC", "frequency_unit": "month" }, "product_names": [ "Sample Product" ], "metadata": { "key1": "value1" } } } ] }, "Error": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorReason" } } } }, "ErrorCode": { "type": "integer", "format": "int64", "description": "This is an error code.", "examples": [ 2001005 ] }, "ErrorReason": { "type": "object", "description": "The reason for the error.", "properties": { "reason": { "type": "string", "examples": [ "This subscription is invalid." ] } } } }, "responses": { "WebhookSuccess": { "description": "Webhooks Subscription Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "succeeded", "failed" ], "examples": [ "succeeded" ] } } } } } }, "WebhookError": { "description": "Webhooks Transaction Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "succeeded", "failed" ], "examples": [ "failed" ] }, "error": { "$ref": "#/components/schemas/Error" } } } } } } }, "securitySchemes": { "X-API-Key": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "X-Publishable-Key": { "type": "apiKey", "in": "header", "name": "X-Publishable-Key" } } } } ```