Create Subscription
Create a new subscription with customer information, plan details, and payment method. Supports flexible trial period settings and idempotency guarantees.
subscriptions.write scope.Authorizations
Bearer authentication header in the format `Bearer <token>`, where `<token>` is your authentication token.
Headers
Merchant account ID for this request.
"default"Unique key to ensure request idempotency. If provided, identical requests will not be processed multiple times.
"unique-key-123"Original IP address of the client connecting to the server.
"203.0.113.195"Body
application/jsonMerchant reference identifier for this subscription. Used to identify the subscription in your system.
"subscription-12345"Amount for the first subscription period in cents (smallest currency unit).
"1000""2999"Currency for the first subscription period (ISO 4217 format).
"USD""EUR"Customer information object.
Subscription plan details.
Payment method details. If the merchant does not have PCI compliance, use checkout mode to redirect to the payment page to collect card information.
Billing details for this subscription.Required when `payment_method.payment_channel_code` is "J-Pay"
Array of cart items representing subscription line items. Required when `payment_method.payment_channel_code` is "J-Pay".
Browser information used by the customer. Required for Direct API mode. This can be used for anti-fraud services.
Trial period end time (ISO 8601 format).
"2025-09-01T00:00:00Z"Description of the subscription.
"Premium Plan with trial period"Custom key-value pairs for additional information.
"{"campaign": "summer_promotion", "source": "website"}"Response
Successful Response
Unique subscription identifier.
"sub_0001"Object type, always "subscription".
"subscription"Merchant reference identifier for this subscription.
"subscription-12345"Amount for the first subscription period in cents (smallest currency unit).
"1000"Currency for the first subscription period (ISO 4217 format).
"USD"Subscription creation time (ISO 8601).
"2025-08-12T09:00:00Z"Customer information.
Subscription plan details.
Payment method details.
Subscription status: failed, active, past_due, cancelled.
"failed""active"Current billing period start time.
"2025-08-12T09:00:00Z"Current billing period end time.
"2025-09-12T09:00:00Z"Next billing date (YYYY-MM-DD format).
"2025-09-01"Trial period start time (if applicable).
"2025-08-12T09:00:00Z"Trial period end time (if applicable).
"2025-09-01T00:00:00Z"Custom metadata.
"{}"URL to complete payment for this subscription. Provided when using checkout mode or requiring additional payment steps.
"https://pay.efundpay.com/abc123""null"curl --request POST \--url https://api.efundpay.com/v4/subscriptions \--header 'Authorization: Bearer <token>' \--header 'x-merchant-account-id: <x-merchant-account-id>' \--header 'Content-Type: application/json' \--header 'idempotency-key: unique-key-123' \--header 'X-Forwarded-For: 203.0.113.195' \--data '{"external_identifier": "subscription-12345","amount": 1000,"currency": "USD","customer": {"display_name": "John Doe","external_identifier": "customer-12345","first_name": "John","last_name": "Doe","email_address": "john@example.com","phone_number": "+1234567890","account_number": "123456789"},"plan": {"name": "Basic Monthly","currency": "USD","amount": 1000,"interval": "month","trial_period_days": 14,"billing_cycle_anchor": "immediate","payment_attempts": 3,"interval_time": 3600},"payment_method": {"payment_channel_code": "card","type": "card","redirect_url": "https://example.com","webhooks_url": "https://merchant.com/webhooks/payment"},"cart_items": [{"name": "Premium Plan","description": "Premium subscription plan with advanced features","quantity": 1,"unit_amount": 1000,"discount_amount": 0,"tax_amount": 0,"external_identifier": "premium-plan","sku": "PREMIUM001","product_url": "https://example.com/catalog/premium-plan","image_url": "https://example.com/images/premium-plan.jpg","categories": ["subscription", "premium", "feature"],"product_type": "service"}],"browser_info": {"javascript_enabled": true,"java_enabled": false,"language": "en-US","color_depth": 24,"screen_height": 1080,"screen_width": 1920,"time_zone_offset": -480,"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36","user_device": "desktop","accept_header": "*/*"},"metadata": {"campaign": "summer_promotion","source": "website"},"billing_details": {"first_name": "John","last_name": "Doe","email_address": "john@example.com","phone_number": "+1234567890","address": {"city": "San Jose","country": "US","postal_code": "94560","state": "California","state_code": "US-CA","house_number_or_name": "10","line1": "Stafford Appartments","line2": "29th Street","organization": "EFundFlow"}}}'
{"id": "sub_0001","object": "subscription","external_identifier": "subscription-12345","amount": 1000,"currency": "USD","created": "2025-08-12T09:00:00Z","customer": {"display_name": "John Doe","external_identifier": "customer-12345","first_name": "John","last_name": "Doe","email_address": "john@example.com","phone_number": "+1234567890","account_number": "123456789"},"plan": {"name": "Basic Monthly","currency": "USD","amount": 1000,"interval": "month","trial_period_days": 14,"billing_cycle_anchor": "immediate","payment_attempts": 3,"interval_time": 3600},"payment_method": {"type": "card","card": {"last4": "1111","expiration_date": "12/27"}},"status": "failed","current_period_start": "2025-08-12T09:00:00Z","current_period_end": "2025-09-12T09:00:00Z","next_billing_date": "2025-09-01","trial_start": "2025-08-12T09:00:00Z","trial_end": "2025-09-01T00:00:00Z","metadata": {"campaign": "summer_promotion","source": "website"},"payment_url_link": "https://pay.efundpay.com/abc123"}