# Migrate from v1 to v2 Document API version

**URL:** <https://community.getswipe.in/t/migrate-from-v1-to-v2-document-api-version/2691>\
**Category:** API Integration\
**Created:** [March 29, 2025, 9:26am UTC](https://community.getswipe.in/t/migrate-from-v1-to-v2-document-api-version/2691 "2025-03-29T09:26:35Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![swipe](https://avatars.discourse-cdn.com/v4/letter/s/439d5e/32.png) [@swipe](https://community.getswipe.in/u/swipe)\
**Post date:** [March 29, 2025, 9:26am UTC](https://community.getswipe.in/t/migrate-from-v1-to-v2-document-api-version/2691/1 "2025-03-29T09:26:35Z")

</div>

# Overview

This guide provides a detailed migration path from [v1 Create a Document](https://developers.getswipe.in/api-reference/document/create-a-document) to [v2 Create a Document](https://developers.getswipe.in/api-reference/document-v2/create-a-document). It highlights key differences and necessary updates to ensure a smooth transition.

* * *

# Key Changes in V2

## 1. Serial Number Handling

- **v1:**
  - `serial_number` (string)

- **v2:**
  - `serial_number_v2` (object)
    - `prefix`: Prefix for document numbering (e.g., `INV-`)
    - `doc_number`: Numeric sequence (e.g., `1`)
    - `suffix`: Optional suffix (e.g., `-2024`)

### **Action Required:**

- If you do not send `serial_number` explicitly, it will be auto-generated.
- `prefix`, `suffix`, and `doc_number` have been separated in v2.
- If values are provided, the serial number will be formatted as:  
**`prefix + doc_number + suffix`** (e.g., `INV-1-2024`).
- Empty strings can be used for `prefix` and `suffix` if not needed.
- If you require a specific `prefix` but do not want to send `doc_number`, you can omit `doc_number` from the payload. A new `doc_number` will be automatically generated for the given prefix.
- [More details on the schema](https://developers.getswipe.in/api-reference/document-v2/create-a-document#body-serial-number-v2).

* * *

## 2. Customer to Party Migration

- **v1:** `customer`
- **v2:** `party`

### **Action Required:**

- The key name has changed from `customer` to `party`.
- The `party` object must include a `party_type` (`customer` or `vendor`) based on the document type.
- `customer_billing_address` and `customer_shipping_address` are now included in the `party` object as `billing_address` and `shipping_address`.
- [More details on the schema](https://developers.getswipe.in/api-reference/document-v2/create-a-document#body-party).

* * *

## 3. Address Schema Changes

- **v2 Updates:**
  - Added an `addr_id` key (must be between `0` and `999999`).
  - If the provided `addr_id` already exists, the existing address will be updated; otherwise, a new address will be created.

* * *

## 4. Payments and Bank Details

### **Updates:**

- Added `bank_details` inside the `payments` array, allowing different details for each payment.
- `bank_details` provided outside the `payments` key will be used for displaying details on the PDF.
- [More details on the schema](https://developers.getswipe.in/api-reference/document-v2/create-a-document#body-bank-details-account-number).

* * *

## 5. Items

### **Updates:**

- Added support for custom columns using the `custom_columns` key.
- To use `custom_columns` via API, they must first be added in the **[Swipe Portal](https://app.getswipe.in/list/sales?settings=document_settings)**.
- [More details on the schema](https://developers.getswipe.in/api-reference/document-v2/create-a-document#body-items-custom-columns).

* * *

## 6. Additional Charges & Deductions

### **Updates:**

- Added support for additional charges and deductions using the `charges_and_deductions` key (e.g., delivery charges, packing charges, etc.).
- [More details on the schema](https://developers.getswipe.in/api-reference/document-v2/create-a-document#body-charges-and-deductions).

* * *

## 7. Export Fields

### **Updates:**

- Added `currency_id` to `export_invoice_details`.
- [More details on the schema](https://developers.getswipe.in/api-reference/document-v2/create-a-document#body-export-invoice-details-country-id).

* * *

## 8. Document Conversion

### **Updates:**

- Added support for tracking document conversions using the `convert` key.
- Example: Track which quotation was converted into a specific invoice.
- [More details on the schema](https://developers.getswipe.in/api-reference/document-v2/create-a-document#body-convert).

* * *

## 9. Document Custom Headers Support

### **Updates:**

- Added support for custom document headers using the `custom_headers` key.
- To enable this feature, document headers must first be added in the **[Swipe Portal](https://app.getswipe.in/list/sales?settings=document_settings)**.
- [More details on the schema](https://developers.getswipe.in/api-reference/document-v2/create-a-document#body-custom-headers).

* * *

# Summary of Required Updates

| **V1 Field** | **Action Required** | **V2 Field** |
| --- | --- | --- |
| `serial_number` | Use `serial_number_v2` | `serial_number_v2` |
| `customer` | Replace with `party` | `party` |
| All address fields | Add `addr_id` key in each address | All address fields |
| `items` | Introduce `custom_columns` if needed | `items` |
| Additional charges (N/A) | Introduce if applicable | `charges_and_deductions` |
| Document custom headers (N/A) | Introduce if applicable | `custom_headers` |
| Convert documents (N/A) | Introduce if applicable | `convert` |