Subscriptions
Subscriptions represent a relationship between a customer and your pricing plans. The subscription allows to bill and charge a customer on a recurring basis.
Subscription object
Attribute
id string
The unique object identifier.
customer string
The ID of the customer who will be billed with this subscription.
document string
The ID of the document type for this subscription.
test_mode boolean
Has the value true if the object exists in production mode or the value false if the object exists in test mode.
date_start date
Subscription start date. It can be a present or future date.
end_date date
Subscription termination date computed based on billing cycles.
billing_cycles number
Number of billing cycles for this subscription. If you want to bill a monthly plan for 12 months, billing cycles must be 12. Leave this field null so that the subscription is billed in unlimited cycles.
next_billing date
Date of the next billing cycle.
next_billing_cycle number
Number of the next billing cycle.
previous_billing date
Date of the last billing cycle already billed.
lines array
addons array
coupon string
coupon_redemptions number
Number of times the coupon has been applied to the subscription.
expiration_days number
Days after billing to wait for payment before starting to send automatic payment reminders.
references array
note string
Free note to indicate something on the invoice.
metadata object
An object with key pairs for store custom information about this subscription.
status string
Status of this subscription, one of active, paused, cancelled, finalized.
paused datetime
Subscription pause datetime if the subscription status is paused.
paused_reason string
Subscription pause reason if the subscription status is paused, one of tax_agency_failed.
cancelled datetime
Subscription cancelled datetime if the subscription status is cancelled.
cancel_reason string
Subscription cancel reason if the subscription status is cancelled, one of not_specified, not_paid, no_card, fraud_review_failed, non_compliant_customer.
created datetime
Date and time of the creation of this subscription.
updated datetime
Date and time of the last update of this subscription.
Subscription line object
Attribute
id string
The unique object identifier.
plan string
quantity decimal
Quantity of the plan to be billed.
coupon string
coupon_redemptions number
Number of times the coupon has been applied to the subscription line.
created datetime
Date and time of the creation of this subscription line.
updated datetime
Date and time of the last update of this subscription line.
Subscription addon object
Attribute
id string
The unique object identifier.
addon string
addon_redemptions number
Number of times the addon has been applied to the subscription.
quantity decimal
Quantity of the addon to be billed.
rates array
Subscription addon rate object
Subscription addon rates allows to divide the billing of a addon in multiple shares and determine its billing in specific cycles.
Attribute
billing_cycle number
Number of the billing cycle in which this rate must be invoiced.
percentage decimal
Percentage of the amount of the addon that must be invoiced with this rate.
description string
Free description about the rate to indicate to the customer.
Create a subscription
POST https://api.piriod.com/subscriptions/
Creates a new Subscription object.
Request Body
customer
string
ID of related Customer object.
date_start
string
Date for the start of the subscription. Format YYYY-DD-MM.
document
string
The ID of the document type this subscription should create.
expiration_days
number
Limit days to wait for subscription payment before starting to send payment reminders. Default is 10.
lines
array
A list of Subscription Line objects.
addons
array
A list of Subscription Addon objects.
coupon
string
ID of related Coupon object. Must be compatible with apply_on=subscription.
note
string
A simple text with a 100 characters as max length.
test_mode
boolean
True or false if the subscription is to be created to account test environment. Default is false.
Retrieve a subscription
GET https://api.piriod.com/subscriptions/{id}/
This endpoint retrieves a subscription.
Path Parameters
id
string
The ID of the subscription object.
Update a subscription
PATCH https://api.piriod.com/subscriptions/{id}/
This endpoint updates a subscription.
Path Parameters
id
string
The ID of the subscription object.
Request Body
coupon
string
The ID of the coupon to this subscription.
Destroy a subscription
DELETE https://api.piriod.com/subscriptions/{id}/
Cancel a subscription.
Path Parameters
id
string
The ID of the subscription object.
Query Parameters
cancel_reason_description
string
Reason for cancellation, one of not_specified, not_paid, no_card, fraud_review_failed, non_compliant_customer
Last updated