PUT
/
billing_templates
/
{id}
/

Authorizations

Authorization
string
headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id
string
required

Object ID (UUID)

Body

application/json
purchase
object
required

Core information about the Purchase, including the products, total, currency and invoice fields. If you're using invoicing via /billing/ or /billing_templates/, this object will be copied 1:1 from BillingTemplate you specify to the resulting Purchases (also to subscription Purchases).

brand_id
string

ID of the brand to create this BillingTemplate for. You can copy it down in the API section, see the "specify the ID of the Brand" link in answer to "How to setup payments on website or in mobile app?".

title
string
is_subscription
boolean
required

Defines whether this BillingTemplate issues invoices in a recurring manner - it's a subscription - or it sends invoices only once. You can't change this parameter when you edit the BillingTemplate. If this field is true, you will need to specify subscription_* fields and invoice_* fields are read-only, and vice-versa.

invoice_issued
string

Sets issued on the Purchase objects generated. Generated from current day in purchase.timezone if not provided. Read-only if is_subscription == true.

invoice_due
integer

Sets due on the Purchase objects generated. Required if is_subscription == false, read-only otherwise.

invoice_skip_capture
boolean
default: false

Sets skip_capture on the Purchase objects generated. false by default. Read-only if is_subscription == true.

invoice_send_receipt
boolean
default: false

Sets send_receipt on the Purchase objects generated. true by default (unlike in Purchases API, where by default receipts are not sent). Read-only if is_subscription == true.

subscription_period
integer
default: 1

Defines how often are the subscription Purchases generated. Used together with subscription_period_units: to issue Purchases once a month, use "...period": 1 and "...period_units" == "months".

Variable number of days in a month is respected; e.g. if subscription has a period of 1 month, a client had its billing cycle activated on January 30 and there are 28 days in February that year - billing scheduled for February will happen on 28th.

Both fields are required when creating a BillingTemplate with is_subscription == true/editing a BillingTemplate with is_subscription == true as long as there aren't any launched subscribers; they are read-only otherwise, whether it's BillingTemplate's editing when there already are clients activated or if is_subscription == false.

subscription_period_units
enum<string>
default: months

See subscription_period.

Available options:
days,
weeks,
months
subscription_due_period
integer
default: 7

Used to generate due on the Purchase objects generated. Used together with subscription_due_period_units: to set the final Purchase.due to a week after it's generated/invoice is sent, use "...period": 1 and "...period_units" == "weeks". Required if is_subscription == true`, read-only otherwise.

subscription_due_period_units
enum<string>
default: days

See subscription_due_period.

Available options:
days,
weeks,
months
subscription_charge_period_end
boolean
default: false

If this is true, clients are charged at the end of billing periods, and vice-versa. E.g. if you add a subscriber client to a BillingTemplate, with this value being set to false, he will receive first invoice today, otherwise - after a single billing period (defined by subscription_period/subscription_period_units) passes.

Required when creating a BillingTemplate with is_subscription == true/editing a BillingTemplate with is_subscription == true as long as there aren't any launched subscribers; read-only otherwise, whether it's BillingTemplate's editing when there already are clients activated or if is_subscription == false.

subscription_trial_periods
integer
default: 0

How many trial periods to give the client prior to starting his billing cycle. If billing period is 1 month and you set this value to 2, subscription will automatically adjust to giving your client 2 months without payments and then charging him for the 3rd month (when exactly depends on subscription_charge_period_end: 3 months after the subscriber was launched for false, 4 for true). "subscription_trial_periods": 0 disables this feature.

Required when creating a BillingTemplate with is_subscription == true/editing a BillingTemplate with is_subscription == true as long as there aren't any launched subscribers; read-only otherwise, whether it's BillingTemplate's editing when there already are clients activated or if is_subscription == false.

subscription_active
boolean
default: false

Whether this subscription is paused. Has the same effect as setting "status": "subscription_paused" for every BillingTemplateClient launched for this subscription, see the description of status on BillingTemplateClient for more details.

Ignored (read-only) if is_subscription == false.

force_recurring
boolean
default: false

If the used payment method supports recurring payment functionality, forces the customer's payment credentials to be saved for possible later recurring payments, without giving the customer a choice in the matter.

Response

200 - application/json
type
string

Object type identifier

id
string
created_on
integer

Object creation time

updated_on
integer

Object last modification time

purchase
object
required

Core information about the Purchase, including the products, total, currency and invoice fields. If you're using invoicing via /billing/ or /billing_templates/, this object will be copied 1:1 from BillingTemplate you specify to the resulting Purchases (also to subscription Purchases).

company_id
string
is_test
boolean

Indicates this is a test object, created using test API keys or using Billing section of UI while in test mode.

user_id
string | null

ID of user who has created this object in the Billing UI, if applicable.

brand_id
string

ID of the brand to create this BillingTemplate for. You can copy it down in the API section, see the "specify the ID of the Brand" link in answer to "How to setup payments on website or in mobile app?".

title
string
is_subscription
boolean
required

Defines whether this BillingTemplate issues invoices in a recurring manner - it's a subscription - or it sends invoices only once. You can't change this parameter when you edit the BillingTemplate. If this field is true, you will need to specify subscription_* fields and invoice_* fields are read-only, and vice-versa.

invoice_issued
string

Sets issued on the Purchase objects generated. Generated from current day in purchase.timezone if not provided. Read-only if is_subscription == true.

invoice_due
integer

Sets due on the Purchase objects generated. Required if is_subscription == false, read-only otherwise.

invoice_skip_capture
boolean
default: false

Sets skip_capture on the Purchase objects generated. false by default. Read-only if is_subscription == true.

invoice_send_receipt
boolean
default: false

Sets send_receipt on the Purchase objects generated. true by default (unlike in Purchases API, where by default receipts are not sent). Read-only if is_subscription == true.

subscription_period
integer
default: 1

Defines how often are the subscription Purchases generated. Used together with subscription_period_units: to issue Purchases once a month, use "...period": 1 and "...period_units" == "months".

Variable number of days in a month is respected; e.g. if subscription has a period of 1 month, a client had its billing cycle activated on January 30 and there are 28 days in February that year - billing scheduled for February will happen on 28th.

Both fields are required when creating a BillingTemplate with is_subscription == true/editing a BillingTemplate with is_subscription == true as long as there aren't any launched subscribers; they are read-only otherwise, whether it's BillingTemplate's editing when there already are clients activated or if is_subscription == false.

subscription_period_units
enum<string>
default: months

See subscription_period.

Available options:
days,
weeks,
months
subscription_due_period
integer
default: 7

Used to generate due on the Purchase objects generated. Used together with subscription_due_period_units: to set the final Purchase.due to a week after it's generated/invoice is sent, use "...period": 1 and "...period_units" == "weeks". Required if is_subscription == true`, read-only otherwise.

subscription_due_period_units
enum<string>
default: days

See subscription_due_period.

Available options:
days,
weeks,
months
subscription_charge_period_end
boolean
default: false

If this is true, clients are charged at the end of billing periods, and vice-versa. E.g. if you add a subscriber client to a BillingTemplate, with this value being set to false, he will receive first invoice today, otherwise - after a single billing period (defined by subscription_period/subscription_period_units) passes.

Required when creating a BillingTemplate with is_subscription == true/editing a BillingTemplate with is_subscription == true as long as there aren't any launched subscribers; read-only otherwise, whether it's BillingTemplate's editing when there already are clients activated or if is_subscription == false.

subscription_trial_periods
integer
default: 0

How many trial periods to give the client prior to starting his billing cycle. If billing period is 1 month and you set this value to 2, subscription will automatically adjust to giving your client 2 months without payments and then charging him for the 3rd month (when exactly depends on subscription_charge_period_end: 3 months after the subscriber was launched for false, 4 for true). "subscription_trial_periods": 0 disables this feature.

Required when creating a BillingTemplate with is_subscription == true/editing a BillingTemplate with is_subscription == true as long as there aren't any launched subscribers; read-only otherwise, whether it's BillingTemplate's editing when there already are clients activated or if is_subscription == false.

subscription_active
boolean
default: false

Whether this subscription is paused. Has the same effect as setting "status": "subscription_paused" for every BillingTemplateClient launched for this subscription, see the description of status on BillingTemplateClient for more details.

Ignored (read-only) if is_subscription == false.

subscription_has_active_clients
boolean

If this is true, there were launched clients (POST /billing_templates/{id}/add_subscriber/ - or subscribers that were added via the gateway system UI) for this subscription.

While this is false (it will be as long as you're only just created the template and haven't launched any subscribers), you can edit all of subscription_* fields.

If this is true, you're only allowed to edit subscription_due_period, subscription_due_period_units and subscription_active.

Is always false if is_subscription == false.

force_recurring
boolean
default: false

If the used payment method supports recurring payment functionality, forces the customer's payment credentials to be saved for possible later recurring payments, without giving the customer a choice in the matter.