API Reference

The djaodjin-saas API is split in four sections: Billing, Subscription, Metrics and Search.

The Billing and Subscription APIs deal with the actual business logic of a Software-as-a-Service, that is the transfer of funds and access control respectively.

The Metrics and Search APIs aggregate the underlying data in various ways to keep on top of the performance of the business as well as provide rich interfaces.

Billing API

These API end points manage the transfer of funds between a subscriber and a provider through a processor.

GET /api/billing/:organization/bank/
class saas.api.backend.RetrieveBankAPIView(**kwargs)

Retrieves a payout account

Pass through that calls the processor API to retrieve some details about the deposit account associated to a provider (if that information is available through the payment processor backend API).

This API does not trigger payment of a subscriber to a provider. Checkout of a subscription cart is done either through the HTML page or API end point.

Examples

GET /api/billing/cowork/bank/ HTTP/1.1

responds

{
  "bank_name": "Stripe Test Bank",
  "last4": "***-htrTZ",
  "balance_amount": 0,
  "balance_unit": "usd"
}
GET /api/billing/:organization/history/
class saas.api.transactions.BillingsAPIView(**kwargs)

Lists subscriber transactions

Queries a page (PAGE_SIZE records) of Transaction associated to {organization} while the organization acts as a subscriber.

The queryset can be filtered to a range of dates ([start_at, ends_at]) and for at least one field to match a search term (q).

Query results can be ordered by natural fields (o) in either ascending or descending order (ot).

This API end point is typically used to display orders, payments and refunds of a subscriber (see subscribers pages)

Tags: billing

Examples

GET /api/billing/xia/history?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc HTTP/1.1

responds

{
    "count": 1,
    "next": null,
    "previous": null,
    "balance": 11000,
    "unit": "usd",
    "results": [
        {
            "created_at": "2015-08-01T00:00:00Z",
            "description": "Charge for 4 periods",
            "amount": "($356.00)",
            "is_debit": true,
            "orig_account": "Liability",
            "orig_organization": "xia",
            "orig_amount": 112120,
            "orig_unit": "usd",
            "dest_account": "Funds",
            "dest_organization": "stripe",
            "dest_amount": 112120,
            "dest_unit": "usd"
        }
    ]
}
GET /api/billing/:organization/card/
class saas.api.backend.PaymentMethodDetailAPIView(**kwargs)

Retrieves a payment method

Pass through to the processor to retrieve some details about the payment method (ex: credit card) associated to a subscriber.

Examples

GET /api/billing/cowork/card/ HTTP/1.1

responds

{
  "last4": "1234",
  "exp_date": "12/2019"
}
GET /api/billing/:organization/balance/
DELETE /api/billing/:organization/balance/
class saas.api.transactions.StatementBalanceAPIView(**kwargs)

Retrieves a customer balance

Get the statement balance due for an organization.

Tags: billing

Examples

GET  /api/billing/cowork/balance/ HTTP/1.1

responds

{
    "balance_amount": "1200",
    "balance_unit": "usd"
}
GET /api/billing/:organization/coupons/
POST /api/billing/:organization/coupons/
class saas.api.coupons.CouponListCreateAPIView(**kwargs)

Lists discount codes

Queries a page (PAGE_SIZE records) of Coupon associated to a provider.

The queryset can be filtered to a range of dates ([start_at, ends_at]) and for at least one field to match a search term (q).

Query results can be ordered by natural fields (o) in either ascending or descending order (ot).

Tags: billing

Examples

GET /api/billing/cowork/coupons?o=code&ot=asc&q=DIS HTTP/1.1

retrieves the list of Coupon for provider cowork where code matches ‘DIS’, ordered by code in ascending order.

responds

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "code": "DIS100",
            "percent": 100,
            "created_at": "2014-01-01T09:00:00Z",
            "ends_at": null,
            "description": null
        },
        {
            "code": "DIS50",
            "percent": 50,
            "created_at": "2014-01-01T09:00:00Z",
            "ends_at": null,
            "description": null
        }
    ]
}
GET /api/billing/:organization/coupons/:coupon/
PUT /api/billing/:organization/coupons/:coupon/
DELETE /api/billing/:organization/coupons/:coupon/
class saas.api.coupons.CouponDetailAPIView(**kwargs)

Retrieves a discount code

Tags: billing

Examples

GET /api/billing/cowork/coupons/DIS100 HTTP/1.1

responds

 {
     "code": "DIS100",
     "percent": 100,
     "created_at": "2014-01-01T09:00:00Z",
     "ends_at": null,
     "description": null
}
GET /api/billing/:organization/receivables/
class saas.api.transactions.ReceivablesListAPIView(**kwargs)

Lists provider receivables

Queries a page (PAGE_SIZE records) of Transaction marked as receivables associated to {organization} while the organization acts as a provider.

The queryset can be filtered to a range of dates ([start_at, ends_at]) and for at least one field to match a search term (q).

Query results can be ordered by natural fields (o) in either ascending or descending order (ot).

This API endpoint is typically used to find all sales for {organization} whether it was paid or not.

Tags: billing

Examples

GET /api/billing/cowork/receivables?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc HTTP/1.1

responds

{
    "count": 1,
    "total": "112120",
    "unit": "usd",
    "next": null,
    "previous": null,
    "results": [
        {
            "created_at": "2015-08-01T00:00:00Z",
            "description": "Charge <a href='/billing/cowork/receipt/1123'>1123</a> distribution for demo562-open-plus",
            "amount": "112120",
            "is_debit": false,
            "orig_account": "Funds",
            "orig_organization": "stripe",
            "orig_amount": 112120,
            "orig_unit": "usd",
            "dest_account": "Funds",
            "dest_organization": "cowork",
            "dest_amount": 112120,
            "dest_unit": "usd"
        }
    ]
}
GET /api/billing/:organization/transfers/
class saas.api.transactions.TransferListAPIView(**kwargs)

Lists provider payouts

Queries a page (PAGE_SIZE records) of Transaction associated to {organization} while the organization acts as a provider.

The queryset can be filtered to a range of dates ([start_at, ends_at]) and for at least one field to match a search term (q).

Query results can be ordered by natural fields (o) in either ascending or descending order (ot).

This API endpoint is typically used to find sales, payments, refunds and bank deposits for a provider. (see provider pages)

Tags: billing

Examples

GET /api/billing/cowork/transfers?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc HTTP/1.1

responds

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "created_at": "2015-08-01T00:00:00Z",
            "description": "Charge <a href='/billing/cowork/receipt/1123'>1123</a> distribution for demo562-open-plus",
            "amount": "$1121.20",
            "is_debit": false,
            "orig_account": "Funds",
            "orig_organization": "stripe",
            "orig_amount": 112120,
            "orig_unit": "usd",
            "dest_account": "Funds",
            "dest_organization": "cowork",
            "dest_amount": 112120,
            "dest_unit": "usd"
        }
    ]
}
GET /api/billing/transactions/
class saas.api.transactions.TransactionListAPIView(**kwargs)

Lists ledger transactions

Queries a page (PAGE_SIZE records) of Transaction from the ledger.

The queryset can be filtered to a range of dates ([start_at, ends_at]) and for at least one field to match a search term (q).

Query results can be ordered by natural fields (o) in either ascending or descending order (ot).

Tags: billing

Examples

GET /api/billing/transactions?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc HTTP/1.1

responds

{
    "ends_at": "2017-03-30T18:10:12.962859Z",
    "balance": 11000,
    "unit": "usd",
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "created_at": "2017-02-01T00:00:00Z",
            "description": "Charge for 4 periods",
            "amount": "($356.00)",
            "is_debit": true,
            "orig_account": "Liability",
            "orig_organization": "xia",
            "orig_amount": 112120,
            "orig_unit": "usd",
            "dest_account": "Funds",
            "dest_organization": "stripe",
            "dest_amount": 112120,
            "dest_unit": "usd"
        }
    ]
}
GET /api/billing/charges/
class saas.api.charges.ChargeListAPIView(**kwargs)

Lists processor charges

Queries a page (PAGE_SIZE records) of Charge that were created on the processor.

The queryset can be filtered to a range of dates ([start_at, ends_at]) and for at least one field to match a search term (q).

Query results can be ordered by natural fields (o) in either ascending or descending order (ot).

Tags: billing

Examples

GET /api/billing/charges?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc HTTP/1.1

Retrieves the list of charges that were created before 2015-07-05T07:00:00.000Z, sort them by date in descending order.

responds

{
    "count": 1,
    "unit": "usd",
    "total": "112120",
    "next": null,
    "previous": null,
    "results": [{
        "created_at": "2016-01-01T00:00:02Z",
        "readable_amount": "$1121.20",
        "amount": 112120,
        "unit": "usd",
        "description": "Charge for subscription to cowork open-space",
        "last4": "1234",
        "exp_date": "2016-06-01",
        "processor_key": "ch_XAb124EF",
        "state": "DONE"
    }]
}
GET /api/billing/charges/:charge/
class saas.api.charges.ChargeResourceView(**kwargs)

Retrieves a single processor charge

Pass through to the processor and returns details about a Charge.

Tags: billing

Examples

GET /api/billing/charges/ch_XAb124EF/ HTTP/1.1

responds

{
    "created_at": "2016-01-01T00:00:01Z",
    "readable_amount": "$1121.20",
    "amount": 112120,
    "unit": "usd",
    "description": "Charge for subscription to cowork open-space",
    "last4": "1234",
    "exp_date": "2016-06-01",
    "processor_key": "ch_XAb124EF",
    "state": "DONE"
}
POST /api/billing/charges/:charge/email/
class saas.api.charges.EmailChargeReceiptAPIView(**kwargs)

Re-sends a charge receipt

Email the charge receipt to the customer email address on file.

The service sends a duplicate e-mail receipt for charge ch_XAb124EF to the e-mail address of the customer, i.e. joe@localhost.localdomain.

Tags: billing

Examples

POST /api/billing/charges/ch_XAb124EF/email/  HTTP/1.1

responds

{
    "charge_id": "ch_XAb124EF",
    "email": "joe@localhost.localdomain"
}
POST /api/billing/charges/:charge/refund/
class saas.api.charges.ChargeRefundAPIView(**kwargs)

Refunds a processor charge

Partially or totally refund all or a subset of line items on a Charge.

Tags: billing

Examples

POST /api/billing/charges/ch_XAb124EF/refund/ HTTP/1.1
{
    "lines": [
      {
          "num": 0,
          "refunded_amount": 4000
      },
      {
          "num": 1,
          "refunded_amount": 82120
      }
  ]
}

Refunds $40 and $821.20 from first and second line item on the receipt respectively. The API call responds with the Charge.

responds

{
    "created_at": "2016-01-01T00:00:05Z",
    "readable_amount": "$1121.20",
    "amount": 112120,
    "unit": "usd",
    "description": "Charge for subscription to cowork open-space",
    "last4": "1234",
    "exp_date": "2016-06-01",
    "processor_key": "ch_XAb124EF",
    "state": "DONE"
}
POST /api/cart/
class saas.api.billing.CartItemAPIView(**kwargs)

Adds an item into a cart

Adds a Plan into the cart of the request.user.

The cart can later be checked out and paid by an Organization, either through the HTML page or API end point.

This end point is typically used when a user is presented with a list of add-ons that she can subscribes to in one checkout screen. The end-point works in both cases, authenticated or anonymous users. For authenticated users, the cart is stored in the database as CartItem objects. For anonymous users, the cart is stored in an HTTP Cookie.

The end-point accepts a single item or a list of items.

quantity is optional. When it is not specified, subsquent checkout screens will provide choices to pay multiple periods in advance When additional full_name, email and sync_on are specified, payment can be made by one Organization for another Organization to be subscribed (see GroupBuy orders).

option is optional. When it is not specified, subsquent checkout screens will provide choices to pay multiple periods in advance When additional full_name and sync_on are specified, payment can be made by one Organization for another Organization to be subscribed (see GroupBuy orders).

Tags: billing

Examples

POST /api/cart/ HTTP/1.1
{
    "plan": "open-space",
    "option": 1
}

responds

{
    "plan": "open-space",
    "option": 1
}
POST /api/cart/redeem/
class saas.api.billing.CouponRedeemAPIView(**kwargs)

Redeems a discount code

Redeems a Coupon and applies the discount to the eligible items in the cart.

Tags: billing

Examples

POST /api/redeem HTTP/1.1
{
    "code": "LABORDAY"
}

responds

{
    "details": "Coupon 'LABORDAY' was successfully applied."
}
DELETE /api/cart/:plan/upload/
class saas.api.billing.CartItemUploadAPIView(**kwargs)

Uploads multiple discount codes into a cart

Add a Plan into the subscription cart of multiple users as per the content of an uploaded file.

This works bulk fashion of /cart/ endpoint. The uploaded file must be a CSV containing the fields first_name, last_name and email. The CSV file must not contain a header line, only data.

Tags: billing

Examples

Content of names.csv:

Joe,Smith,joesmith@example.com
Marie,Johnson,mariejohnson@example.com
POST /api/cart/basic/upload/ HTTP/1.1

Content-Disposition: form-data; name="file"; filename="names.csv"
Content-Type: text/csv

responds

{
    "created": [
        {
            "first_name": "Joe",
            "last_name": "Smith",
            "email": "joesmith@example.com"
        },
        {
            "first_name": "Marie",
            "last_name": "Johnson",
            "email": "mariejohnson@example.com"
        }
    ],
    "updated": [],
    "failed": []
}
POST /api/billing/:organization/checkout
class saas.api.billing.CheckoutAPIView(**kwargs)

Retrieves a user cart for checkout

Get a list indexed by plans of items that will be charged (lines) and options that could be charged instead.

In many subscription businesses, it is possible to buy multiple period in advance at a discount. The options reflects that.

Tags: billing

Examples

GET /api/billing/xia/checkout HTTP/1.1

responds

{"items":
[{
  "subscription":{
      "created_at":"2016-06-21T23:24:09.242925Z",
      "ends_at":"2016-10-21T23:24:09.229768Z",
      "description":null,
      "organization":{
          "slug":"xia",
          "full_name":"Xia",
          "printable_name":"Xia",
          "created_at":"2012-08-14T23:16:55Z",
          "email":"xia@localhost.localdomain"
      },
      "plan":{
          "slug": "basic",
          "title": "Basic",
          "description": "Basic Plan",
          "is_active": true,
          "setup_amount": 0,
          "period_amount": 2000,
          "period_type": "monthly",
          "app_url":"/app/"
      },
      "auto_renew":true
  },
  "lines":[{
      "created_at":"2016-06-21T23:42:13.863739Z",
      "description":"Subscription to basic until 2016/11/21 (1 month)",
      "amount":"$20.00",
      "is_debit":false,
      "orig_account":"Receivable",
      "orig_organization":"cowork",
      "orig_amount":2000,
      "orig_unit":"usd",
      "dest_account":"Payable",
      "dest_organization":"xia",
      "dest_amount":2000,
      "dest_unit":"usd"
  }],
  "options":[]
}]
}

Subscription API

These API end points manage the subscription logic, payments excluded.

GET /api/profile/:organization/plans/
POST /api/profile/:organization/plans/
class saas.api.plans.PlanListCreateAPIView(**kwargs)

Lists a provider plans

Returns a PAGE_SIZE list of plans whose provider is {organization}.

Tags: subscriptions

Examples

GET /api/profile/cowork/plans HTTP/1.1

responds

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [{
    "slug": "managed",
    "title": "Managed",
    "description": "Ideal for growing organizations",
    "is_active": true,
    "setup_amount": 0,
    "period_amount": 2900,
    "period_length": 1,
    "period_type": "monthly",
    "advance_discount": 0,
    "unit": "usd",
    "is_not_priced": false,
    "renewal_type": "auto-renew",
    "created_at": "2019-01-01T00:00:00Z",
    "organization": "cowork",
    "extra": null,
    "skip_optin_on_grant": false,
    "optin_on_request": false
  }]
}
GET /api/profile/:organization/plans/:plan/
PUT /api/profile/:organization/plans/:plan/
DELETE /api/profile/:organization/plans/:plan/
class saas.api.plans.PlanDetailAPIView(**kwargs)

Retrieves a subscription plan

Returns the {plan} for provider {organization}

The is_active boolean is used to activate a plan, enabling users to subscribe to it, or deactivate a plan, disabling users from subscribing to it.

Tags: subscriptions

Examples

GET /api/profile/cowork/plans/open-space HTTP/1.1

responds

{
    "title": "Open Space",
    "description": "A desk in our coworking space",
    "is_active": false,
    "period_amount": 12000,
    "interval": "monthly"
}
GET /api/profile/:organization/plans/:plan/subscriptions/
POST /api/profile/:organization/plans/:plan/subscriptions/
class saas.api.subscriptions.PlanSubscriptionsAPIView(**kwargs)

Lists subscriptions to a plan

Returns a PAGE_SIZE records of subscriptions to {plan} provided by {organization}.

Tags: subscriptions

Examples

GET /api/profile/cowork/plans/premium/subscriptions/ HTTP/1.1

responds

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [{
        "slug": "xia",
        "full_name": "Xia Lee",
        "created_at": "2016-01-14T23:16:55Z",
        "ends_at": "2017-01-14T23:16:55Z"
    }]
}
GET /api/profile/:organization/
PUT /api/profile/:organization/
DELETE /api/profile/:organization/
class saas.api.organizations.OrganizationDetailAPIView(**kwargs)

Retrieves a billing profile

Tags: profile

Examples

GET /api/profile/xia/ HTTP/1.1

responds

{
    "created_at": "2018-01-01T00:00:00Z",
    "email": "xia@locahost.localdomain",
    "full_name": "Xia Lee",
    "printable_name": "Xia Lee",
    "slug": "xia",
    "phone": "555-555-5555",
    "street_address": "185 Berry St #550",
    "locality": "San Francisco",
    "region": "CA",
    "postal_code": "",
    "country": "US",
    "default_timezone": "Europe/Kiev",
    "is_provider": false,
    "is_bulk_buyer": false,
    "type": "",
    "picture": "",
    "subscriptions": [
        {
            "created_at": "2018-01-01T00:00:00Z",
            "ends_at": "2019-01-01T00:00:00Z",
            "plan": "open-space",
            "auto_renew": true
        }
    ]
}
GET /api/users/:user/accessibles/
POST /api/users/:user/accessibles/
class saas.api.roles.AccessibleByListAPIView(**kwargs)

Lists roles by user

Lists all relations where an Organization is accessible by a User. Typically the user was granted specific permissions through a Role.

see Flexible Security Framework.

Tags: rbac

Examples

GET  /api/users/alice/accessibles/ HTTP/1.1

responds

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "slug": "cowork",
            "created_at": "2018-01-01T00:00:00Z",
            "printable_name": "ABC Corp.",
            "email": "help@cowork.net",
            "role_description": {
                "slug": "cowork",
                "created_at": "2018-01-01T00:00:00Z",
                "title": "ABC Corp.",
                "is_global": true,
                "organization": null
            },
            "request_key": null,
            "accept_grant_api_url": null,
            "remove_api_url": "https://cowork.net/api/users/alice/accessibles/manager/cowork",
            "home_url": "https://cowork.net/app/",
            "settings_url": "https://cowork.net/profile/cowork/contact/"
         }
    ]
}
DELETE /api/users/:user/accessibles/:organization/
class saas.api.roles.RoleDetailAPIView(**kwargs)
GET /api/profile/:organization/roles/describe/
POST /api/profile/:organization/roles/describe/
class saas.api.roles.RoleDescriptionListCreateView(**kwargs)

Lists role types

Lists roles by description``RoleDescription``.

see Flexible Security Framework.

Tags: rbac

Examples

GET /api/profile/cowork/roles/describe/ HTTP/1.1

responds

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "created_at": "2018-01-01T00:00:00Z",
            "title": "Managers",
            "slug": "manager",
            "is_global": true,
            "roles": [
                {
                    "created_at": "2018-01-01T00:00:00Z",
                    "user": {
                        "slug": "donny",
                        "email": "donny@localhost.localdomain",
                        "full_name": "Donny Cooper",
                        "created_at": "2018-01-01T00:00:00Z"
                    },
                    "request_key": null,
                    "grant_key": null
                }
            ]
        },
        {
            "created_at": "2018-01-01T00:00:00Z",
            "title": "Contributors",
            "slug": "contributor",
            "is_global": false,
            "roles": []
        }
    ]
}
GET /api/profile/:organization/roles/describe/:role/
PUT /api/profile/:organization/roles/describe/:role/
DELETE /api/profile/:organization/roles/describe/:role/
class saas.api.roles.RoleDescriptionDetailView(**kwargs)

Retrieves a role type

see Flexible Security Framework.

Tags: rbac

Examples

GET /api/profile/cowork/roles/describe/manager HTTP/1.1

responds

{
    "created_at": "2018-01-01T00:00:00Z",
    "slug": "manager",
    "title": "Profile Managers",
    "is_global": true,
    "roles": [
        {
            "created_at": "2018-01-01T00:00:00Z",
            "user": {
                "slug": "donny",
                "email": "donny@localhost.localdomain",
                "full_name": "Donny Cooper",
                "created_at": "2018-01-01T00:00:00Z"
            },
            "request_key": null,
            "grant_key": null
        }
    ]
}
GET /api/profile/:organization/roles/:role/
POST /api/profile/:organization/roles/:role/
class saas.api.roles.RoleListAPIView(**kwargs)

Lists roles for an organization

Tags: rbac

Examples

GET /api/profile/cowork/roles/ HTTP/1.1

responds

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "created_at": "2018-01-01T00:00:00Z",
            "role_description": {
                "name": "Manager",
                "slug": "manager",
                "organization": {
                    "slug": "cowork",
                    "full_name": "ABC Corp.",
                    "printable_name": "ABC Corp.",
                    "created_at": "2018-01-01T00:00:00Z",
                    "email": "support@localhost.localdomain"
                }
            },
            "user": {
                "slug": "alice",
                "email": "alice@localhost.localdomain",
                "full_name": "Alice Doe",
                "created_at": "2018-01-01T00:00:00Z"
            },
            "request_key": "1",
            "grant_key": null
        }
    ]
}
DELETE /api/profile/:organization/roles/:role/:user/
class saas.api.roles.RoleDetailAPIView(**kwargs)
GET /api/profile/:organization/subscribers/
class saas.api.organizations.SubscribersAPIView(**kwargs)

Lists subscribers for a provider

Returns a PAGE_SIZE list of subscriber profiles which have or had a subscription to a plan provided by {organization}.

Tags: subscriptions

Examples

GET /api/profile/cowork/subscribers/?o=created_at&ot=desc HTTP/1.1

responds

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
        "slug": "xia",
        "full_name": "Xia Lee",
        "email": "xia@localhost.localdomain",
        "created_at": "2016-01-14T23:16:55Z",
        "ends_at": "2017-01-14T23:16:55Z"
        }
    ]
}
GET /api/profile/:organization/subscriptions/
class saas.api.subscriptions.SubscriberSubscriptionListAPIView(**kwargs)

Lists subscriptions

Returns a PAGE_SIZE list of subscriptions past and present for subscriber {organization}.

The queryset can be further refined to match a search filter (q) and sorted on specific fields (o).

Tags: subscriptions

Examples

GET /api/profile/cowork/subscriptions/?o=created_at&ot=desc HTTP/1.1

responds

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "created_at": "2016-01-14T23:16:55Z",
            "ends_at": "2017-01-14T23:16:55Z",
            "description": null,
            "organization": {
                "slug": "xia",
                "printable_name": "Xia Lee"
            },
            "plan": {
                "slug": "open-space",
                "title": "Open Space",
                "description": "open space desk, High speed internet
                              - Ethernet or WiFi, Unlimited printing,
                              Unlimited scanning, Unlimited fax service
                              (send and receive)",
                "is_active": true,
                "setup_amount": 0,
                "period_amount": 17999,
                "period_type": "monthly",
                "app_url": "http://localhost:8020/app"
            },
            "auto_renew": true
        }
    ]
}
DELETE /api/profile/:organization/subscriptions/<subscribed_plan>/
class saas.api.subscriptions.SubscriptionDetailAPIView(**kwargs)

Retrieves a subscription

Returns the subscription of {organization} to {subscribed_plan}.

Tags: subscriptions

Examples

GET /api/profile/xia/subscriptions/open-space/ HTTP/1.1

responds

{
  "created_at": "2019-01-01T00:00:00Z",
  "ends_at": "2020-01-01T00:00:00Z",
  "description": null,
  "organization": {
    "slug": "xia",
    "created_at": "2019-01-01T00:00:00Z",
    "full_name": "Xia Lee",
    "email": "xia@localhost.localdomain",
    "phone": "555-555-5555",
    "street_address": "350 Bay St.",
    "locality": "San Francisco",
    "region": "CA",
    "postal_code": "94133",
    "country": "US",
    "default_timezone": "UTC",
    "printable_name": "Xia Lee",
    "is_provider": false,
    "is_bulk_buyer": false,
    "type": "personal",
    "credentials": true,
    "extra": null
  },
  "plan": {
    "slug": "open-space",
    "title": "Open Space",
    "description": "open space desk",
    "is_active": true,
    "setup_amount": 0,
    "period_amount": 17999,
    "period_length": 1,
    "interval": "monthly",
    "advance_discount": 0,
    "unit": "cad",
    "organization": "cowork",
    "renewal_type": "auto-renew",
    "is_not_priced": false,
    "created_at": "2019-01-01T00:00:00Z",
    "skip_optin_on_grant": false,
    "optin_on_request": false,
    "extra": null
  },
  "auto_renew": true,
  "editable": true,
  "extra": null,
  "grant_key": null,
  "request_key": null
}

Metrics API

GET /api/metrics/registered/
class saas.api.users.RegisteredAPIView(**kwargs)

Lists top of funnel registered users

Lists all User which have no associated role or a role to an Organization which has no Subscription, active or inactive.

The queryset can be filtered to a range of dates ([start_at, ends_at]) and for at least one field to match a search term (q).

Query results can be ordered by natural fields (o) in either ascending or descending order (ot).

Tags: metrics

Examples

GET  /api/metrics/registered?o=created_at&ot=desc HTTP/1.1

responds

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "slug": "alice",
            "email": "alice@djaodjin.com",
            "full_name": "Alice Cooper",
            "created_at": "2014-01-01T00:00:00Z"
        }
    ]
}
GET /api/metrics/:organization/active/
class saas.api.subscriptions.ActiveSubscriptionAPIView(**kwargs)

Lists active subscriptions

Lists all Subscription to a plan whose provider is {organization} and which are currently in progress.

Optionnaly when an ends_at query parameter is specified, returns a queryset of Subscription that were active at ends_at. When a start_at query parameter is specified, only considers Subscription that were created after start_at.

The queryset can be filtered for at least one field to match a search term (q).

Query results can be ordered by natural fields (o) in either ascending or descending order (ot).

Tags: metrics

Examples

GET /api/metrics/cowork/active?o=created_at&ot=desc HTTP/1.1

responds

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "created_at": "2016-01-14T23:16:55Z",
            "ends_at": "2017-01-14T23:16:55Z",
            "description": null,
            "organization": {
                "slug": "xia",
                "printable_name": "Xia Lee"
            },
            "plan": {
                "slug": "open-space",
                "title": "Open Space",
                "description": "open space desk, High speed internet
                            - Ethernet or WiFi, Unlimited printing,
                            Unlimited scanning, Unlimited fax service
                            (send and receive)",
                "is_active": true,
                "setup_amount": 0,
                "period_amount": 17999,
                "interval": 4,
                "app_url": "http://localhost:8020/app"
            },
            "auto_renew": true
        }
    ]
}
GET /api/metrics/:organization/balances/
class saas.api.metrics.BalancesAPIView(**kwargs)

Retrieves a default balance sheet

Generate a table of revenue (rows) per months (columns) for a default balance sheet (Income, Backlog, Receivable).

Tags: metrics

Examples

GET /api/metrics/cowork/balances HTTP/1.1

responds

{
    "title": "Balances",
    "scale": 0.01,
    "unit": "usd",
    "table": [
        {
            "key": "Income",
            "values": [
                ["2014-09-01T00:00:00Z", 0],
                ["2014-10-01T00:00:00Z", 1532624],
                ["2014-11-01T00:00:00Z", 2348340],
                ["2014-12-01T00:00:00Z", 3244770],
                ["2015-01-01T00:00:00Z", 5494221],
                ["2015-02-01T00:00:00Z", 7214221],
                ["2015-03-01T00:00:00Z", 8444221],
                ["2015-04-01T00:00:00Z", 9784221],
                ["2015-05-01T00:00:00Z", 12784221],
                ["2015-06-01T00:00:00Z", 14562341],
                ["2015-07-01T00:00:00Z", 16567341],
                ["2015-08-01T00:00:00Z", 17893214],
                ["2015-08-06T02:24:50.485Z", 221340]
            ]
        },
        {
            "key": "Backlog",
            "values": [
                ["2014-09-01T00:00:00Z", 1712624],
                ["2014-10-01T00:00:00Z", 3698340],
                ["2014-11-01T00:00:00Z", 7214770],
                ["2014-12-01T00:00:00Z", 10494221],
                ["2015-01-01T00:00:00Z", 14281970],
                ["2015-02-01T00:00:00Z", 18762845],
                ["2015-03-01T00:00:00Z", 24258765],
                ["2015-04-01T00:00:00Z", 31937741],
                ["2015-05-01T00:00:00Z", 43002401],
                ["2015-06-01T00:00:00Z", 53331444],
                ["2015-07-01T00:00:00Z", 64775621],
                ["2015-08-01T00:00:00Z", 75050033],
                ["2015-08-06T02:24:50.485Z", 89156321]
            ]
        },
        {
            "key": "Receivable",
            "values": [
                ["2014-09-01T00:00:00Z", 0],
                ["2014-10-01T00:00:00Z", 0],
                ["2014-11-01T00:00:00Z", 0],
                ["2014-12-01T00:00:00Z", 0],
                ["2015-01-01T00:00:00Z", 0],
                ["2015-02-01T00:00:00Z", 0],
                ["2015-03-01T00:00:00Z", 0],
                ["2015-04-01T00:00:00Z", 0],
                ["2015-05-01T00:00:00Z", 0],
                ["2015-06-01T00:00:00Z", 0],
                ["2015-07-01T00:00:00Z", 0],
                ["2015-08-01T00:00:00Z", 0],
                ["2015-08-06T02:24:50.485Z", 0]
            ]
        }
    ]
}
GET /api/metrics/balances/:report/
class saas.api.balances.BrokerBalancesAPIView(**kwargs)

Retrieves a balance sheet

Queries a balance sheet named {report} for the broker.

To add lines in the report see /api/metrics/balances/{report}/lines/.

Tags: metrics

Examples

GET /api/metrics/balances/taxes/ HTTP/1.1

responds

{
    "scale": 0.01,
    "unit": "usd",
    "title": "Balances: taxes",
    "table": [
        {
            "key": "Sales",
            "selector": "Receivable",
            "values": [
                ["2015-05-01T00:00:00Z", 0],
                ["2015-08-01T00:00:00Z", 0],
                ["2015-11-01T00:00:00Z", 0],
                ["2016-02-01T00:00:00Z", 0],
                ["2016-05-01T00:00:00Z", 0],
                ["2016-05-16T21:08:15.637Z", 0]
            ]
        }
    ]
}
GET /api/metrics/lines/:report/
POST /api/metrics/lines/:report/
class saas.api.balances.BalanceLineListAPIView(**kwargs)

Retrieves row headers for a balance sheet

Queries the list of rows reported on a balance sheet named {report}.

Tags: metrics

Examples

GET  /api/metrics/balances/taxes/lines/ HTTP/1.1

responds

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "title": "Sales",
            "selector": "Receivable",
            "rank": 1
        }
    ]
}
GET /api/metrics/:organization/churned/
class saas.api.subscriptions.ChurnedSubscriptionAPIView(**kwargs)

Lists churned subscriptions

Lists all Subscription to a plan whose provider is :organization which have ended already.

The queryset can be further filtered to a range of dates between start_at and ends_at.

The queryset can be further filtered by passing a q parameter. The result queryset can be ordered.

Tags: metrics

Examples

GET /api/metrics/cowork/churned?o=created_at&ot=desc HTTP/1.1

responds

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "created_at": "2016-01-14T23:16:55Z",
            "ends_at": "2017-01-14T23:16:55Z",
            "description": null,
            "organization": {
                "slug": "xia",
                "printable_name": "Xia Lee"
            },
            "plan": {
                "slug": "open-space",
                "title": "Open Space",
                "description": "open space desk, High speed internet
                            - Ethernet or WiFi, Unlimited printing,
                            Unlimited scanning, Unlimited fax service
                            (send and receive)",
                "is_active": true,
                "setup_amount": 0,
                "period_amount": 17999,
                "interval": 4,
                "app_url": "http://localhost:8020/app"
            },
            "auto_renew": true
        }
    ]
}
GET /api/metrics/:organization/coupons/:coupon/
class saas.api.metrics.CouponUsesAPIView(**kwargs)

Retrieves performance of a discount code

Queries a page (PAGE_SIZE records) of Coupon usage.

The queryset can be filtered to a range of dates ([start_at, ends_at]) and for at least one field to match a search term (q).

The result queryset can be ordered by passing an o (field name) and ot (asc or desc) parameter.

Tags: metrics

Examples

GET /api/metrics/cowork/coupons/DIS100/ HTTP/1.1

responds

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "user": {
                "slug": "xia",
                "email": "xia@localhost.localdomain",
                "full_name": "Xia Doe",
                "created_at": "2012-09-14T23:16:55Z"
            },
            "plan": "basic",
            "created_at": "2014-01-01T09:00:00Z"
        }
    ]
}
GET /api/metrics/:organization/customers/
class saas.api.metrics.CustomerMetricAPIView(**kwargs)

Retrieves 12-month trailing customer counts

Tags: metrics

Examples

GET /api/metrics/cowork/customers HTTP/1.1

responds

{
    "title": "Customers",
    "table": [
        {
            "key": "Total # of Customers",
            "values": [
                ["2014-10-01T00:00:00Z", 15],
                ["2014-11-01T00:00:00Z", 17],
                ["2014-12-01T00:00:00Z", 19],
                ["2015-01-01T00:00:00Z", 19],
                ["2015-02-01T00:00:00Z", 25],
                ["2015-03-01T00:00:00Z", 29],
                ["2015-04-01T00:00:00Z", 37],
                ["2015-05-01T00:00:00Z", 43],
                ["2015-06-01T00:00:00Z", 46],
                ["2015-07-01T00:00:00Z", 48],
                ["2015-08-01T00:00:00Z", 54],
                ["2015-08-06T05:20:24.537Z", 60]
            ]
        },
        {
            "key": "# of new Customers",
            "values": [
                ["2014-10-01T00:00:00Z", 2],
                ["2014-11-01T00:00:00Z", 2],
                ["2014-12-01T00:00:00Z", 0],
                ["2015-01-01T00:00:00Z", 6],
                ["2015-02-01T00:00:00Z", 4],
                ["2015-03-01T00:00:00Z", 8],
                ["2015-04-01T00:00:00Z", 6],
                ["2015-05-01T00:00:00Z", 3],
                ["2015-06-01T00:00:00Z", 2],
                ["2015-07-01T00:00:00Z", 6],
                ["2015-08-01T00:00:00Z", 7],
                ["2015-08-06T05:20:24.537Z", 0]
            ]
        },
        {
            "key": "# of churned Customers",
            "values": [
                ["2014-10-01T00:00:00Z", 0],
                ["2014-11-01T00:00:00Z", 0],
                ["2014-12-01T00:00:00Z", 0],
                ["2015-01-01T00:00:00Z", 0],
                ["2015-02-01T00:00:00Z", 0],
                ["2015-03-01T00:00:00Z", 0],
                ["2015-04-01T00:00:00Z", 0],
                ["2015-05-01T00:00:00Z", 0],
                ["2015-06-01T00:00:00Z", 0],
                ["2015-07-01T00:00:00Z", 0],
                ["2015-08-01T00:00:00Z", 1],
                ["2015-08-06T05:20:24.537Z", 60]
            ]
        },
        {
            "key": "Net New Customers",
            "values": [
                ["2014-10-01T00:00:00Z", 2],
                ["2014-11-01T00:00:00Z", 2],
                ["2014-12-01T00:00:00Z", 0],
                ["2015-01-01T00:00:00Z", 6],
                ["2015-02-01T00:00:00Z", 4],
                ["2015-03-01T00:00:00Z", 8],
                ["2015-04-01T00:00:00Z", 6],
                ["2015-05-01T00:00:00Z", 3],
                ["2015-06-01T00:00:00Z", 2],
                ["2015-07-01T00:00:00Z", 6],
                ["2015-08-01T00:00:00Z", 6],
                ["2015-08-06T05:20:24.537Z", -60]
            ]
        }
    ],
    "extra": [
        {
            "key": "% Customer Churn",
            "values": [
                ["2014-10-01T00:00:00Z", 0],
                ["2014-11-01T00:00:00Z", 0.0],
                ["2014-12-01T00:00:00Z", 0.0],
                ["2015-01-01T00:00:00Z", 0.0],
                ["2015-02-01T00:00:00Z", 0.0],
                ["2015-03-01T00:00:00Z", 0.0],
                ["2015-04-01T00:00:00Z", 0.0],
                ["2015-05-01T00:00:00Z", 0.0],
                ["2015-06-01T00:00:00Z", 0.0],
                ["2015-07-01T00:00:00Z", 0.0],
                ["2015-08-01T00:00:00Z", 2.08],
                ["2015-08-06T05:20:24.537Z", 111.11]
            ]
        }
    ]
}
GET /api/metrics/:organization/funds/
class saas.api.metrics.RevenueMetricAPIView(**kwargs)

Retrieves 12-month trailing revenue

Produces sales, payments and refunds over a period of time.

Tags: metrics

Examples

GET /api/metrics/cowork/funds/ HTTP/1.1

responds

{
    "title": "Amount",
    "scale": 0.01,
    "unit": "usd",
    "table": [
        {
            "key": "Total Sales",
            "values": [
                ["2014-10-01T00:00:00Z", 1985716],
                ["2014-11-01T00:00:00Z", 3516430],
                ["2014-12-01T00:00:00Z", 3279451],
                ["2015-01-01T00:00:00Z", 3787749],
                ["2015-02-01T00:00:00Z", 4480875],
                ["2015-03-01T00:00:00Z", 5495920],
                ["2015-04-01T00:00:00Z", 7678976],
                ["2015-05-01T00:00:00Z", 11064660],
                ["2015-06-01T00:00:00Z", 10329043],
                ["2015-07-01T00:00:00Z", 11444177],
                ["2015-08-01T00:00:00Z", 10274412],
                ["2015-08-06T04:59:14.721Z", 14106288]
            ]
        },
        {
            "key": "New Sales",
            "values": [
                ["2014-10-01T00:00:00Z", 0],
                ["2014-11-01T00:00:00Z", 0],
                ["2014-12-01T00:00:00Z", 0],
                ["2015-01-01T00:00:00Z", 0],
                ["2015-02-01T00:00:00Z", 0],
                ["2015-03-01T00:00:00Z", 0],
                ["2015-04-01T00:00:00Z", 0],
                ["2015-05-01T00:00:00Z", 0],
                ["2015-06-01T00:00:00Z", 0],
                ["2015-07-01T00:00:00Z", 0],
                ["2015-08-01T00:00:00Z", 0],
                ["2015-08-06T04:59:14.721Z", 0]
            ]
        },
        {
            "key": "Churned Sales",
            "values": [
                ["2014-10-01T00:00:00Z", 0],
                ["2014-11-01T00:00:00Z", 0],
                ["2014-12-01T00:00:00Z", 0],
                ["2015-01-01T00:00:00Z", 0],
                ["2015-02-01T00:00:00Z", 0],
                ["2015-03-01T00:00:00Z", 0],
                ["2015-04-01T00:00:00Z", 0],
                ["2015-05-01T00:00:00Z", 0],
                ["2015-06-01T00:00:00Z", 0],
                ["2015-07-01T00:00:00Z", 0],
                ["2015-08-01T00:00:00Z", 0],
                ["2015-08-06T04:59:14.721Z", 0]
            ]
        },
        {
            "key": "Payments",
            "values": [
                ["2014-10-01T00:00:00Z", 1787144],
                ["2014-11-01T00:00:00Z", 3164787],
                ["2014-12-01T00:00:00Z", 2951505],
                ["2015-01-01T00:00:00Z", 3408974],
                ["2015-02-01T00:00:00Z", 4032787],
                ["2015-03-01T00:00:00Z", 4946328],
                ["2015-04-01T00:00:00Z", 6911079],
                ["2015-05-01T00:00:00Z", 9958194],
                ["2015-06-01T00:00:00Z", 9296138],
                ["2015-07-01T00:00:00Z", 10299759],
                ["2015-08-01T00:00:00Z", 9246970],
                ["2015-08-06T04:59:14.721Z", 12695659]
            ]
        },
        {
            "key": "Refunds",
            "values": [
                ["2014-10-01T00:00:00Z", 0],
                ["2014-11-01T00:00:00Z", 0],
                ["2014-12-01T00:00:00Z", 0],
                ["2015-01-01T00:00:00Z", 0],
                ["2015-02-01T00:00:00Z", 0],
                ["2015-03-01T00:00:00Z", 0],
                ["2015-04-01T00:00:00Z", 0],
                ["2015-05-01T00:00:00Z", 0],
                ["2015-06-01T00:00:00Z", 0],
                ["2015-07-01T00:00:00Z", 0],
                ["2015-08-01T00:00:00Z", 0],
                ["2015-08-06T04:59:14.721Z", 0]
            ]
        }
    ]
}
GET /api/metrics/:organization/plans/
class saas.api.metrics.PlanMetricAPIView(**kwargs)

Retrieves 12-month trailing plans performance

Tags: metrics

Examples

GET /api/metrics/cowork/plans HTTP/1.1

responds

{
    "title": "Active Subscribers",
    "table": [
        {
            "is_active": true,
            "key": "open-space",
            "location": "/profile/plan/open-space/",
            "values": [
                ["2014-09-01T00:00:00Z", 4],
                ["2014-10-01T00:00:00Z", 5],
                ["2014-11-01T00:00:00Z", 6],
                ["2014-12-01T00:00:00Z", 6],
                ["2015-01-01T00:00:00Z", 6],
                ["2015-02-01T00:00:00Z", 9],
                ["2015-03-01T00:00:00Z", 9],
                ["2015-04-01T00:00:00Z", 9],
                ["2015-05-01T00:00:00Z", 11],
                ["2015-06-01T00:00:00Z", 11],
                ["2015-07-01T00:00:00Z", 14],
                ["2015-08-01T00:00:00Z", 16],
                ["2015-08-06T05:37:50.004Z", 16]
            ]
        },
        {
            "is_active": true,
            "key": "open-plus",
            "location": "/profile/plan/open-plus/",
            "values": [
                ["2014-09-01T00:00:00Z", 7],
                ["2014-10-01T00:00:00Z", 8],
                ["2014-11-01T00:00:00Z", 9],
                ["2014-12-01T00:00:00Z", 9],
                ["2015-01-01T00:00:00Z", 12],
                ["2015-02-01T00:00:00Z", 13],
                ["2015-03-01T00:00:00Z", 18],
                ["2015-04-01T00:00:00Z", 19],
                ["2015-05-01T00:00:00Z", 19],
                ["2015-06-01T00:00:00Z", 20],
                ["2015-07-01T00:00:00Z", 23],
                ["2015-08-01T00:00:00Z", 25],
                ["2015-08-06T05:37:50.014Z", 25]
            ]
        },
        {
            "is_active": true,
            "key": "private",
            "location": "/profile/plan/private/",
            "values": [
                ["2014-09-01T00:00:00Z", 3],
                ["2014-10-01T00:00:00Z", 3],
                ["2014-11-01T00:00:00Z", 3],
                ["2014-12-01T00:00:00Z", 3],
                ["2015-01-01T00:00:00Z", 6],
                ["2015-02-01T00:00:00Z", 7],
                ["2015-03-01T00:00:00Z", 10],
                ["2015-04-01T00:00:00Z", 15],
                ["2015-05-01T00:00:00Z", 16],
                ["2015-06-01T00:00:00Z", 17],
                ["2015-07-01T00:00:00Z", 17],
                ["2015-08-01T00:00:00Z", 18],
                ["2015-08-06T05:37:50.023Z", 18]
            ]
        }
    ],
    "extra": [
        {
            "key": "churn",
            "values": [
                ["2014-09-01T00:00:00Z", 0],
                ["2014-10-01T00:00:00Z", 0],
                ["2014-11-01T00:00:00Z", 0],
                ["2014-12-01T00:00:00Z", 0],
                ["2015-01-01T00:00:00Z", 0],
                ["2015-02-01T00:00:00Z", 0],
                ["2015-03-01T00:00:00Z", 0],
                ["2015-04-01T00:00:00Z", 0],
                ["2015-05-01T00:00:00Z", 0],
                ["2015-06-01T00:00:00Z", 0],
                ["2015-07-01T00:00:00Z", 0],
                ["2015-08-01T00:00:00Z", 1],
                ["2015-08-06T05:37:50.031Z", 1]
            ]
        }
    ]
}

Search API

At times, we might be looking to grant a User permissions to an Organization through a Role (manager, etc.), or we might be looking to request access to an Organization on behalf of a User. Both features might benefit from an auto-complete suggestions list. The two following API end point will list all Organization and User in the database regardless of their associations.

class saas.api.organizations.OrganizationListAPIView(**kwargs)

Queries a page (PAGE_SIZE records) of organization and user profiles.

The queryset can be filtered for at least one field to match a search term (q).

The queryset can be ordered by a field by adding an HTTP query parameter o= followed by the field name. A sequence of fields can be used to create a complete ordering by adding a sequence of o HTTP query parameters. To reverse the natural order of a field, prefix the field name by a minus (-) sign.

Tags: profile

Examples

GET /api/profile/?o=created_at HTTP/1.1

responds

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [{
        "slug": "xia",
        "full_name": "Xia Lee",
        "email": "xia@localhost.localdomain",
        "printable_name": "Xia Lee",
        "created_at": "2016-01-14T23:16:55Z"
    }]
}