JSON API » plans » plans/create

Creates a new rate plan.

Input parameters

Requires authentication and the commerce role privilege.

Name	Type	Description	Required	Default value
auth_username	String	Authentication username.	Yes
auth_password	String	Authentication password.	Yes
name	String	Name.	Yes
auto_topup	Decimal	The balance to top up to when doing an automatic topup.	No	0.00
bill_defer	Integer	1 to defer billing of features until start of next billing period, 0 not to.	No	0
bill_type	String	Billing type. "external", "none", "prepaid", "prepaid_invoices", "prepaid_calls", or "postpaid".	No	"prepaid"
bulk_calls	Integer	Maximum concurrent bulk dialler calls. -1 for default limit.	No	-1
call_maximum	Decimal	Maximum spending on calls per customer per day. -1 for no limit.	No	-1
callerid_in_external	Integer	1 to pass callerid from inbound external calls to telephone lines, 0 not to.	No	1
carry_forward_messages	Integer	1 to carry forward unused messages for one billing period, 0 not to.	No	0
carry_forward_seconds	Integer	1 to carry forward unused call seconds for one billing period, 0 not to.	No	0
conference_calls	Integer	Maximum concurrent conference calls. -1 for no limit.	No	-1
contract	String	Minimum contract length. "1_month", "3_month", "6_month", "1_year", "18_month", "2_year", "3_year", or empty string for none.	No	Empty string.
cos_timegroup	Integer	ID of time group for class of service. 0 for none.	No	0
currency	String	Currency costs are in.	No	System currency.
customer	Integer	ID of customer to create in.	No	Customer of authentication user.
description	String	Description.	No	Empty string.
dialplan	String	Dial plan for the rate plan. Empty string for default.	No	Empty string
external_out	Integer	1 to allow external calls by default, 0 not to.	No	1
huntgroup_dests	Integer	Maximum destinations per hunt group. -1 for no limit.	No	-1
included_messages	Integer	Number of messages included free each billing period.	No	0
included_seconds	Integer	Number of calls seconds included free each billing period.	No	0
inconnect_margin	Decimal	Profit margin to add to inbound connect fee after markup.	No	0.00
inconnect_markup	Integer	Percentage markup on inbound connect fee.	No	0
incost_margin	Decimal	Profit margin to add to inbound per-minute cost after markup.	No	0.00
incost_markup	Integer	Percentage markup on inbound per-minute cost.	No	0
inheritable	Integer	1 to allow resellers to inherit their plans from this plan, 0 not to.	No	0
inmaximum	Integer	Maximum concurrent inbound calls. -1 for no limit.	No	-1
inmessage_margin	Decimal	Profit margin to add to inbound messages after markup.	No	0.00
inmessage_markup	Integer	Percentage markup on inbound messages.	No	0
inmessage_media_margin	Decimal	Profit margin to add to inbound media messages after markup.	No	0.00
inmessage_media_markup	Integer	Percentage markup on inbound media messages.	No	0
internal_out	Integer	1 to allow internal calls by default, 0 not to.	No	1
invoices	String	Whether to send invoices. "customer", "parent", "queue", or empty string for no invoices.	No	"customer"
invoices_due	Integer	The number of days after issue that invoices become due. 0 for immediate. -1 for manual.	No	0
invoices_overdue	Integer	The number of days after invoices become due that they become overdue. -1 for manual.	No	-1
invoice_detail	String	What detail to include on invoices. "summary", "transactions", "cdrs", "direction_cdrs", "group_cdrs", "source_cdrs", "group_transactions", "group_transactions_cdrs", "group_transactions_direction_cdrs", "group_transactions_group_cdrs", "group_transactions_source_cdrs", "transactions_cdrs", "transactions_direction_cdrs", "transactions_group_cdrs", or "transactions_source_cdrs".	No	"transactions_cdrs"
invoice_format	String	Format invoices are sent in. "pdf" or "xml".	No	"pdf"
low_balance	Decimal	The balance to trigger an automatic topup at.	No	0.00
maxmsg	Integer	Maximum messages per mailbox.	No	1000
maxsecs	Integer	Maximum message duration in seconds.	No	300
outconnect_margin	Decimal	Profit margin to add to outbound connect fee after markup.	No	0.00
outconnect_markup	Integer	Percentage markup on outbound connect fee.	No	0
outcost_margin	Decimal	Profit margin to add to outbound per-minute cost after markup.	No	0.00
outcost_markup	Integer	Percentage markup on outbound per-minute cost.	No	0
outmaximum	Integer	Maximum concurrent outbound calls. -1 for no limit.	No	-1
outmessage_margin	Decimal	Profit margin to add to outbound messages after markup.	No	0.00
outmessage_markup	Integer	Percentage markup on outbound messages.	No	0
outmessage_media_margin	Decimal	Profit margin to add to outbound media messages after markup.	No	0.00
outmessage_media_markup	Integer	Percentage markup on outbound media messages.	No	0
overmax	Integer	1 to allow customers to go over maximum calls, 0 to reject calls.	No	0
pagegroup_dests	Integer	Maximum destinations per page group. -1 for no limit.	No	-1
parent	Integer	ID the plan inherits settings from. 0 for no parent.	No	0
payment_type	String	Payment type on signup. "creditcard", "direct_debit", "external", or "none".	No	"creditcard"
peer1	Integer	ID of peer to send all outbound calls to. 0 to use routing exceptions.	No	0
period	String	Billing period. "daily", "weekly", "monthly", "2_monthly", "3_monthly", "6_monthly", "annually", or empty string for indefinite.	No	"monthly"
period_start	String	When the billing period starts. "start" or "exact".	No	"start"
person_role	Integer	ID of the first person's role on signup.	No	0
purge_messages	String	When to purge mailbox messages. "1_day", "1_week", "1_month", "3_months", "6_months", "1_year", or empty string for never.	No	Empty string.
queue_calls	Integer	Maximum concurrent queue calls. -1 for no limit.	No	-1
queue_dests	Integer	Maximum destinations per queue. -1 for no limit.	No	-1
record_maximum	Integer	Maximum number of seconds of recordings to keep. -1 for unlimited.	No	-1
require_tax_number	Integer	1 to require tax number in signup, 0 not to.	No	0
rounding	Integer	Number of digits to round call prices to, from 0 to 6.	No	6
service_call_locked	Integer	1 to forward calls to customer service if customer is locked, 0 not to.	No	0
service_copy	Integer	1 to copy customer service on emails to customers, 0 not to.	No	0
service_email	String	Customer service email address. Empty string for none.	No	Empty string.
service_telephone	String	Customer service telephone number. Empty string for none.	No	Empty string.
signup_topup	Integer	1 to attempt to topup the customer's account on signup. 0 not to.	No	0
shared	Integer	Whether the plan is shared. "resellers", "resellers_recursive", or empty string not to share.	No	Empty string.
totalmaximum	Integer	Maximum concurrent total calls. -1 for no limit.	No	-1
use_markups	Integer	1 to use markups, 0 to reject calls if this plan has no matching cost exception.	No	1
validation	Integer	1 to validate input then return, 0 for full action.	No	0

Responses

Code	Description
200	Success.
201	Input passed validation. Only returned if validation=1.
400	Invalid input parameters specified. Check the key and message fields for more details.
401	The authentication details provided are invalid.
402	Your role does not allow this.
403	Your rate plan does not allow this.

Data returned

The ID of the created rate plan.

Example: With required parameters

http://enswitch.example.com/api/json/plans/create/?auth_username=user;auth_password=password;name=example

{ "responses":[ { "code":"200", "key":"", "message":"OK" } ], "data":{ "id":123 } }

Change history

Version	Changes
4.2	inmessage_media_margin, inmessage_media_markup, outmessage_media_margin, and outmessage_media_markup input parameters added.
3.15	invoice_detail parameter updated to include grouped transactions. maxsecs input parameter added.
3.14	inconnect, incost, inmessage, outconnect, outcost, and outmessage input parameters renamed to inconnect_markup, incost_markup, inmessage_markup, outconnect_markup, outcost_markup, and outmessage_markup. bulk_calls, conference_calls, huntgroup_dests, inconnect_margin, incost_margin, inmessage_margin, outconnect_margin, outcost_margin, outmessage_margin, pagegroup_dests, queue_calls, and queue_dests input parameters added.
3.13	Function added.