> ## Documentation Index
> Fetch the complete documentation index at: https://docs.decisionly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Versioning

> Understanding Decisionly API versions and changes

The Decisionly API uses versioning to ensure backward compatibility while allowing us to improve the API over time.

## How Versioning Works

The Decisionly API uses URL-based versioning. You specify the API version directly in the URL path of your requests. We will bump the API version for **breaking changes**. Non-breaking changes, such as adding new fields or endpoints, will not trigger a version bump.

All API endpoints are versioned by including the version in the URL path. For example:

* `https://api.decisionly.com/v2/issuer/cases`
* `https://api.decisionly.com/v1/issuer/cases`

## Version History

* **v2 (Current)**
* **v1 (Legacy)**

## v2 Changes

### Terminal Statuses

Terminal case states are now represented as distinct status values instead of using a generic `closed` status with a `closed_reason` field:

**v1 behavior:**

* Terminal cases had `status: "closed"` with a `closed_reason` field indicating the specific outcome
* A single `case.closed` webhook was triggered for all terminal states

**v2 behavior:**

* Terminal states are now first-class status values: `accepted`, `rejected`, `expired`, `withdrawn`, `merchant_credited`
* The `closed_reason` field has been removed
* Each terminal status has its own dedicated webhook event: `case.accepted`, `case.rejected`, `case.expired`, `case.withdrawn`, `case.merchant_credited`
* The `case.closed` webhook is deprecated

See the [Case Lifecycle documentation](/case-lifecycle) for more details.

### File endpoint

Cases are now filed using a [dedicated file endpoint](/api-reference/v2-cases/file-a-case).

### Evidence Structure Changes

The `issuer_evidence` object has been reorganized in v2 for better clarity and consistency:

**Field groupings:**

* Amount corrections: `correct_amount` and `correct_currency` → `amount_correction.amount` and `amount_correction.currency`
* Return shipping: `return.shipping_carrier` and `return.shipping_tracking` → `return.shipping.carrier` and `return.shipping.tracking_number`
* Service end date: `service_end_date` → `service.end_date`
* Resolution: Previously flat resolution fields are now organized into specific resolution type objects:
  * Product resolution fields → `product` object (order\_id, description, condition, type)
  * Cancellation fields → `cancellation` object (id, date, description, policy\_provided)
  * Refund fields → `refund` object (was\_promised, promise\_date, description)
  * Return fields → `return` object (date, was\_successful, description, policy\_provided, shipping)
  * Delivery fields → `delivery` object (date, expected\_date)
  * Service fields → `service` object (end\_date)
  * Card fraud fields → `card` object (lost\_date, is\_active, cardholder\_has\_possession, possession\_at\_transaction)

**Boolean field renames:**

* `merchant_contact.success` → `merchant_contact.was_successful`
* `return.success` → `return.was_successful`
* `refund.promised` → `refund.was_promised`
* `card.active` → `card.is_active`

**Other field renames:**

* `cardholder_message` → `cardholder_explanation`
* `explanation` → `issuer_explanation`
* `merchant_contact.prohibited_description` → `merchant_contact.prohibited_reason`