# Subscriptions The report offers a comprehensive overview for merchants, detailing customer subscriptions, payment methods, key customer data, and associated invoices, which are important for managing recurring revenues, customer retention, and informed decision-making in subscription-based businesses. The updated_at parameter is used when unloading subscription data, indicating the most recent update to a subscription. Endpoint: POST /subscriptions Version: 1.0.0 Security: MerchantID ## Header parameters: - `merchant` (string, required) Unique public key provided upon registration and must be shared for identification purposes. Example: "api_pk_7b197...ba108f842" - `signature` (string, required) Request signature that allows verification of merchant authenticity on the payment gateway server. Example: "M2E3OTkyNzcz...xMmExODI4" ## Request fields (application/json): - `filter` (string) Filtering criteria for the report data. Enum: "updated_at", "created_at" - `date_from` (string, required) Start datetime for the report stated in UTC+0. Example: "2025-08-15 11:00:00" - `date_to` (string, required) End datetime for the report stated in UTC+0. Example: "2025-08-18 11:00:00" - `limit` (integer) Limit value indicates the maximum number of items to be returned. Example: 2000 - `next_page_iterator` (string) Pagination helps in managing large datasets by dividing them into smaller, manageable chunks. If this value is null, it indicates that all available data has been successfully retrieved by the merchant. Example: "eyJzdWJzY3JpcHRpb25faWQiOiI5ODlkCJkYXRlX3RvIjoiMjAyMC0wOS0xNyAxNDoxMDowMCJ9" ## Response 200 fields (application/json): - `body` (object) — one of: - Success: - `subscriptions` (object, required) Map of subscriptions, including detailed information such as status, payment details, cancellation info, associated customer and product data, invoice history, and pause schedule parameters. - `subscriptions.` (object, required) Details of a subscription, including payment and customer information. - `subscriptions..id` (string, required) Unique subscription identifier. - `subscriptions..status` (string, required) Subscription status. Enum: "active", "cancelled", "redemption", "paused" - `subscriptions..started_at` (string, required) Datetime of the subscription start. - `subscriptions..updated_at` (string, required) Datetime of the subscription update. - `subscriptions..expired_at` (string) Datetime of the subscription expiration. - `subscriptions..next_charge_at` (string) Datetime for the subsequent charge. - `subscriptions..payment_type` (string, required) Customer's payment method used for the subscription payment. Enum: "card", "paypal-vault", "alipay", "gcash", "mbway", "mercadopago", "upi", "wechatpay", "pix" - `subscriptions..trial` (boolean, required) Indicates whether the subscription has a trial. - `subscriptions..cancelled_at` (string) Datetime of subscription cancellation. - `subscriptions..cancel_code` (string) Reason code used to cancel the subscription. Enum: "8.01", "8.02", "8.03", "8.04", "8.05", "8.06", "8.07", "8.08", "8.09", "8.10", "8.11", "8.12", "8.13", "8.14", "8.15" - `subscriptions..cancel_message` (string) Cancellation reason brief description. - `subscriptions..customer` (object, required) Customer details related to the subscription, including key information such as the customer's email address. - `subscriptions..customer.customer_account_id` (string, required) Unique customer identifier defined by the merchant. - `subscriptions..customer.customer_email` (string, required) Customer's email address. - `subscriptions..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 fields of the product creation request. - `subscriptions..product.id` (string, required) Unique product identifier. - `subscriptions..product.name` (string, required) Product name. - `subscriptions..product.payment_action` (string) Specifies a payment flow applied to the first transaction. - `subscriptions..product.amount` (integer, required) Product price. - `subscriptions..product.currency` (string, required) Three-letter ISO-4217 currency code of the product price currency. - `subscriptions..product.trial` (boolean, required) Indicates whether the product has a trial. - `subscriptions..product.trial_period` (integer) Indicates the trial period in minutes. - `subscriptions..invoices` (object, required) Map of invoices, containing details such as a subscription's billing overview, current state, financial information, and associated order history. - `subscriptions..invoices.` (object, required) Single invoice, where `` is a dynamically generated unique invoice identifier. - `subscriptions..invoices..id` (string, required) Unique invoice identifier associated with a specific subscription. - `subscriptions..invoices..status` (string, required) Invoice status. Enum: "processing", "retry", "success", "fail" - `subscriptions..invoices..created_at` (string, required) Datetime of the invoice creation. - `subscriptions..invoices..updated_at` (string, required) Datetime of the invoice update. - `subscriptions..invoices..amount` (integer, required) Current subscription price. - `subscriptions..invoices..billing_period_started_at` (string, required) Start datetime of the period covered by the invoice. Filled if invoice is in the success status. - `subscriptions..invoices..billing_period_ended_at` (string, required) End datetime of the period covered by the invoice. Filled if invoice is in the success status. - `subscriptions..invoices..subscription_term_number` (integer, required) 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 status on or after March 1, 2024, regardless of the invoice status - `subscriptions..invoices..orders` (object, required) Map of orders, including data such as status, creation and processing timestamps, and other transaction details. - `subscriptions..invoices..orders.` (object, required) Single order, where `` is a dynamically generated unique order identifier. - `subscriptions..invoices..orders..id` (string, required) Unique order identifier defined by the merchant, which can be used to find the payment. - `subscriptions..invoices..orders..status` (string, required) Status of the requested order. Card order statuses are created, processing, 3ds_verify, auth_ok, auth_failed, void_ok, settle_ok, and refunded. Card order status partial_settled is not used in subscriptions. APM order statuses are created, processing, approved, declined, and refunded. APM order status settle_pending is not used in subscriptions. Enum: "created", "processing", "3ds_verify", "auth_ok", "auth_failed", "void_ok", "settle_ok", "refunded", "approved", "declined" - `subscriptions..invoices..orders..created_at` (string, required) Datetime of the order creation. - `subscriptions..invoices..orders..processed_at` (string, required) Datetime when the order was processed. - `subscriptions..invoices..orders..amount` (integer, required) Original order amount. - `subscriptions..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. - `subscriptions..invoices..orders..payment_details.invoice_id` (string) Unique invoice identifier provided by PayPal. It is provided only for the transactions with paypal-vault method. - `subscriptions..invoices..orders..payment_details.payer_email` (string) Customer's email. It is provided only for the transactions with paypal-vault method. - `subscriptions..invoices..orders..retry_attempt` (integer, required) Number of retry attempts for the subscription payments. Use it for analytics and conversion tuning purposes. - `subscriptions..invoices..orders..operation` (string) Type of the transaction. Enum: "pay", "recurring", "recurring-auth", "refund", "resign", "resign-auth", "auth", "settle", "void", "apple-pay", "google-pay" - `subscriptions..pause` (object) Pause schedule parameters. - `subscriptions..pause.from_date` (string, required) Pause start date. - `subscriptions..pause.to_date` (string) Pause end date. - `metadata` (object, required) Contains metadata related to the request, particularly for pagination. - `metadata.next_page_iterator` (string, required) To perform pagination in the request body, add the field with the value from the previous response. If this value is null, all data was successfully retrieved by the merchant. - `metadata.count` (integer, required) Number of subscriptions on the page. - Authentication failed: - `error` (object, required) Error object. - `error.code` (string, required) Unauthorized access due to invalid credentials. Example: "1.01" - `error.messages` (array, required) Array of error messages applied to the decline payment. Example: ["Authentication failed"]