# Subscription payment updates Webhooks for subscription status provide real-time notifications about changes in subscription status. The webhook structure is similar to the subscription status method but additionally includes the `callback_type` parameter in the response object. There are two versions of subscription events: legacy and extended. The extended version offers an enhanced webhook event set with more detail and context, giving merchants deeper insights into subscription stages for better management and analysis. The legacy version remains supported until the end of August 2026. Duplicate webhook events can occur. Implement idempotency on your end to avoid processing the same event twice.Parameters for each callback type can vary based on factors such as product type, payment method, trial availability, or other specific conditions. Endpoint: POST Billing Version: 1.0.0 Security: merchant, signature ## Security: - `merchant` (unknown) apiKey in header merchant - `signature` (unknown) apiKey in header signature ## Header parameters: - `merchant` (string, required) - `signature` (string, required) - `solidgate-event-id` (string, required) Unique event identifier. - `solidgate-event-created-at` (string, required) Event creation time in UTC as ISO 8601 with milliseconds. - `solidgate-event-type` (string, required) Event type, indicating the specific event that occurred. ## Request fields (application/json): - `callback_type` (string, required) Subscription event type, representing a specific change in the subscription lifecycle. View parameters specific to a particular callback type by choosing the relevant callback type. Enum: "create", "init" - `subscription` (object, required) Subscription details, including its status, payment method, and other essential information for tracking and managing its lifecycle. - `subscription.id` (string, required) Unique subscription identifier. - `subscription.status` (string, required) Subscription status. Enum: "pending" - `subscription.updated_at` (string, required) Datetime of the subscription update. - `subscription.payment_type` (string) Customer payment method used to pay for a subscription. Enum: "card", "paypal-vault", "mercadopago", "upi", "pix", "gcash", "alipay", "mbway", "wechatpay" - `subscription.discount` (object) Contains information about the discount applied. - `subscription.discount.created_at` (string, required) Datetime of the discount creation. Example: 2025-05-31 12:53:12 - `subscription.discount.coupon_code` (string) Coupon code. Example: SUMMER25OFF - `subscription.discount.coupon` (object, required) Coupon details. - `subscription.discount.coupon.name` (string, required) Coupon name. Example: Summer 25% OFF - `subscription.discount.coupon.description` (string) Coupon description. Example: 25% off for 3 months - `subscription.discount.coupon.type` (string, required) Discount type indicating percentage or fixed amount off the price. Enum: "percentage", "amount" - `subscription.discount.coupon.value` (integer, required) Discount value. Depending on the coupon type, the value represents either a percentage or a fixed amount. Example: 25 - `subscription.trial` (boolean, required) Indicates whether the subscription is in trial period. - `product` (object, required) Subscription product details, including name, pricing logic, amount, currency, trial settings, and other related attributes. The list of fields within the object differs from the field set during the creation of the product request. - `product.product_id` (string, required) Unique product identifier. - `product.name` (string, required) Product name. - `product.payment_action` (string) Specifies a payment flow applied to the first transaction, with or without the next money return, for: - **free trial** - the payment actions are `auth_0_amount` and `auth_void`, with the last indicating that the funds will be refunded to the customer - **paid trial** - the payment action is `auth_settle`, indicating the funds will be deducted from the customer's account as payment for the trial period and transferred to the merchant's account Required if product has a trial. Enum: "auth_0_amount", "auth_void", "auth_settle" - `product.amount` (integer, required) Product price. - `product.currency` (string, required) Three-letter ISO-4217 currency code of the product price currency. - `product.trial` (boolean, required) Indicates whether the product has a trial. - `product.trial_period` (integer) Indicates the trial period in minutes. Required if the product has a trial. - `product.trial_amount` (integer) Trial price. Required if product has a trial. - `product.trial_currency` (string) Three-letter ISO-4217 currency code of the trial price currency. Required if product has a trial. - `customer` (object, required) Customer details related to the subscription, including key information such as the customer's email address. - `customer.customer_account_id` (string, required) Unique customer identifier defined by the merchant. - `customer.customer_email` (string, required) Customer's email address. - `invoices` (object) Latest invoice for the subscription, including billing information, current state, financial details, and associated order history. - `invoices.` (object) Invoice for the last billing period. - `invoices..id` (string, required) Unique invoice identifier associated with a specific subscription. - `invoices..status` (string, required) Invoice status. Enum: "processing" - `invoices..created_at` (string, required) Datetime of the invoice creation. - `invoices..updated_at` (string, required) Datetime of the invoice update. - `invoices..amount` (integer, required) Current subscription price. - `invoices..product_price_id` (string) Unique product price identifier applied to the invoice. Use it to distinguish prices configured for different currencies and locations within the same product for product and price management. null is returned if the product has no prices configured for other currencies and locations. Example: 61b7f690-242a-498c-99a1-eb191f93f08c - `invoices..discount` (object) Contains information about the discount applied. - `invoices..discount.created_at` (string, required) Datetime of the discount creation. Example: 2025-05-31 12:53:12 - `invoices..discount.coupon_code` (string) Coupon code. Example: SUMMER25OFF - `invoices..discount.coupon` (object, required) Coupon details. - `invoices..discount.coupon.name` (string, required) Coupon name. Example: Summer 25% OFF - `invoices..discount.coupon.description` (string) Coupon description. Example: 25% off for 3 months - `invoices..discount.coupon.type` (string, required) Discount type indicating percentage or fixed amount off the price. Enum: "percentage", "amount" - `invoices..discount.coupon.value` (integer, required) Discount value. Depending on the coupon type, the value represents either a percentage or a fixed amount. Example: 25 - `invoices..subscription_term_number` (integer) Indicates the number of passed subscription periods, excluding the trial period. The value increments when a new billing period begins or when the subscription is upgraded or downgraded with a billing period change. Filled if invoice is created:before March 1, 2024 only for the invoice with a success statuson or after March 1, 2024, regardless of the invoice status - `invoices..orders` (object, required) Map of orders, including details such as current status, creation and processing timestamps, and other related transaction information. - `invoices..orders.` (object) Single order, where `` is a dynamically generated unique order identifier. - `invoices..orders..id` (string, required) Unique order identifier, which can be used to find the payment. For the first payment, the identifier is defined by the merchant.For recurring subscription-based payments, it is generated by the Solidgate subscription service. - `invoices..orders..status` (string, required) Status of the requested card or APM order. Enum: "processing" - `invoices..orders..created_at` (string, required) Datetime of the order creation. - `invoices..orders..updated_at` (string) Datetime of the order update. - `invoices..orders..processed_at` (string) Datetime when the order was processed. It is empty for orders in processing. - `invoices..orders..amount` (integer, required) Original order amount. - `invoices..orders..retry_attempt` (integer) Indicates the number of retry attempt for the invoice. Filled for orders created according to retry strategy. - `invoices..orders..payment_details` (object) Details of the payer for transactions conducted through APMs. It provides essential information like the customer's email and the invoice identifier, both of which are specifically applicable to transactions conducted with the PayPal method. - `invoices..orders..payment_details.invoice_id` (string) Unique invoice identifier provided by PayPal. - `invoices..orders..payment_details.payer_email` (string) Customer's email. It is provided only for the transactions with paypal-vault method. - `invoices..orders..operation` (string) Type of the transaction. Enum: "pay", "recurring", "recurring-auth", "refund", "resign", "resign-auth", "auth", "settle", "void", "apple-pay", "google-pay" - `invoices..order_metadata` (object) Metadata is useful for storing additional, structured information about an object. - `callback_type` (string, required) Subscription event type, representing a specific change in the subscription lifecycle. Enum: "expire", "payment_attempt", "active", "renew", "switch_product", "pause", "pause_schedule.create", "pause_schedule.update", "pause_schedule.delete", "resume", "recurring", "restore", "cancel", "scheduled_for_cancellation", "redemption", "retry", "scheduled_for_retry", "update" - `callback_type` (string, required) Subscription event type, representing a specific change in the subscription lifecycle. If the subscription has multiple invoices, this event is only sent for the most recent invoice at the time the order status changes. Webhooks for orders on older invoices are suppressed. To receive events for all order updates regardless of invoice status, subscribe to card_gate.order.updated and alt_gate.order.updated. Enum: "order_update" ## Request examples: - `extended create` (unknown) - `extended expire` (unknown) - `extended payment_attempt` (unknown) - `extended active` (unknown) - `extended renew` (unknown) - `extended switch_product` (unknown) - `extended order_update` (unknown) - `extended pause` (unknown) - `extended pause_schedule.create` (unknown) - `extended pause_schedule.update` (unknown) - `extended pause_schedule.delete` (unknown) - `extended resume` (unknown) - `extended recurring` (unknown) - `extended restore` (unknown) - `extended cancel` (unknown) - `extended scheduled_for_cancellation` (unknown) - `extended redemption` (unknown) - `extended retry` (unknown) - `extended scheduled_for_retry` (unknown) - `init` (unknown) - `renew` (unknown) - `update` (unknown) - `cancel` (unknown) - `pause` (unknown) - `resume` (unknown) - `pause_schedule.create` (unknown) - `pause_schedule.update` (unknown) - `pause_schedule.delete` (unknown) ## Response 2XX: - `2XX` (unknown) Return any 2XX status to confirm successful data receipt