[Internal] Billing¶

Subscriptions, services, coupons and invoices.

[Internal] Get Subscription¶

GET billing/subscriptions/¶

Note

Authorized Roles: root, manager, backend

Get a subscription.

Response JSON Object

status (string) – Subscription status
description (string) – Description
current_period_start (float) – Current period start timestamp
current_period_end (float) – Current period end timestamp
plans (list-of-object) –
Plans
Inner fields
- id (string) – Plan ID
- description (string) – Description
- unit_amount (float) – Amount per unit (price)
- currency (string) – Currency
- usage_type (string) – Usage type: licenced or metered
- interval (string) – Billing frequency
- interval_count (int) – number of intervals between subscription billings
- tiers (list-of-object) – Tiers
  Inner fields
  
  flat_amount (float) – Flat amount price
  
  unit_amount (float) – Amount price per unit
  
  up_to (float) – The upper bound of the tier
invoice_upcoming (object) –
Invoice upcoming
Inner fields
- email (string) – Email
- name (string) – Name
- number (string) – Number of invoice
- billing_reason (string) – Billing reason
- currency (string) – Currency
- period_start (float) – Period start timestamp
- period_end (float) – Period end timestamp
- total_discount (float) – Total discount
- subtotal (float) – Subtotal
- total (float) – Total
- coupon (object) – Coupon
  Inner fields
  
  id (string) – Coupon ID
  
  valid (bool) – Valid
  
  name (string) – Name
  
  kind (string) – trial_days, percent_off or amount_off
  
  expire (float) – Expire timestamp
  
  duration (string) – once, repeating or forever
  
  duration_in_months (int) – Duration in months
  
  trial_days (int) – Number of trial days. Only when kind=trial_days
  
  amount_off (float) – Amount off. Only when kind=amount_off
  
  percent_off (float) – Percent off. Only when kind=percent_off
  
  currency (string) – Currency. Only when kind=percent_off
- plans (list-of-object) – Plans
  Inner fields
  
  id (string) – Plan ID
  
  description (string) – Description
  
  amount (float) – Amount (price)
  
  usage_type (string) – Usage type: licenced or metered
  
  currency (string) – Currency
  
  quantity (int) – quantity or current period usage
  
  period_start (float) – Period start timestamp
  
  period_end (float) – Period end timestamp
  
  interval (string) – Billing frequency
  
  interval_count (int) – number of intervals between subscription billings
  
  tiers (list-of-object) – Tiers
  
  Inner fields
  
  flat_amount (float) – Flat amount price
  
  unit_amount (float) – Amount price per unit
  
  up_to (float) – The upper bound of the tier
spending_limit (float) – Optional. Spending limit
coupon (object) –
Optional. Coupon
Inner fields
- id (string) – Coupon ID
- valid (bool) – Valid
- name (string) – Name
- kind (string) – trial_days, percent_off or amount_off
- expire (float) – Expire timestamp
- duration (string) – once, repeating or forever
- duration_in_months (int) – Duration in months
- trial_days (int) – Number of trial days. Only when kind=trial_days
- amount_off (float) – Amount off. Only when kind=amount_off
- percent_off (float) – Percent off. Only when kind=percent_off
- currency (string) – Currency. Only when kind=percent_off

EXAMPLE RESPONSE¶

  {
      "status": "active",
      "current_period_start": 1686519299,
      "current_period_end": 1686529299,
      "description": "subscription+desc",
      "spending_limit": 1200.00,
      "plans": [
          {
              "id": "fake+plan+id",
              "description": "plan monthly",
              "currency": "usd",
              "usage_type": "metered",
              "interval": "month",
              "interval_count": 1,
              "unit_amount": 0.3
          }
      ],
      "coupon": {
          "id": "DEMO-COUPON",
          "valid": true,
          "name": "Demo Coupon Name",
          "kind": "percent_off",
          "expire": 1686529299,
          "duration": "once",
          "duration_in_months": 1,
          "percent_off": 30.30
      },
      "invoice_upcoming": {
          "email": "test+email@test.com",
          "name": "customer-name",
          "number": "N-01",
          "billing_reason": "subscription_cycle",
          "currency": "usd",
          "period_start": 1686519299,
          "period_end": 1686529299,
          "total_discount": 10.00,
          "subtotal": 1200.00,
          "total": 1190.00,
          "plans": [
              {
                  "id": "fake+plan+id",
                  "description": "plan+description",
                  "amount": 500.0,
                  "currency": "usd",
                  "usage_type": "metered",
                  "quantity": 73,
                  "period_start": 1686519299,
                  "period_end": 1686529299,
                  "interval": "month",
                  "interval_count": 1
              }
          ],
          "coupon": {
              "id": "DEMO-COUPON",
              "valid": true,
              "name": "Demo Coupon Name",
              "kind": "percent_off",
              "expire": 1686529299,
              "duration": "once",
              "duration_in_months": 1,
              "percent_off": 30.30
          }
      }
  }

[Internal] Partial Update Subscription¶

PATCH billing/subscriptions/¶

Note

Authorized Roles: root, manager, backend

Partial update a subscription.

Request JSON Object

description (string) – Optional. Description
coupon (string) – Optional. Coupon
spending_limit (float) – Optional. Spending limit

EXAMPLE RESPONSE¶

  {
      "description": "new-desc-update",
      "coupon": "DEMO-COUPON"
  }

[Internal] List Invoices¶

GET billing/subscriptions/invoices/¶

Note

Authorized Roles: root, manager, backend

List historical of invoice in a subscription. Results are ordered from newest to oldest.

Query Parameters

amt (int) – Optional. [min: 1] Maximal amount of invoices to return
cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response

EXAMPLE QUERY PARAMS¶

  ?amt=2&cursor=F25pU1vHb1LjSEp...

Response JSON Object

invoices (list-of-object) –
Invoice
Inner fields
- email (string) – Email
- name (string) – Name
- number (string) – Number of invoice
- billing_reason (string) – Billing reason
- currency (string) – Currency
- period_start (float) – Period start timestamp
- period_end (float) – Period end timestamp
- total_discount (float) – Total discount
- subtotal (float) – Subtotal
- total (float) – Total
- coupon (object) – Coupon
  Inner fields
  
  id (string) – Coupon ID
  
  valid (bool) – Valid
  
  name (string) – Name
  
  kind (string) – trial_days, percent_off or amount_off
  
  expire (float) – Expire timestamp
  
  duration (string) – once, repeating or forever
  
  duration_in_months (int) – Duration in months
  
  trial_days (int) – Number of trial days. Only when kind=trial_days
  
  amount_off (float) – Amount off. Only when kind=amount_off
  
  percent_off (float) – Percent off. Only when kind=percent_off
  
  currency (string) – Currency. Only when kind=percent_off
- plans (list-of-object) – Plans
  Inner fields
  
  id (string) – Plan ID
  
  description (string) – Description
  
  amount (float) – Amount (price)
  
  usage_type (string) – Usage type: licenced or metered
  
  currency (string) – Currency
  
  quantity (int) – quantity or current period usage
  
  period_start (float) – Period start timestamp
  
  period_end (float) – Period end timestamp
  
  interval (string) – Billing frequency
  
  interval_count (int) – number of intervals between subscription billings
  
  tiers (list-of-object) – Tiers
  
  Inner fields
  
  flat_amount (float) – Flat amount price
  
  unit_amount (float) – Amount price per unit
  
  up_to (float) – The upper bound of the tier
has_more (bool) – Has more invoices
next_cursor (string) – Next cursor

EXAMPLE RESPONSE¶

  {
      "invoices": [{
          "email": "test+email@test.com",
          "name": "customer-name",
          "number": "N-01",
          "billing_reason": "subscription_cycle",
          "currency": "usd",
          "period_start": 1686519299,
          "period_end": 1686529299,
          "total_discount": 10.00,
          "subtotal": 1200.00,
          "total": 1190.00,
          "plans": [
              {
                  "id": "fake+plan+id",
                  "description": "plan+description",
                  "amount": 500.0,
                  "currency": "usd",
                  "usage_type": "metered",
                  "quantity": 73,
                  "period_start": 1686519299,
                  "period_end": 1686529299,
                  "interval": "month",
                  "interval_count": 1
              }
          ],
          "coupon": {
              "id": "DEMO-COUPON",
              "valid": true,
              "name": "Demo Coupon Name",
              "kind": "percent_off",
              "expire": 1686529299,
              "duration": "once",
              "duration_in_months": 1,
              "percent_off": 30.30
          }
      }],
      "has_more": true,
      "next_cursor": "abc1..."
  }

[Internal] List All Services¶

GET billing/services/¶

Note

Authorized Roles: root, manager, backend

List all services.

Response JSON Object

services (list-of-object) –
Services
Inner fields
- id (string) – Service ID
- name (string) – Service name
- group (string) – Group name
- is_default (bool) – True if the service is default in the group
- description (string) – Description
- plans (list-of-object) – Plans
  Inner fields
  
  id (string) – Plan ID
  
  description (string) – Description
  
  unit_amount (float) – Amount per unit (price)
  
  currency (string) – Currency
  
  usage_type (string) – Usage type: licenced or metered
  
  interval (string) – Billing frequency
  
  interval_count (int) – number of intervals between subscription billings
  
  tiers (list-of-object) – Tiers
  
  Inner fields
  
  flat_amount (float) – Flat amount price
  
  unit_amount (float) – Amount price per unit
  
  up_to (float) – The upper bound of the tier

EXAMPLE RESPONSE¶

  {
      "services": [{
          "id": "demo+product+id",
          "group": "demo+group",
          "is_default": false,
          "name": "Demo Product",
          "description": "demo desc",
          "plans": [
              {
                  "id": "fake+plan+id",
                  "description": "plan monthly",
                  "currency": "usd",
                  "usage_type": "metered",
                  "interval": "month",
                  "interval_count": 1,
                  "unit_amount": 0.3
              }
          ]
      }]
  }

[Internal] Get Coupon¶

GET billing/coupons/<str:coupon>/¶

Note

Authorized Roles: root, manager, backend

Get coupon.

Response JSON Object

id (string) – Coupon ID
valid (bool) – Valid
name (string) – Name
kind (string) – trial_days, percent_off or amount_off
expire (float) – Expire timestamp
duration (string) – once, repeating or forever
duration_in_months (int) – Optional. Duration in months
trial_days (int) – Number of trial days. Only when kind=trial_days
amount_off (float) – Amount off. Only when kind=amount_off
percent_off (float) – Percent off. Only when kind=percent_off
currency (string) – Currency. Only when kind=percent_off

EXAMPLE RESPONSE¶

  {
      "id": "TRIAL-DAYS-7",
      "valid": true,
      "name": "Trial Days 7",
      "kind": "trial_days",
      "expire": 1686529299,
      "duration_in_months": 1,
      "duration": "once",
      "trial_days": 7
  }