# Base URL and versions

> Every path starts with https://secure.yoprint.com, the API version and your team slug. Why many v2 paths repeat /v2/, and when to use v1 or v2.

Web page: https://developer.yoprint.com/concepts/base-url-and-versions/

All requests go to one host:

```text
https://secure.yoprint.com
```

Every path then starts with the API version and your [team slug](https://developer.yoprint.com/concepts/teams.md):

```text
https://secure.yoprint.com/v1/api/store/your-team/...
https://secure.yoprint.com/v2/api/store/your-team/...
```

**Diagram:** Every request URL has the same five parts.

1. **Host**: `https://secure.yoprint.com` /
2. **Version**: `v1` or `v2` /
3. **Fixed**: `api/store` /
4. **Team slug**: `your-team` /
5. **Resource**: Such as `customer`, or `v2/sales_order/…` in v2

## v2 paths often repeat `/v2/`

Most v2 operations have a second `/v2/` after the team slug. This isn't a typo. Send it exactly as shown:

```text
GET https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7
```

A few v2 families don't have the second `/v2/`, for example messages, message templates and order search:

```text
GET https://secure.yoprint.com/v2/api/store/your-team/messages
```

Copy each path from its reference page rather than building it by rule.

## v1 or v2

The version is part of each operation's path, not a header or a setting. You can use v1 and v2 operations side by side with the same key.

| Use v2 for                                                               | Use v1 for                                             |
| ------------------------------------------------------------------------ | ------------------------------------------------------ |
| Quotes and sales orders, their line items, approvals, comments and media | Customers, contacts and addresses                      |
| Jobs and their tasks, on an order                                        | Products, variants and supplier catalog lookups        |
| Shipments, packages, rates and labels                                    | Vendors                                                |
| Invoices, invoice lines and payments                                     | Team settings, statuses, users and webhooks            |
| Messages and message templates                                           | Data exports, imports and reports                      |
| Order search and the v2 filters for orders, quotes and invoices          | Job and task filters, calendars and production control |

When the same thing exists in both, use v2. Some older v1 operations no longer work: the v1 sales order and quote filters, showing a job, changing a job's status and reading a sales order's history. Use their v2 versions.

## Deprecated operations

The reference marks an operation **Legacy** when a newer one does the same thing. The legacy operations that still work keep working for now, so an existing integration doesn't break. Each answer says the operation is deprecated and names the one to use instead:

```text
Deprecation: @1794009600
X-YoPrint-Successor: POST /v2/api/store/{team_slug}/v2/invoice/filter
```

- `Deprecation` is when the operation was deprecated, in seconds since 1970 (RFC 9745). `@1794009600` is November 7, 2026.
- `X-YoPrint-Successor` is the replacement's method and path. Move to it.

No removal date is set yet. [Changes and deprecations](https://developer.yoprint.com/start/changes.md) lists all 18 deprecated operations, and it's where removal dates will appear.

## Deprecated fields

Some answers still carry an older copy of a newer field. The reference marks it **deprecated** and names the field to read instead. It keeps coming back for now, so an existing integration doesn't break. Read the newer field in new code:

| Deprecated                                                                                     | Read instead                                                                                                      |
| ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| An order's or quote's `calc_total`, `calc_tax`, `calc_discount`                                | `invoiced_total`, `invoiced_tax_subtotal`, `invoiced_discount_subtotal`                                           |
| An order's or quote's `calc_subtotal`                                                          | `invoiced_order_item_subtotal` (it already includes billed shipping, and `calc_subtotal` adds the shipping again) |
| An invoice's `calc_subtotal`, `calc_delivery_total`, `calc_tax`, `calc_discount`, `calc_total` | `cart_item_subtotal`, `shipment_subtotal`, `tax_subtotal`, `discount_subtotal`, `total`                           |

The newer fields are decimal pairs. For details on decimal pairs, older thousandths encodings, and which order totals to read, see [Money and quantities](https://developer.yoprint.com/concepts/money-and-quantities.md).

## Request and response format

- Send request bodies as JSON, with `Content-Type: application/json`.
- Send `Accept: application/json` on every request. Matched paths answer JSON anyway, but a path that doesn't exist (`404`) or a method it doesn't take (`405`) answers an HTML page without it.
- Send `X-Yoprint-Decimal-Format: exact-v1` on every request, so amounts come back exact. Without it, a few saves that would answer with a very precise amount are refused with `422` `amount_out_of_range`. See [Money and quantities](https://developer.yoprint.com/concepts/money-and-quantities.md#ask-for-exact-responses).
- Responses are JSON, apart from file downloads such as PDFs and CSV exports.
- A successful JSON response has `status`, `success: true` and `data`. Errors have `success: false`, and a few refusals come with status `200`. See [Errors](https://developer.yoprint.com/concepts/errors.md).

```json
{
  "status": 200,
  "success": true,
  "data": { "id": "V4keXwwxMQyXw7", "name": "Northwind Apparel" }
}
```

## Dates and times

Send date-times in UTC, ending in `Z`. See [Dates and times](https://developer.yoprint.com/concepts/dates-and-times.md).