Skip to main content
GET
/
subscriptions
/
{id}
Retrieve subscription
curl --request GET \
  --url https://api.piriod.com/subscriptions/{id}/ \
  --header 'Authorization: <api-key>' \
  --header 'x-simple-workspace: <x-simple-workspace>'
{
  "customer": "<string>",
  "document": 123,
  "date_start": "2023-12-25",
  "next_billing": "2023-12-25",
  "lines": [
    {
      "plan": "<string>",
      "quantity": 2,
      "id": "<string>",
      "coupon": "<string>",
      "coupon_redemptions": 123,
      "created": "2023-11-07T05:31:56Z",
      "updated": "2023-11-07T05:31:56Z"
    }
  ],
  "id": "<string>",
  "previous_billing": "2023-12-25",
  "billing_cycles": 123,
  "next_billing_cycle": 1,
  "expiration_days": 10,
  "collection_scheme": "send_invoice",
  "default_source": "<string>",
  "custom_change": 2,
  "coupon": "<string>",
  "coupon_redemptions": 123,
  "require_reference": false,
  "note": "<string>",
  "orgunit": 123,
  "status_description": "<string>",
  "needs_attention": "2023-11-07T05:31:56Z",
  "cancelled": "2023-11-07T05:31:56Z",
  "paused": "2023-11-07T05:31:56Z",
  "pause_until": "2023-12-25",
  "addons": [
    {
      "addon": "<string>",
      "quantity": 2,
      "addon_redemptions": 123,
      "rates": [
        {
          "billing_cycle": 123,
          "percentage": 123,
          "description": "<string>"
        }
      ]
    }
  ],
  "references": [
    {
      "date": "2023-12-25",
      "document": "<string>",
      "serial": "<string>",
      "date_end": "2023-12-25",
      "description": "<string>"
    }
  ],
  "test_mode": true,
  "created": "2023-11-07T05:31:56Z",
  "updated": "2023-11-07T05:31:56Z"
}

Authorizations

​
Authorization
string
header
required

Use header Authorization: Token <api_token>. API tokens are obtained from the Piriod dashboard.

Headers

​
x-simple-workspace
string
required

Workspace (account) identifier. Required for every request.

​
x-piriod-test-mode
boolean
default:false

Whether to operate against test-mode data. Defaults to false.

Path Parameters

​
id
string
required

Resource identifier.

Response

The subscription.

​
customer
string
required

Customer ID.

​
document
integer
required

Document type ID used to issue invoices.

​
date_start
string<date>
required
​
next_billing
string<date>
required
​
lines
object[]
required
​
id
string
read-only
​
previous_billing
string<date> | null
​
billing_cycles
integer | null

Total cycles or null for indefinite.

​
next_billing_cycle
integer
default:1
read-only
​
expiration_days
integer
default:10

Days until invoices generated by this subscription expire.

​
collection_scheme
enum<string>
default:send_invoice
Available options:
send_invoice,
charge_payment
​
default_source
string | null

Default payment source ID. Required when collection_scheme=charge_payment.

​
custom_change
number | null

Custom currency conversion factor for issued invoices.

Required range: x >= 1
​
coupon
string | null

Coupon ID applied at the subscription (invoice-level) scope.

​
coupon_redemptions
integer
read-only
​
require_reference
boolean
default:false
​
note
string | null
Maximum string length: 100
​
orgunit
integer | null
​
status
enum<string>
read-only
Available options:
active,
paused,
cancelled,
finalized,
needs_attention
​
status_description
string | null
Maximum string length: 512
​
needs_attention
string<date-time> | null
read-only
​
needs_attention_reason
enum<string> | null
read-only
Available options:
biller_issue,
gateway_issue,
reference_expired,
without_usage_records,
processing_issue,
without_reference
​
cancel_reason
enum<string> | null
read-only
Available options:
custom,
fraud_review_failed,
insolvency,
no_card,
non_compliant_customer,
not_paid,
not_specified,
shutdown_ops
​
cancelled
string<date-time> | null
read-only
​
paused
string<date-time> | null
read-only
​
paused_reason
enum<string> | null
read-only
Available options:
not_specified,
non_compliant_customer,
custom
​
pause_until
string<date> | null
read-only
​
addons
object[]
​
references
object[]
​
test_mode
boolean
read-only
​
created
string<date-time>
read-only
​
updated
string<date-time>
read-only