# Get an invoice

```http
GET https://secure.yoprint.com/v2/api/store/{team_slug}/v2/invoice/{unique_key}
```

- API version: v2
- Operation ID: `v2_public_invoice_show`
- Section: Invoices and payments › [Invoices](https://developer.yoprint.com/reference/invoices.md)
- Web page: https://developer.yoprint.com/reference/invoices/v2-invoice-show/
- Authentication: `Authorization: Bearer YOUR_API_KEY`

An invoice bills some or all of a sales order (or quote). One order can have many invoices; each line of an invoice points at a line of the order, or is a shipping fee, a discount or the tax. Invoices have no status: they are paid or unpaid (`is_paid`) as payments recorded on the order are allocated to them.

Returns the invoice with its lines (`items`), its sales order (`order`), and its billing and shipping addresses. Money comes in two encodings:
- Decimal pairs (`total`, `cart_item_subtotal`, `shipment_subtotal`, `shipment_tax_subtotal`, `discount_subtotal`, `tax_subtotal`, `credit_card_surcharge`): the amount is `value` ÷ 10^`dp` (`{ "value": 3397500, "dp": 4 }` is 339.75). Read `dp` every time: invoice totals usually use `dp` 4 and line prices use `dp` 6.
- Thousandths, an older encoding (`paid_amount`, `calc_deposit_total`): `10000` is 10.00. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (`1234.5` is 1.2345), or as a string (`"1234.5"`) when you send `X-Yoprint-Decimal-Format: exact-v1`. See [Money and quantities](/concepts/money-and-quantities/). The `calc_*` totals are deprecated copies of the pairs: use the pairs.

`is_valid` is false when the invoice needs fixing (no lines, lines but no tax line, or a customer that differs from the order's). `pdf_url` holds PDF links that carry their own long-lived access token: don't publish them.

The path takes the invoice `id` (a hash id).

## Permission

Any member of the team.

## Path parameters

- `team_slug` (string, required): Your team slug, shown as Team ID next to your API key in Profile. Example `your-team`.
- `unique_key` (string, required): The invoice's `id` (a hash id), as its answers show it. Its unique key (`ordinv_...`) also works, but API answers don't include it. Example `cBRpSf5nw6upt5`.

## Request body

This operation takes no request body.

### Example request

```bash
curl 'https://secure.yoprint.com/v2/api/store/your-team/v2/invoice/cBRpSf5nw6upt5' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'X-Yoprint-Decimal-Format: exact-v1'
```

## Response

`200` Successful response.

Fields:

- `data` (object, required): An invoice. Amounts are decimal pairs at the stored scale (4 decimal places for invoice totals), except `paid_amount` and `calc_deposit_total` (thousandths). The `calc_*` totals are deprecated copies of the decimal-pair ones.
  - `auto_invoice_managed` (boolean, optional): YoPrint keeps this invoice in step with the order (Auto Invoice).
  - `bill_to_status` (string, optional): How Bill To compares with the order's. One of: `"okay"`, `"empty"`, `"diff_from_order"`, `"diff_from_customer"`.
  - `billing_address` (object | null, optional): An address.
    - `address1` (string | null, optional)
    - `address2` (string | null, optional)
    - `city` (string | null, optional)
    - `country` (string | null, optional)
    - `country_code` (string | null, optional)
    - `id` (string, optional): The address.
    - `label` (string | null, optional)
    - `postcode` (string | null, optional)
    - `state` (string | null, optional)
    - `state_code` (string | null, optional)
  - `billing_address_id` (string | null, optional): Bill To.
  - `calc_deposit_total` (integer | number | string | null, optional): The order's deposit amount. Thousandths, an older encoding: `12500` is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (`1234.5` is 1.2345), or as a string (`"1234.5"`) when you send `X-Yoprint-Decimal-Format: exact-v1`. See [Money and quantities](/concepts/money-and-quantities/).
  - `cart_item_subtotal` (decimal pair, optional): Billed sales order lines and shipping fees (price × quantity); `shipment_subtotal` is the shipping part of it. `total` = `cart_item_subtotal` − `discount_subtotal` + `tax_subtotal` (+ `credit_card_surcharge`). At the stored scale (4 decimal places). A decimal pair: the amount is `value` ÷ 10^`dp` (`{ "value": 1250, "dp": 2 }` is 12.50). Read `dp` every time: it can differ between fields and records. See https://developer.yoprint.com/concepts/money-and-quantities.md.
  - `created_at` (string (date-time), optional)
  - `credit_card_surcharge` (decimal pair, optional): A card surcharge added by a card payment; zero when there is none. Always sent. A decimal pair: the amount is `value` ÷ 10^`dp` (`{ "value": 1250, "dp": 2 }` is 12.50). Read `dp` every time: it can differ between fields and records. See https://developer.yoprint.com/concepts/money-and-quantities.md.
  - `customer` (object | null, optional): The customer (the full customer record).
    - `id` (string, optional): The customer.
    - `name` (string, optional)
  - `deposit_due` (string (date-time) | null, optional): From the order. ISO 8601 with offset, or null.
  - `deposit_required` (boolean | integer | null, optional): From the order.
  - `discount_subtotal` (decimal pair, optional): Discounts. A decimal pair: the amount is `value` ÷ 10^`dp` (`{ "value": 1250, "dp": 2 }` is 12.50). Read `dp` every time: it can differ between fields and records. See https://developer.yoprint.com/concepts/money-and-quantities.md.
  - `external_type` (string | null, optional)
  - `from_legacy` (boolean, optional)
  - `full_amount_due` (string (date-time) | null, optional): From the order. ISO 8601 with offset, or null.
  - `id` (string, optional): The invoice.
  - `is_external` (boolean, optional)
  - `is_paid` (boolean, optional): Paid amount covers the total (also true for a zero total).
  - `is_valid` (boolean, optional): False when the invoice needs fixing: no lines, lines without a tax line, or a customer that differs from the order's.
  - `issue_date` (string (date-time) | null, optional): Issue date. ISO 8601 with offset, or null.
  - `items` (array of objects, optional): The lines. Sort by `position`.
    - Each item:
      - `_meta` (object, optional): Read-only: `id`, `type`, `invoice_id`, `lock_version`, `from_legacy`, `position_hash`.
      - `auto_invoice_managed` (boolean, optional): YoPrint manages this line (Auto Invoice).
      - `external_ids` (array of objects, optional): Links to external systems; empty for lines made in YoPrint.
      - `external_type` (string | null, optional)
      - `from_legacy` (boolean, optional)
      - `id` (string, optional): The invoice line.
      - `invoice_id` (string, optional): The invoice.
      - `is_external` (boolean, optional)
      - `lock_version` (integer, optional): Send it back on Update an invoice line to detect a concurrent change.
      - `position` (integer, optional)
      - `pricing` (object, optional): Absent on tax and discount lines. `system` (sales order lines): `_meta.unit_price` is the price copied from the sales order line and `_meta.subtotal` is that price × this line's quantity. `fee` (shipping fees): `product.total` is the fee. Prices come at the stored scale (6 decimal places); `_meta.subtotal` at the combined scale of price × quantity (compacted when large). Always read `dp`.
        - `type` (string, optional): One of: `"system"`, `"fee"`.
      - `product` (object, optional)
        - `_meta` (object, optional): Read-only details, always an object (with `editable_fields_on_update`); for `order_item`, `parent` describes the sales order line.
        - `properties` (object, optional): The kind's fields; for `order_item`, `id` is the sales order line. A discount's percentage or amount comes back as `total` (you send it as `rate`).
        - `type` (string, optional): One of: `"order_item"`, `"shipment_fee"`, `"invoice_discount"`, `"user_tax"`, `"override_tax"`, `"auto_tax"`, `"invoice_surcharge"`.
      - `quantity` (object, optional): Absent on tax and discount lines.
        - `type` (string, optional): Always `"unit"`.
        - `total` (decimal pair, optional): The quantity. A decimal pair: the amount is `value` ÷ 10^`dp` (`{ "value": 1250, "dp": 2 }` is 12.50). Read `dp` every time: it can differ between fields and records. See https://developer.yoprint.com/concepts/money-and-quantities.md.
      - `tax` (object, optional): Absent on tax and discount lines. YoPrint adds it by default only to sales order lines (`taxable`); other lines have it only when it was sent.
        - `type` (string, optional): One of: `"taxable"`, `"non_taxable"`.
      - `type` (string, optional): Same as `product.type`.
  - `lock_version` (integer, optional)
  - `order` (object, optional): The sales order or quote in the v2 order shape: its header fields, with `status` and `assigned_users`, but no `items`.
    - `id` (string, optional): The order.
    - `scoped_id` (string | null, optional)
  - `order_id` (string, optional): The sales order or quote it bills.
  - `order_object_type` (string | null, optional): `sales_order` or `quote`.
  - `order_quote` (boolean, optional): The order is a quote.
  - `order_scoped_id` (string | null, optional): The order number.
  - `paid_amount` (integer | number | string | null, optional): Allocated payments. Thousandths, an older encoding: `12500` is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (`1234.5` is 1.2345), or as a string (`"1234.5"`) when you send `X-Yoprint-Decimal-Format: exact-v1`. See [Money and quantities](/concepts/money-and-quantities/).
  - `pdf_url` (array of objects, optional): PDF links.
    - Each item:
      - `label` (string, optional)
      - `object_type` (string, optional)
      - `url` (string, optional): A download link with its own long-lived access token: don't publish it.
  - `scoped_id` (string | null, optional): The invoice number.
  - `ship_to_status` (string, optional): One of: `"okay"`, `"empty"`, `"diff_from_order"`, `"diff_from_customer"`.
  - `shipment_subtotal` (decimal pair, optional): Shipping fees (already in `cart_item_subtotal`). A decimal pair: the amount is `value` ÷ 10^`dp` (`{ "value": 1250, "dp": 2 }` is 12.50). Read `dp` every time: it can differ between fields and records. See https://developer.yoprint.com/concepts/money-and-quantities.md.
  - `shipment_tax_subtotal` (decimal pair, optional): The tax on shipping (included in `tax_subtotal`). A decimal pair: the amount is `value` ÷ 10^`dp` (`{ "value": 1250, "dp": 2 }` is 12.50). Read `dp` every time: it can differ between fields and records. See https://developer.yoprint.com/concepts/money-and-quantities.md.
  - `shipping_address` (object | null, optional): An address. Same fields as `data.billing_address` above.
  - `shipping_address_id` (string | null, optional): Ship To.
  - `tax_subtotal` (decimal pair, optional): Tax. A decimal pair: the amount is `value` ÷ 10^`dp` (`{ "value": 1250, "dp": 2 }` is 12.50). Read `dp` every time: it can differ between fields and records. See https://developer.yoprint.com/concepts/money-and-quantities.md.
  - `total` (decimal pair, optional): The invoice total. A decimal pair: the amount is `value` ÷ 10^`dp` (`{ "value": 1250, "dp": 2 }` is 12.50). Read `dp` every time: it can differ between fields and records. See https://developer.yoprint.com/concepts/money-and-quantities.md.
  - `version` (integer, optional)
  - `calc_delivery_total` (integer | number | string | null, optional, deprecated): **Deprecated:** use `shipment_subtotal`, the same amount. Thousandths, an older encoding: `12500` is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (`1234.5` is 1.2345), or as a string (`"1234.5"`) when you send `X-Yoprint-Decimal-Format: exact-v1`. See [Money and quantities](/concepts/money-and-quantities/).
  - `calc_discount` (integer | number | string | null, optional, deprecated): **Deprecated:** use `discount_subtotal`, the same amount. Thousandths, an older encoding: `12500` is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (`1234.5` is 1.2345), or as a string (`"1234.5"`) when you send `X-Yoprint-Decimal-Format: exact-v1`. See [Money and quantities](/concepts/money-and-quantities/).
  - `calc_subtotal` (integer | number | string | null, optional, deprecated): **Deprecated:** use `cart_item_subtotal`, the same amount. Thousandths, an older encoding: `12500` is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (`1234.5` is 1.2345), or as a string (`"1234.5"`) when you send `X-Yoprint-Decimal-Format: exact-v1`. See [Money and quantities](/concepts/money-and-quantities/).
  - `calc_tax` (integer | number | string | null, optional, deprecated): **Deprecated:** use `tax_subtotal`, the same amount. Thousandths, an older encoding: `12500` is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (`1234.5` is 1.2345), or as a string (`"1234.5"`) when you send `X-Yoprint-Decimal-Format: exact-v1`. See [Money and quantities](/concepts/money-and-quantities/).
  - `calc_total` (integer | number | string | null, optional, deprecated): **Deprecated:** use `total`, the same amount. Thousandths, an older encoding: `12500` is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (`1234.5` is 1.2345), or as a string (`"1234.5"`) when you send `X-Yoprint-Decimal-Format: exact-v1`. See [Money and quantities](/concepts/money-and-quantities/).
- `status` (integer, required)
- `success` (boolean, required)

Example response:

```json
{
  "data": {
    "auto_invoice_managed": false,
    "bill_to_status": "okay",
    "billing_address": {
      "address1": "100 Example Street",
      "address2": null,
      "city": "Austin",
      "country": "United States",
      "country_code": "US",
      "id": "117KfwwfreX15N",
      "label": "Main office",
      "postcode": "78701",
      "state": "Texas",
      "state_code": "TX"
    },
    "billing_address_id": "117KfwwfreX15N",
    "calc_deposit_total": 169880,
    "cart_item_subtotal": {
      "dp": 4,
      "value": 3150000
    },
    "created_at": "2026-11-03T15:00:00+00:00",
    "credit_card_surcharge": {
      "dp": 4,
      "value": 0
    },
    "customer": {
      "id": "ifAHmADekGZ6id",
      "name": "Northwind Apparel"
    },
    "deposit_due": "2026-11-05T00:00:00+00:00",
    "deposit_required": true,
    "discount_subtotal": {
      "dp": 4,
      "value": 0
    },
    "external_type": null,
    "from_legacy": false,
    "full_amount_due": "2026-11-20T00:00:00+00:00",
    "id": "cBRpSf5nw6upt5",
    "is_external": false,
    "is_paid": false,
    "is_valid": true,
    "issue_date": "2026-11-03T00:00:00+00:00",
    "items": [
      {
        "_meta": {
          "from_legacy": false,
          "id": "nhsGsn84PyJBvK",
          "invoice_id": "cBRpSf5nw6upt5",
          "lock_version": 1730000000000000,
          "position_hash": "EXAMPLEpositionHash",
          "type": "order_item"
        },
        "auto_invoice_managed": false,
        "external_ids": [],
        "external_type": null,
        "from_legacy": false,
        "id": "nhsGsn84PyJBvK",
        "invoice_id": "cBRpSf5nw6upt5",
        "is_external": false,
        "lock_version": 1730000000000000,
        "position": 100,
        "position_hash": "EXAMPLEpositionHash",
        "pricing": {
          "_meta": {
            "subtotal": {
              "dp": 0,
              "value": 300
            },
            "unit_price": {
              "dp": 6,
              "value": 12500000
            }
          },
          "type": "system"
        },
        "product": {
          "_meta": {
            "parent": {
              "product_name": "Gildan 5000 T-shirt"
            }
          },
          "properties": {
            "id": "ZJTJ2uF5dMiArL"
          },
          "type": "order_item"
        },
        "quantity": {
          "total": {
            "dp": 0,
            "value": 24
          },
          "type": "unit"
        },
        "tax": {
          "type": "taxable"
        },
        "type": "order_item"
      },
      {
        "_meta": {
          "from_legacy": false,
          "id": "E6U0sez7BmPz1t",
          "invoice_id": "cBRpSf5nw6upt5",
          "lock_version": 1730000000000000,
          "position_hash": "EXAMPLEpositionHash",
          "type": "shipment_fee"
        },
        "auto_invoice_managed": false,
        "external_ids": [],
        "external_type": null,
        "from_legacy": false,
        "id": "E6U0sez7BmPz1t",
        "invoice_id": "cBRpSf5nw6upt5",
        "is_external": false,
        "lock_version": 1730000000000000,
        "position": 900,
        "position_hash": "EXAMPLEpositionHash",
        "pricing": {
          "product": {
            "total": {
              "dp": 6,
              "value": 15000000
            }
          },
          "type": "fee"
        },
        "product": {
          "_meta": {
            "product_hash": "EXAMPLEproductHash",
            "product_name": "Shipping"
          },
          "properties": {
            "description": null,
            "name": "Shipping",
            "shipping_taxable": 0
          },
          "type": "shipment_fee"
        },
        "quantity": {
          "total": {
            "dp": 0,
            "value": 1
          },
          "type": "unit"
        },
        "type": "shipment_fee"
      },
      {
        "_meta": {
          "from_legacy": false,
          "id": "WzHB84GM5mzqAw",
          "invoice_id": "cBRpSf5nw6upt5",
          "lock_version": 1730000000000001,
          "position_hash": "EXAMPLEpositionHash",
          "type": "user_tax"
        },
        "auto_invoice_managed": false,
        "external_ids": [],
        "external_type": null,
        "from_legacy": false,
        "id": "WzHB84GM5mzqAw",
        "invoice_id": "cBRpSf5nw6upt5",
        "is_external": false,
        "lock_version": 1730000000000001,
        "position": 2147483647,
        "position_hash": "EXAMPLEpositionHash",
        "product": {
          "_meta": {
            "editable_fields_on_update": [
              "product.properties",
              "product.properties.description",
              "product.properties.id",
              "product.properties.refresh_tax_rate",
              "product.properties.shipping_taxable",
              "product.properties.apply_before_discount"
            ],
            "product_hash": "EXAMPLEproductHash",
            "product_name": "State sales tax"
          },
          "properties": {
            "apply_before_discount": 0,
            "description": null,
            "id": "KC48n7qAAfGYMM",
            "invoice_tax_metadata": [
              {
                "rate_decimal": 3,
                "rate_value": 8250,
                "tax_id": 4021,
                "tax_last_updated": "2026-10-01T09:00:00.000000Z",
                "tax_name": "State sales tax",
                "tax_type": "simple",
                "total_decimal": 2,
                "total_value": 2475
              }
            ],
            "name": "State sales tax",
            "rate": {
              "dp": 6,
              "value": 8250000
            },
            "shipping_taxable": 0,
            "user_tax_last_updated": "2026-10-01T09:00:00+00:00"
          },
          "type": "user_tax"
        },
        "type": "user_tax"
      }
    ],
    "lock_version": 1730000000000000,
    "order": {
      "id": "sFbALVSYD55eXe",
      "scoped_id": "SO1001"
    },
    "order_id": "sFbALVSYD55eXe",
    "order_object_type": "sales_order",
    "order_quote": false,
    "order_scoped_id": "SO1001",
    "paid_amount": 100000,
    "pdf_url": [
      {
        "description": "Invoice pdf",
        "label": "Invoice",
        "object_type": "invoice",
        "url": "https://example.com/pdf/invoice.pdf"
      }
    ],
    "scoped_id": "1001",
    "ship_to_status": "okay",
    "shipment_subtotal": {
      "dp": 4,
      "value": 150000
    },
    "shipment_tax_subtotal": {
      "dp": 4,
      "value": 0
    },
    "shipping_address": {
      "address1": "100 Example Street",
      "address2": null,
      "city": "Austin",
      "country": "United States",
      "country_code": "US",
      "id": "117KfwwfreX15N",
      "label": "Main office",
      "postcode": "78701",
      "state": "Texas",
      "state_code": "TX"
    },
    "shipping_address_id": "117KfwwfreX15N",
    "tax_subtotal": {
      "dp": 4,
      "value": 247500
    },
    "total": {
      "dp": 4,
      "value": 3397500
    },
    "version": 2
  },
  "status": 200,
  "success": true
}
```

## Errors

- `401` The API key is missing or wrong (`unauthenticated`).
- `403` You are not allowed to do this. `api_access_not_in_plan`: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only `{"message": "Insufficient Permission"}`. Other refusals use the error envelope, with `unauthorized` or `user_is_not_authorized`.
- `404` Not found. `page_not_found`: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. `code: null`, with a message that starts "No query results for": there is no record with that id.
  - When: The invoice isn't your team's, or was deleted. Fix: Use an id from Filter invoices or the order's invoice list.

## Notes

- Send the header `X-Yoprint-Decimal-Format: exact-v1` so large amounts come back exactly (as digit strings when needed).

## Related

- [Update an invoice](https://developer.yoprint.com/reference/invoices/v2-invoice-update.md): `PUT /v2/api/store/{team_slug}/v2/invoice/{unique_key}`
- [List the lines of an invoice](https://developer.yoprint.com/reference/invoice-line-items/v2-invoice-item-index.md): `GET /v2/api/store/{team_slug}/v2/invoice/{unique_key}/item`
- [List the invoices of a sales order](https://developer.yoprint.com/reference/invoices/v2-sales-order-invoice-index-for-order.md): `GET /v2/api/store/{team_slug}/v2/sales_order/{unique_key}/invoice`
- [Filter invoices](https://developer.yoprint.com/reference/invoices/v2-invoice-filter.md): `POST /v2/api/store/{team_slug}/v2/invoice/filter`