Retrieve subscription

GET /subscriptions/{id}

Retrieve subscription

cURL

curl --request GET \
  --url https://api.piriod.com/subscriptions/{id}/ \
  --header 'Authorization: <api-key>' \
  --header 'x-simple-workspace: <x-simple-workspace>'

200

{
  "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": "active",
  "status_description": "<string>",
  "needs_attention": "2023-11-07T05:31:56Z",
  "needs_attention_reason": "biller_issue",
  "cancel_reason": "custom",
  "cancelled": "2023-11-07T05:31:56Z",
  "paused": "2023-11-07T05:31:56Z",
  "paused_reason": "not_specified",
  "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

200

application/json

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

Show child attributes

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[]

Show child attributes

references · object[]

Show child attributes

test_mode · boolean · read-only

created · string<date-time> · read-only

updated · string<date-time> · read-only