Create subscription

post

https://www.pelcro.com/api/v1/core/subscriptions

Create a new subscription.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Overview

Create a new subscription for a customer. Associate them with a plan and optionally apply a coupon or trial period.

Example: A customer selects your Premium Annual plan. Create a subscription with their user_id, plan_id, and source_id to start billing immediately.

Conditional Requirements

Condition	Required Fields
Always	`plan_id` OR `plan_old_provider_id`
Always	`user_id` OR `customer_old_provider_id`
`collection_method=charge_automatically` (default)	`source_id` OR `source_old_provider_id`
`collection_method=send_invoice`	`source_id` is optional
Account has `taxes_enabled=true`	`address_id` OR `address_old_provider_id` required for tax calculation (subscription created without taxes if missing)
Plan's product has `address_required=true` AND customer has no shipping address	`address_id` required
Plan's product has `address_required=true` AND customer has shipping address	`address_id` OR `address_old_provider_id`
`is_gift_donor=true`	`gift_recipient_email`, `gift_recipient_first_name`, `gift_recipient_last_name` allowed
`gift_donor_old_provider_id` OR `gift_donor_subscription_id` is set	Cannot use `is_gift_donor` (mutually exclusive)
`current_period_end` is set	Cannot use `trial_period_days` (mutually exclusive)
`trial_period_days` is set	Cannot use `current_period_end` (mutually exclusive)
`next_invoice_date` is set	`current_period_end` must also be set and have same value
`start_date` is set in the future	`billing_behavior` is required (`bill_immediately` or `bill_on_start_date`)
Both `user_id` AND `customer_old_provider_id` are set	Must reference the same customer
Both `address_id` AND `address_old_provider_id` are set	Must reference the same address
Both `plan_id` AND `plan_old_provider_id` are set	Must reference the same plan
Both `source_id` AND `source_old_provider_id` are set	Must reference the same source
Customer has reached max subscription limit	Request will fail

Webhook

Triggers the subscription.created webhook event.

Query Params

site_id

int32

required

The unique identifier of the site associated with your account.

Body Params

user_id

int32

Customer user ID. Required unless customer_old_provider_id is provided.

plan_id

int32

Plan ID. Required unless plan_old_provider_id is provided.

address_id

int32

Shipping address ID. Required when the plan product has address_required enabled.

source_id

int32

Payment source ID. Required when collection_method is charge_automatically.

auto_renew

boolean

A boolean that determines whether the subscription will auto-renew or not at the end of the last phase. (overrides the plan configuration when set)

campaign_key

string

length ≤ 191

The campaign associated to the subscription. If the key does not already exist, it will be created. The campaign key must be between 3 and 191 characters in length and include only letters, numbers, dashes and underscores without space.

collection_method

string

enum

Defaults to charge_automatically

Payment collection method. Defaults to charge_automatically.

Allowed:

coupon_code

string

Coupon code to apply to the subscription.

current_period_end

int32

A valid Unix timestamp in the future representing the exact time at which the subscription will either renew or cancel, based on the auto-renewal behavior.

domains

array of strings

Email domains that will allow end-users with these domains to be members of this subscription upon registration/login. It can only be sent when the subscription plan type is membership.

domains

metadata

array of objects

Set of key-value pairs that can be saved on subscription level. This can be useful for storing additional information about the object in a structured format.

metadata

quantity

int32

required

1 to 100000

Subscription quantity (1–100,000).

shipments_remaining

int32

An integer indicating the number of shipments remaining for the subscription.

shipments_undeliverable

boolean

Whether shipments for this subscription are undeliverable.

shipments_suspended_until

int32

A valid Unix timestamp in the future to set the exact time until the subscription's shipments should be suspended.

source

string

required

length ≤ 255

Acquisition source label (e.g. api, web, phone). Free text, max 255 characters.

trial_period_days

int32

≤ 730

Trial period in days (0–730). Mutually exclusive with current_period_end.

is_imported

boolean

Whether the subscription is imported from another system.

is_gift_donor

boolean

Create as a gift donor subscription. Mutually exclusive with gift_donor_subscription_id. Requires gift_recipient_email, gift_recipient_first_name, gift_recipient_last_name.

ip_addresses

array of strings

IP addresses that will identify end-users as members of this subscription upon registration/login. This attribute can only be set when the subscription plan type is membership. Two format are accepted for strings:

A single public IP address
This should be a valid public IP address following the standard IPv4 format (e.g., 192.168.1.100).

A range of public IP addresses
This should be a range of public IP addresses following the CIDR notation (e.g., 198.51.100.0/24).

You can use this tool calculate the appropriate CIDR notation for your needs.

ip_addresses

gift_start_date

date

Gift start date in YYYY-MM-DD format. Must be within one year. Only when is_gift_donor is true.

gift_recipient_email

string

length ≤ 255

Gift recipient email address. Required when is_gift_donor is true.

gift_recipient_first_name

string

length ≤ 255

Gift recipient first name. Required when is_gift_donor is true.

gift_recipient_last_name

string

length ≤ 255

Gift recipient last name. Required when is_gift_donor is true.

gift_message

string

length ≤ 200

Gift message included with the gift notification (max 200 characters). Only when is_gift_donor is true.

gift_donor_subscription_id

int32

Donor subscription ID when creating a gift recipient subscription. Mutually exclusive with is_gift_donor.

old_provider_id

string

length ≤ 191

External provider ID for imported subscriptions. Must be unique per account. Max 191 characters.

gift_donor_old_provider_id

string

length ≤ 191

Import alias for gift_donor_subscription_id. Resolves by old_provider_id on the donor subscription. Max 191 characters.

next_invoice_date

integer

Unix timestamp for next invoice date. Must equal current_period_end. Prohibited when current_period_end is not set.

customer_old_provider_id

string

length ≤ 255

Import alias for user_id. Resolves by old_provider_id on the customer.

address_old_provider_id

string

length ≤ 255

Import alias for address_id. Resolves by old_provider_id on the address.

plan_old_provider_id

string

length ≤ 255

Import alias for plan_id. Resolves by import_unique_id on the plan.

start_date

int64

Unix timestamp for subscription start date. When set in the future, subscription starts as scheduled. Pelcro Billing Engine accounts only.

billing_behavior

string | null

enum

Billing behavior when start_date is in the future. Required when start_date is a future date.

Allowed:

source_old_provider_id

string | null

Import alias for source_id. Resolves to source_id by matching old_provider_id on the payment source. Use this instead of source_id when importing from another system.

recommended_plan_id

integer | null

ID of a recommended plan for upsell suggestions. Must be a valid, non-expired plan on the same account.

vendor_tip_amount

integer | null

≥ 0

Tip amount for vendor-associated subscriptions. Minimum 0.

Headers

Authorization

string

required

Defaults to Bearer eyJ***

Responses

Overview

Conditional Requirements

Webhook

200Success.

400Invalid request.

401Unauthenticated.