Migration Guide: v1 → v2

This guide covers the changes between API v1 and v2 and how to update your integration.

Base URL Changes

API	v1 Base URL	v2 Base URL
Public (Production)	https://api.tidely.com/api/v1/open-api	https://api.tidely.com/public/v2
Public (Staging)	https://api.sam.tidely.com/api/v1/open-api	https://api.sam.tidely.com/public/v2

Update all API calls to use the new path structure prefix.

Changes to Existing Resources

Invoices

The biggest change to an existing resource is the invoice API. In v1, invoices were handled through a single unified import endpoint. In v2 this has been replaced by a full set of resource-oriented CRUD operations:

Operation	v2 Endpoint
List	GET /invoices
Retrieve	GET /invoices/{id}
Create	POST /invoices
Bulk create	POST /invoices/bulk (up to 1000 at once)
Update	PATCH /invoices/{id}
Delete	DELETE /invoices/{id}

Key things to be aware of when migrating:

• Migrate away from the import endpoint — clients relying on the v1 import endpoint must switch to the new operations above. Use POST /invoices/bulk for high-volume creation.
• List and retrieve require invoiceTypeFilter — GET /invoices and GET /invoices/{id} take a required invoiceTypeFilter query parameter (SALE or PURCHASE).
• ERP-sourced invoices are read-only — invoices originating from an ERP integration cannot be updated or deleted; PATCH and DELETE are rejected for them.
• Partial updates — PATCH /invoices/{id} updates only the mutable invoice fields and does not accept externalId or invoiceType.

Pagination Changes

Paginated endpoints in v2 use a consistent response structure with metadata fields (number, size, totalElements, totalPages). See the Pagination guide for details.

Authentication

Authentication methods are unchanged in v2:

• Public API: API key via X-Authorization header
• Partner API (new in v2): OAuth 2.0 via Authorization: Bearer header

Migration Checklist

1. ✅ Update base URLs
2. ✅ Update pagination handling for the new response metadata format
3. ✅ Migrate invoice integrations from the v1 import endpoint to the new CRUD operations
4. ✅ Test your integration against the staging environment (api.sam.tidely.com)
5. ✅ Switch production traffic to v2

v1 Deprecation Timeline

v1 is currently deprecated but still operational. End of life has not been scheduled yet. When end of life is announced, there will be at least 6 months notice via email and the changelog.

We recommend migrating to v2 as soon as possible to benefit from new features and improvements.