/api/administrator/subscriptions/usage-record-summaries (GET)
await global.api.administrator.subscriptions.UsageRecordSummaries.get(req) Located in Stripe Subscriptions module API
Returns stripe list response
Exceptions
These exceptions are thrown (NodeJS) or returned as JSON (HTTP) if you provide incorrect data or do not meet the requirements:
Exception | Circumstances |
---|---|
invalid querystring subscriptionitemid | |
invalid-subscriptionitemid | missing querystring subscriptionitemid |
Receives
API routes may receive parameters from the URL and POST supporting simple and multipart:
Field | Value | Required | Type |
---|---|---|---|
ending_before | string | optional | URL |
limit | integer | optional | URL |
starting_after | string | optional | URL |
NodeJS source (edit on github)
If you see a problem with the source submit a pull request on Github.
const subscriptions = require('../../../../../index.js')
const stripe = require('stripe')()
stripe.setApiVersion(global.stripeAPIVersion)
if (global.maxmimumStripeRetries) {
stripe.setMaxNetworkRetries(global.maximumStripeRetries)
}
stripe.setTelemetryEnabled(false)
module.exports = {
// TODO: the usage records get aggregated into these summaries
// but there's currently no way to index and paginate them
// consistent with other objects
get: async (req) => {
if (!req.query || !req.query.subscriptionitemid) {
throw new Error('invalid-subscriptionitemid')
}
const listInfo = {}
if (req.query.ending_before) {
listInfo.ending_before = req.query.ending_before
} else if (req.query.starting_after) {
listInfo.starting_after = req.query.starting_after
}
if (req.query.limit) {
listInfo.limit = parseInt(req.query.limit, 10)
} else {
listInfo.limit = global.pageSize
}
let records
try {
records = await stripe.subscriptionItems.listUsageRecordSummaries(req.query.subscriptionitemid, listInfo, req.stripeKey)
} catch (error) {
if (error.message === 'stripe.subscriptionItems.listUsageRecordSummaries is not a function') {
// TODO: not sure if this is pending a nodejs update
// or an api-update on Stripe's side but the method
// is not currently available
return null
}
throw new Error('invalid-subscriptionitemid')
}
if (!records || !records.data || !records.data.length) {
return null
}
// TODO: as a fallback for checking ownership the summaries
// invoice is verified as belonging to the user
req.query.invoiceid = records.data[0].invoice
const owned = await subscriptions.StorageList.exists(`${req.appid}/account/invoices/${req.account.accountid}`, records.data[0].invoice)
if (!owned) {
throw new Error('invalid-account')
}
const invoice = await global.api.user.subscriptions.Invoice.get(req)
if (!invoice) {
throw new Error('invalid-subscriptionitemid')
}
return records
}
}
Test source (edit on github)
Tests perform real HTTP requests against a running Dashboard server.
/* eslint-env mocha */
const assert = require('assert')
const TestHelper = require('../../../../../test-helper.js')
describe('/api/administrator/subscriptions/usage-record-summaries', () => {
describe('exceptions', () => {
describe('invalid-subscriptionitemid', () => {
it('missing querystring subscriptionitemid', async () => {
const administrator = await TestHelper.createOwner()
const req = TestHelper.createRequest('/api/administrator/subscriptions/usage-record-summaries')
req.account = administrator.account
req.session = administrator.session
let errorMessage
try {
await req.get()
} catch (error) {
errorMessage = error.message
}
assert.strictEqual(errorMessage, 'invalid-subscriptionitemid')
})
it('invalid querystring subscriptionitemid', async () => {
// TODO: this test needs to verify ownership of the
// subscriptionitemid after they are indexed
})
})
})
describe('receives', () => {
it('optional querystring starting_after (string)', async () => {
// TODO: this test needs to cause multiple usage summaries
})
it('optional querystring ending_before (string)', async () => {
// TODO: this test needs to cause multiple usage summaries
})
it('optional querystring limit (integer)', async () => {
// TODO: this test needs to cause multiple usage summaries
})
})
describe('returns', () => {
it('stripe list response', async () => {
// TODO: this test needs to cause multiple usage summaries
})
})
describe('configuration', () => {
it('environment PAGE_SIZE', async () => {
// TODO: this test needs to cause multiple usage summaries
})
})
})