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 and a Store.
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 invoice.
customer_id
The ID of the customer this subscription invoice belongs to.
user_name
The full name of the customer.
user_email
The email address of the customer.
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
Lowercase brand of the card used to pay for the invoice. One of
visamastercardamexdiscoverjcbdinersunionpay
Will be empty for non-card payments.
card_last_four
The last 4 digits of the card used to pay for the invoice. Will be empty for non-card payments.
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.
status
The status of the invoice. One of
pending- The invoice is waiting for payment.paid- The invoice has been paid.void- The invoice was cancelled or cannot be paid.refunded- The invoice was paid but has since been fully refunded.partial_refund– The invoice was paid but has since been partially refunded.
status_formatted
The formatted status of the invoice.
refunded
A boolean value indicating whether the invoice has been fully refunded.
refunded_at
If the invoice has been fully refunded, this will be an ISO 8601 formatted date-time string indicating when the invoice was refunded. Otherwise, it will be null.
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.
tax_inclusive
A boolean indicating if the order was created with tax inclusive or exclusive pricing.
total
A positive integer in cents representing the total cost of the invoice in the invoice currency.
refunded_amount
A positive integer in cents representing the refunded amount of the invoice in the invoice currency.
subtotal_usd
A positive integer in cents representing the subtotal of the invoice in USD.
discount_total_usd
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.
refunded_amount_usd
A positive integer in cents representing the refunded amount of the invoice in USD.
subtotal_formatted
A human-readable string representing the subtotal of the invoice in the invoice currency (e.g. $9.99).
discount_total_formatted
A human-readable string representing the total discount value applied to the invoice in the invoice currency (e.g. $9.99).
tax_formatted
A human-readable string representing the tax applied to the invoice in the invoice currency (e.g. $9.99).
total_formatted
A human-readable string representing the total cost of the invoice in the invoice currency (e.g. $9.99).
refunded_amount_formatted
A human-readable string representing the refunded amount of the invoice in the invoice currency (e.g. $9.99).
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). Will benullifstatusispending.
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.
test_mode
A boolean indicating if the object was created within test mode.
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.
Tip: to retrieve subscription invoices for a certain subscription, you can include related resources or use a nested query.
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).
subscription_id
Only return subscription invoices belonging to a subscription with this ID.
GET /v1/subscription-invoices
Returns
Returns a paginated list of subscription invoice objects ordered by created_at (descending).
Response
Generate subscription invoice
Generates a new invoice for the given subscription with given parameters.
Attributes
name
Optional. The full name of the customer.
address
Optional. The street address of the customer.
city
Optional. The city of the customer.
state
Optional. The state of the customer.
zip_code
Optional. The ZIP code of the customer.
country
Optional. The country of the customer.
notes
Optional. Any additional notes to include on the invoice.
POST /v1/subscription-invoices/:id/generate-invoice
Returns
Returns a link to download the generated invoice.
Response
Issue a refund
Issues a partial refund for a subscription invoice.
Attributes
amount
Required. The amount that you want to refund for a subscription invoice.
POST /v1/subscription-invoices/:id/refund
Returns
Returns a subscription invoice object.