# Invoices

Source: https://developers.swell.is/backend-api/invoices

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.

## The invoice model

### Fields

- `id` (objectId): Unique identifier for the invoice.
- `account_id` (objectId, required): ID of the customer's account. Default: `{"$formula":"source.account_id"}`.
- `account` (Account): Expandable link to the customer's account.
- `closed` (boolean): When true, it indicates no further attempts will be made to capture payment for the invoice. Default: `false`.
- `coupon` (Coupon): Expandable link to the coupon applied to the invoice.
- `coupon_code` (string): Coupon code applied to the invoice.
- `coupon_id` (objectId): ID of the coupon applied to the invoice.
- `credits` (Credit memo): Expandable list of account credit transactions. Balance of these transactions is kept in `balance`.
- `credit_total` (currency): Total amount of additional credit applied to the order.
- `currency` (string): Three-letter ISO currency code in uppercase. Defaults to the store's base currency.
- `currency_rate` (float): Currency percentage used in calculating the fixed amount.
- `date_created` (date, auto): Date and time the invoice was created.
- `date_due` (date): The date by which the invoice is to be paid.
- `date_payment_retry` (date): Date the next automatic payment will be attempted.
- `date_period_end` (date): End date of the subscription billing period for the invoice. Default: `{"$formula":"if(subscription_id, subscription.date_period_end)"}`.
- `date_period_start` (date): Start date of the subscription billing period for the invoice. Default: `{"$formula":"if(subscription_id, subscription.date_period_start)"}`.
- `date_updated` (date, auto): Date and time the invoice was last updated.
- `discount_total` (currency, auto): Total discount amount.
- `discounts` (array of object): List of all discounts applied to the invoice.
  - `id` (string): Unique identifier for the object.
  - `amount` (currency): Fixed discount amount.
  - `rule` (object): Object describing the discount rule details. Custom discounts don't require this value.
  - `source_id` (objectId): ID of the source object that generated the discount, such as a coupon or promotion.
  - `type` (string): Type of discount. Can be `coupon` or `sale` referring to the source of the discount. Custom discounts don't require this value.
- `grand_total` (currency, auto): Grand total including items and taxes.
- `giftcard_total` (currency): Total gift card value applied to the invoice.
- `giftcards` (array of object): List of gift cards applied to the invoice.
  - `id` (objectId)
  - `amount` (currency)
  - `code` (string)
  - `code_formatted` (string)
  - `last4` (string)
  - `giftcard` (giftcard)
- `item_discount` (currency, auto): Sum of all line items before discounts and taxes.
- `item_tax_included` (boolean): Indicates line item prices include taxes.
- `item_tax` (currency, auto): Total taxes applied to line items.
- `item_quantity` (int, auto): Total quantity of all line items.
- `item_quantity_creditable` (int): Quantity of creditable items on the order.
- `items` (array of object): List of invoice line items.
  - `id` (objectId): Unique identifier for the object.
  - `bundle_items` (array of object): List of bundled items, if applicable.
    - `id` (objectId): Unique identifier for the object.
    - `product_id` (objectId): ID of the bundled product.
    - `product` (product): Expandable link to the bundled product.
    - `quantity` (int): Quantity of the bundled item.
    - `quantity_total` (int): Total quantity of the bundled item (`items.quantity * bundle_items.quantity`).
    - `variant_id` (objectId): ID of the bundled product variant.
    - `variant` (variant): Expandable link to the bundled product variant.
  - `description` (string): Description used for custom line items, when product is not defined.
  - `discount_each` (currency): Total discount amount divided by quantity.
  - `discount_total` (currency): Total discount applied to the item.
  - `discounts` (array of object): List of discounts to be applied to the line items.
    - `id` (string): ID of the promotion or discount to apply.
    - `amount` (currency): Amount of the discount to apply
  - `options` (array of object): Line item options, if applicable.
    - `id` (string): Unique identifier for the object.
    - `name` (string): Name of the option.
    - `value` (string): Value of the option.
  - `price` (currency): Price of the line item.
  - `price_total` (currency): Original item price used internally to determine if the item price was overridden and should be automatically updated when item options are changed.
  - `product_id` (objectId): ID of the line item product.
  - `product` (product): Expandable link to the line item product.
  - `quantity` (int): Quantity of the line item. Default: `1`.
  - `taxes` (array of object): List of taxes applied to the invoice line items.
    - `id` (string): Unique identifier for the object.
    - `amount` (currency): Fixed tax amount.
  - `tax_each` (currency): Total tax amount divided by quantity.
  - `tax_total` (currency): Total tax applied to the item.
  - `variant_id` (objectId): ID of the line item product variant.
  - `variant` (variant): Expandable link to the line item product variant.
  - `quantity_creditable` (int): Quantity of items eligible to be credited.
- `net_days` (int): Net number of days for which the invoice is open before being considered past due.
- `notes` (string): 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](https://developers.swell.is/backend-api/notes).
- `number` (string, auto): Unique incremental invoice number, assigned automatically.
- `order` (Order): Expandable link to the order the invoice was applied to, if applicable.
- `order_id` (objectId): ID of the order the invoice was applied to, if applicable.
- `paid` (boolean, auto): Indicates the invoice was paid in full. Default: `false`.
- `pastdue` (boolean): Indicates the invoice payment is past due. Default: `false`.
- `payment_due` (currency, auto): Payment amount due on the invoice.
- `payment_error` (string): A message describing the last payment error, if one occurred.
- `payment_retry_count` (int): The number of times automatic payment has been attempted.
- `payment_retry_resolve` (string): The method used to resolve automatic payment when all retry attempts are exhausted. Can be blank (do nothing), `canceled`, or `unpaid`.
- `payment_total` (currency): Sum of payments applied to the order, not including refunds.
- `payments` (Payment): Expandable list of payments applied to the invoice.
- `refunds` (Refund): Expandable list of refunds applied to the invoice.
- `shipment_tax` (currency): Shipping tax amount, if applicable.
- `shipment_tax_included` (boolean): Indicates shipping total includes taxes, if applicable.
- `shipment_tax_included_total` (currency): Total of taxes applied separately from line items.
- `shipment_total` (currency): Total shipping price after discounts.
- `source` (Product): Expands into the corresponding order or subscription using `source_model` and `source_id`.
- `source_id` (objectId): 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.
- `source_model` (string): 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.
- `status` (enum, auto): Current status of the invoice. Can be `pending`, `paid`, or `unpaid`. Possible values: `pending`, `void`, `paid`, `unpaid`. Default: `"pending"`.
- `sub_total` (currency, auto): Sum of all line items before discounts, taxes and shipping.
- `subscription` (Subscription): Expandable link to the subscription the invoice was issued for.
- `subscription_id` (objectId): ID of the subscription the invoice was issued for.
- `tax_included_total` (currency, auto): Total of taxes applied separately from line items.
- `tax_total` (currency, auto): Total tax amount applied to the order including line items.
- `taxes` (array of object): List of taxes applied to the order.
  - `id` (string): Unique identifier for the object.
  - `name` (string): Name of the tax rule. For example, "NY Sales Tax".
  - `shipping` (boolean): Indicates the tax applies to shipping.
  - `priority` (int): 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.
  - `rate` (float): Tax percentage used in calculating the fixed amount.
  - `amount` (currency): Fixed tax amount.

### Example response

```json
{
  "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 invoice

Retrieve an existing invoice using the ID that was returned when created.

### Arguments

- `id` (objectId, required): ID of the invoice to retrieve.
- `expand` (string): 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](https://developers.swell.is/backend-api/querying/expanding) for more details.
- `fields` (string): 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` (string): Include one or more arbitrary queries in the response, possibly related to the main query.

  See [including ](https://developers.swell.is/backend-api/querying/including)for more details.

### Example request

`GET /invoices/:id`

**cURL**

```bash
$ curl https://api.swell.store/invoices/60f199509111e70000000037 \
  -u store-id:secret-key
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.get('/invoices/{id}', {
  id: '60f199509111e70000000037'
});
```

**PHP**

```php
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/invoices/{id}', [
  'id' => '60f199509111e70000000037'
]);
```

### Example response

```json
{
  "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"
}
```


## List all invoices

Return a list of invoices.

### Arguments

- `expand` (string): 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](https://developers.swell.is/backend-api/querying/expanding) for more details.
- `fields` (string): 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` (object): Include one or more arbitrary queries in the response which are potentially related to the main query.

  See [including](https://developers.swell.is/backend-api/querying/including) for more details.
- `limit` (int): Limit the number of records returned, ranging between `1` and `1000`. Defaults to `15`. Default: `15`.
- `page` (int): The page number of results to return given the specified or default `limit`.
- `search` (string): 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](https://developers.swell.is/backend-api/querying/searching) for more details.
- `sort` (string): 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](https://developers.swell.is/backend-api/querying/sorting) for more details.
- `where` (object): 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](https://developers.swell.is/backend-api/querying) for more details.

### Example request

`GET /invoices`

**cURL**

```bash
$ curl https://api.swell.store/invoices \
  -u store-id:secret-key \
  -G
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.get('/invoices');
```

**PHP**

```php
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/invoices');
```

### Example response

```json
{
  "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,
  "page_count": 4,
  "limit": 15,
  "pages": {
    "1": {
      "start": 1,
      "end": 15
    },
    "2": {
      "start": 16,
      "end": 30
    },
    "3": {
      "start": 31,
      "end": 45
    },
    "4": {
      "start": 46,
      "end": 51
    }
  }
}
```