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…

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

200Success.

400Invalid request.

401Unauthenticated.