Backend API
Invoices are created automatically when a subscription is charged. An invoice captures the billing period of a subscription, including the subscription plan and line items prices. Payments are applied directly to an invoice.
Fields
Unique identifier for the invoice.
ID of the customer's account.
Expandable link to the customer's account.
When true, it indicates no further attempts will be made to capture payment for the invoice.
Expandable link to the coupon applied to the invoice.
Coupon code applied to the invoice.
ID of the coupon applied to the invoice.
Expandable list of account credit transactions. Balance of these transactions is kept in balance.
Total amount of additional credit applied to the order.
Three-letter ISO currency code in uppercase. Defaults to the store's base currency.
Currency percentage used in calculating the fixed amount.
Date and time the invoice was created.
The date by which the invoice is to be paid.
Date the next automatic payment will be attempted.
End date of the subscription billing period for the invoice.
Start date of the subscription billing period for the invoice.
Date and time the invoice was last updated.
Total discount amount.
List of all discounts applied to the invoice.
Unique identifier for the object.
Fixed discount amount.
Object describing the discount rule details. Custom discounts don't require this value.
ID of the source object that generated the discount, such as a coupon or promotion.
Type of discount. Can be coupon or sale referring to the source of the discount. Custom discounts don't require this value.
Grand total including items and taxes.
Total gift card value applied to the invoice.
List of gift cards applied to the invoice.
Sum of all line items before discounts and taxes.
Indicates line item prices include taxes.
Total taxes applied to line items.
Total quantity of all line items.
Quantity of creditable items on the order.
List of invoice line items.
Unique identifier for the object.
List of bundled items, if applicable.
Unique identifier for the object.
ID of the bundled product.
Expandable link to the bundled product.
Quantity of the bundled item.
Total quantity of the bundled item (items.quantity * bundle_items.quantity).
ID of the bundled product variant.
Expandable link to the bundled product variant.
Description used for custom line items, when product is not defined.
Total discount amount divided by quantity.
Total discount applied to the item.
List of discounts to be applied to the line items.
ID of the promotion or discount to apply.
Amount of the discount to apply
Line item options, if applicable.
Unique identifier for the object.
Name of the option.
Value of the option.
Price of the line item.
Original item price used internally to determine if the item price was overridden and should be automatically updated when item options are changed.
ID of the line item product.
Expandable link to the line item product.
Quantity of the line item.
List of taxes applied to the invoice line items.
Unique identifier for the object.
Fixed tax amount.
Total tax amount divided by quantity.
Total tax applied to the item.
ID of the line item product variant.
Expandable link to the line item product variant.
Quantity of items eligible to be credited.
Quantity of items credited on the order.
Net number of days for which the invoice is open before being considered past due.
Internal admin notes, not visible to the customer. This field holds a single block of text. To record a series of notes against the invoice, each attributed to a user, see Notes.
Unique incremental invoice number, assigned automatically.
Expandable link to the order the invoice was applied to, if applicable.
ID of the order the invoice was applied to, if applicable.
Indicates the invoice was paid in full.
Indicates the invoice payment is past due.
Payment amount due on the invoice.
A message describing the last payment error, if one occurred.
The number of times automatic payment has been attempted.
The method used to resolve automatic payment when all retry attempts are exhausted. Can be blank (do nothing), canceled, or unpaid.
Sum of payments applied to the order, not including refunds.
Expandable list of payments applied to the invoice.
Expandable list of refunds applied to the invoice.
Shipping tax amount, if applicable.
Indicates shipping total includes taxes, if applicable.
Total of taxes applied separately from line items.
Total shipping price after discounts.
Expands into the corresponding order or subscription using source_model and source_id.
Used to expand source into corresponding order or subscription. Equal to order_id. If order_id is not set, then equal to subscription_id. If order_id nor subscription_id are set, is null.
Used to expand source into corresponding order or subscription. If order_id is set, equals orders. If subscription_id is set, equals subscriptions. When neither is set, is null.
Current status of the invoice. Can be pending, paid, or unpaid.
Possible enum values:
Sum of all line items before discounts, taxes and shipping.
Expandable link to the subscription the invoice was issued for.
ID of the subscription the invoice was issued for.
Total of taxes applied separately from line items.
Total tax amount applied to the order including line items.
List of taxes applied to the order.
Unique identifier for the object.
Name of the tax rule. For example, "NY Sales Tax".
Indicates the tax applies to shipping.
Priority indicates the order in which a tax rule was applied. Higher priority rules are added on top of other tax rules with a lower priority. Rules with the same priority are calculated excluding each other.
Tax percentage used in calculating the fixed amount.
Fixed tax amount.
The invoice model
{
"id": "60f199509111e7000000002f",
"account_id": "60f199509111e70000000031",
"currency": "USD",
"date_created": "2021-07-16T14:36:00.194Z",
"date_updated": "2021-07-16T14:36:00.194Z",
"items": [
{
"id": "5ca537326a0ec32a521139dd",
"product_id": "5c524166f4e8f3446a10331b",
"variant_id": "5c524166f4e8f3446a10331f",
"quantity": 2,
"price": 19.99,
"price_total": 38.98,
"orig_price": 19.99,
"options": [
{
"id": "5becb84fac207653a4816ee5",
"name": "Type",
"value": "Elven"
},
{
"id": "5becb84fac207653a4816ee6",
"name": "Enchanted",
"value": "Fire"
}
],
"discounts": [
{
"id": "coupon-0",
"amount": 5
}
],
"discount_each": 2.5,
"discount_total": 5,
"taxes": [
{
"id": "sales-tax",
"amount": 2
}
],
"tax_each": 1,
"tax_total": 2
}
],
"number": 117266,
"paid": false,
"pastdue": false,
"status": "pending"
}Retrieve an existing invoice using the ID that was returned when created.
Arguments
ID of the invoice to retrieve.
Expanding link fields and child collections is performed using the expand argument.
- For example, expand=account would return a related customer account if one exists.
When the field represents a collection, you can specify the query limit.
- For example, expand=variants:10 would return up to 10 records of the variants collection.
See expanding for more details.
Return only the specified fields in the result. For example fields=name,slug would return only the fields name and slug in the response. Supports nested object and array fields using dot-notation. For example, items.product_id. The gift card id is always returned.
Include one or more arbitrary queries in the response, possibly related to the main query.
See including for more details.
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');
await swell.get('/invoices/{id}', {
id: '60f199509111e70000000037'
});
Response
{
"id": "60f199509111e70000000037",
"account_id": "60f199509111e70000000038",
"currency": "USD",
"date_created": "2021-07-16T14:36:00.194Z",
"date_updated": "2021-07-16T14:36:00.194Z",
"items": [
{
"id": "5ca537326a0ec32a521139dd",
"product_id": "5c524166f4e8f3446a10331b",
"variant_id": "5c524166f4e8f3446a10331f",
"quantity": 2,
"price": 19.99,
"price_total": 38.98,
"orig_price": 19.99,
"options": [
{
"id": "5becb84fac207653a4816ee5",
"name": "Size",
"value": "Small"
},
{
"id": "5becb84fac207653a4816ee6",
"name": "Color",
"value": "Yellow"
}
],
"discounts": [
{
"id": "coupon-0",
"amount": 5
}
],
"discount_each": 2.5,
"discount_total": 5,
"taxes": [
{
"id": "sales-tax",
"amount": 2
}
],
"tax_each": 1,
"tax_total": 2
}
],
"number": 117266,
"paid": false,
"pastdue": false,
"status": "pending"
}Return a list of invoices.
Arguments
Expand link fields and child collections by using the expand argument.
- For example, expand=account would return a related customer account if one exists.
When the field represents a collection, you can specify the query limit.
- For example, expand=variants:10 would return up to 10 records of the variants collection.
See expanding for more details.
Returns only the specified fields in the result.
- For example fields=name,slug would return only the fields name and slug in the response.
Supports nested object and array fields using dot-notation.
- For example, items.product_id. The product id is always returned.
Include one or more arbitrary queries in the response which are potentially related to the main query.
See including for more details.
Limit the number of records returned, ranging between 1 and 1000. Defaults to 15.
The page number of results to return given the specified or default limit.
A text search is performed using the search argument. Searchable fields are defined by the model.
- For example, search=red would return records containing the word "red" anywhere in the defined text fields.
See searching for more details.
Expression to sort results by using a format similar to a SQL sort statement.
- For example, sort=name asc would return records sorted by name ascending.
See sorting for more details.
An object with criteria to filter the result.
- For example, active=true would return records containing a field active with the value true.
It's also possible to use query operators, for example, $eq, $ne, $gt, and more.
See querying for more details.
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');
await swell.get('/invoices/{id}', {
id: '60f199509111e70000000033'
});
Response
{
"count": 51,
"results": [
{
"id": "60f199509111e7000000002f",
"account_id": "60f199509111e7000000003c",
"currency": "USD",
"date_created": "2021-07-16T14:36:00.194Z",
"date_updated": "2021-07-16T14:36:00.194Z",
"items": [
{
"id": "5ca537326a0ec32a521139dd",
"product_id": "5c524166f4e8f3446a10331b",
"variant_id": "5c524166f4e8f3446a10331f",
"quantity": 2,
"price": 19.99,
"price_total": 38.98,
"orig_price": 19.99,
"options": [
{
"id": "5becb84fac207653a4816ee5",
"name": "Size",
"value": "Small"
},
{
"id": "5becb84fac207653a4816ee6",
"name": "Color",
"value": "Yellow"
}
],
"discounts": [
{
"id": "coupon-0",
"amount": 5
}
],
"discount_each": 2.5,
"discount_total": 5,
"taxes": [
{
"id": "sales-tax",
"amount": 2
}
],
"tax_each": 1,
"tax_total": 2
}
],
"number": 117266,
"paid": false,
"pastdue": false,
"status": "pending"
},
{...},
{...}
],
"page": 1,
"pages": {
"1": {
"start": 1,
"end": 25
},
"2": {
"start": 26,
"end": 50
},
"2": {
"start": 51,
"end": 51
}
}
}