Get an invoice

GET/v2/api/store/{team_slug}/v2/invoice/{unique_key}

v2Operation ID v2_public_invoice_show

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. 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_slugstringrequired

  Your team slug, shown as Team ID next to your API key in Profile.

  • Example your-team
• unique_keystringrequired

  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.

Response

200Successful response.

• dataobjectrequired

  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.

  Child fields (43)

  • auto_invoice_managedboolean

    YoPrint keeps this invoice in step with the order (Auto Invoice).

  • bill_to_statusstring

    How Bill To compares with the order's.

    • One of: "okay", "empty", "diff_from_order", "diff_from_customer"
  • billing_addressobject | null

    An address.

    Child fields (10)

    • address1string | null
    • address2string | null
    • citystring | null
    • countrystring | null
    • country_codestring | null
    • idstring

      The address.

    • labelstring | null
    • postcodestring | null
    • statestring | null
    • state_codestring | null
  • billing_address_idstring | null

    Bill To.

  • calc_deposit_totalinteger | number | string | null

    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.

  • cart_item_subtotaldecimal pair

    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 Money and quantities.
  • created_atstring (date-time)
  • credit_card_surchargedecimal pair

    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 Money and quantities.
  • customerobject | null

    The customer (the full customer record).

    Child fields (2)

    • idstring

      The customer.

    • namestring
  • deposit_duestring (date-time) | null

    From the order. ISO 8601 with offset, or null.

  • deposit_requiredboolean | integer | null

    From the order.

  • discount_subtotaldecimal pair

    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 Money and quantities.
  • external_typestring | null
  • from_legacyboolean
  • full_amount_duestring (date-time) | null

    From the order. ISO 8601 with offset, or null.

  • idstring

    The invoice.

  • is_externalboolean
  • is_paidboolean

    Paid amount covers the total (also true for a zero total).

  • is_validboolean

    False when the invoice needs fixing: no lines, lines without a tax line, or a customer that differs from the order's.

  • issue_datestring (date-time) | null

    Issue date. ISO 8601 with offset, or null.

  • itemsarray of objects

    The lines. Sort by position.

    Fields of each item (15)

    • _metaobject

      Read-only: id, type, invoice_id, lock_version, from_legacy, position_hash.

    • auto_invoice_managedboolean

      YoPrint manages this line (Auto Invoice).

    • external_idsarray of objects

      Links to external systems; empty for lines made in YoPrint.

    • external_typestring | null
    • from_legacyboolean
    • idstring

      The invoice line.

    • invoice_idstring

      The invoice.

    • is_externalboolean
    • lock_versioninteger

      Send it back on Update an invoice line to detect a concurrent change.

    • positioninteger
    • pricingobject

      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.

      Child fields (1)

      • typestring
        • One of: "system", "fee"
    • productobject
      Child fields (3)

      • _metaobject

        Read-only details, always an object (with editable_fields_on_update); for order_item, parent describes the sales order line.

      • propertiesobject

        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).

      • typestring
        • One of: "order_item", "shipment_fee", "invoice_discount", "user_tax", "override_tax", "auto_tax", "invoice_surcharge"
    • quantityobject

      Absent on tax and discount lines.

      Child fields (2)

      • typestring
        • Always "unit"
      • totaldecimal pair

        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 Money and quantities.
    • taxobject

      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.

      Child fields (1)

      • typestring
        • One of: "taxable", "non_taxable"
    • typestring

      Same as product.type.

  • lock_versioninteger
  • orderobject

    The sales order or quote in the v2 order shape: its header fields, with status and assigned_users, but no items.

    Child fields (2)

    • idstring

      The order.

    • scoped_idstring | null
  • order_idstring

    The sales order or quote it bills.

  • order_object_typestring | null

    sales_order or quote.

  • order_quoteboolean

    The order is a quote.

  • order_scoped_idstring | null

    The order number.

  • paid_amountinteger | number | string | null

    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.

  • pdf_urlarray of objects

    PDF links.

    Fields of each item (3)

    • labelstring
    • object_typestring
    • urlstring

      A download link with its own long-lived access token: don't publish it.

  • scoped_idstring | null

    The invoice number.

  • ship_to_statusstring
    • One of: "okay", "empty", "diff_from_order", "diff_from_customer"
  • shipment_subtotaldecimal pair

    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 Money and quantities.
  • shipment_tax_subtotaldecimal pair

    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 Money and quantities.
  • shipping_addressobject | null

    An address.

    • Same fields as data.billing_address.
  • shipping_address_idstring | null

    Ship To.

  • tax_subtotaldecimal pair

    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 Money and quantities.
  • totaldecimal pair

    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 Money and quantities.
  • versioninteger
  • calc_delivery_totalinteger | number | string | nulldeprecated

    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.

  • calc_discountinteger | number | string | nulldeprecated

    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.

  • calc_subtotalinteger | number | string | nulldeprecated

    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.

  • calc_taxinteger | number | string | nulldeprecated

    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.

  • calc_totalinteger | number | string | nulldeprecated

    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.

• statusintegerrequired
• successbooleanrequired

Errors

• 401The API key is missing or wrong (unauthenticated).

• 403You 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.

• 404Not 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

• PUTUpdate an invoice/v2/api/store/{team_slug}/v2/invoice/{unique_key}
• GETList the lines of an invoice/v2/api/store/{team_slug}/v2/invoice/{unique_key}/item
• GETList the invoices of a sales order/v2/api/store/{team_slug}/v2/sales_order/{unique_key}/invoice
• POSTFilter invoices/v2/api/store/{team_slug}/v2/invoice/filter

Example request

curl

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'

Example response 200

Response

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