Subscription Invoices
Throughout the lifecycle of a subscription, numerous invoices are generated. Typically, there is one at the time of purchase, and then one for each renewal.
A subscription invoice belongs to a Subscription.
The subscription invoice object
Attributes
store_id
The ID of the Store this subscription invoice belongs to.
subscription_id
The ID of the Subscription associated with this subscription.
billing_reason
The reason for the invoice being generated.
initial
- The initial invoice generated when the subscription is created.renewal
- A renewal invoice generated when the subscription is renewed.updated
- An invoice generated when the subscription is updated.
card_brand
Brand of the card used to pay for the invoice. One of visa
, mastercard
, american_express
, discover
, jcb
, diners_club
.
card_last_four
The last 4 digits of the card used to pay for the invoice.
currency
The ISO 4217 currency code for the invoice (e.g. USD
, GBP
, etc).
currency_rate
If the invoice currency is USD, this will always be 1.0
. Otherwise, this is the currency conversion rate used to determine the cost of the invoice in USD at the time of payment.
subtotal
A positive integer in cents representing the subtotal of the invoice in the invoice currency.
discount_total
A positive integer in cents representing the total discount value applied to the invoice in the invoice currency.
tax
A positive integer in cents representing the tax applied to the invoice in the invoice currency.
total
A positive integer in cents representing the total cost of the invoice in the invoice currency.
subtotal_usd
A positive integer in cents representing the subtotal of the invoice in USD.
discount_total
A positive integer in cents representing the total discount value applied to the invoice in USD.
tax_usd
A positive integer in cents representing the tax applied to the invoice in USD.
total_usd
A positive integer in cents representing the total cost of the invoice in USD.
status
The status of the invoice. One of paid
, open
, void
, uncollectible
or draft
.
status_formatted
The formatted status of the invoice.
refunded
A boolean value indicating whether the invoice has been refunded.
refunded_at
If the invoice has been refunded, this will be an ISO-8601 formatted date-time string indicating when the invoice was refunded. Otherwise, it will be null
.
urls
An object of customer-facing URLs for the invoice. It contains:
invoice_url
- The unique URL to download a PDF of the invoice. Note: for security reasons, download URLs are signed (but do not expire).
created_at
An ISO-8601 formatted date-time string indicating when the invoice was created.
updated_at
An ISO-8601 formatted date-time string indicating when the invoice was last updated.
Subscription invoice object
Retrieve a subscription invoice
Retrieves the subscription invoice with the given ID.
GET /v1/subscription-invoices/:id
Returns
Returns a subscription invoice object.
Response
List all subscription invoices
Returns a paginated list of subscription invoices.
Parameters
store_id
Only return subscription invoices belonging to the store with this ID.
status
Only return subscription invoices with this status.
refunded
Only return subscription invoices that are refunded
(the value should be true
or false
).
GET /v1/subscription-invoices
Returns
Returns a paginated list of subscription invoice objects ordered by created_at
(descending).