# API Conventions Source: https://developers.getswipe.in/api-conventions Response format, error handling, dates, IDs, list endpoints, and rate limits - the rules every Swipe API endpoint follows. The rules on this page apply to every endpoint, so the reference pages don't repeat them. ## Requests * Base URL: `https://app.getswipe.in/api/partner` (see [Authentication](/authentication)) * Request and response bodies are JSON — send `Content-Type: application/json` * All dates use the **`DD-MM-YYYY`** format (for example `26-08-2026`), in requests and responses alike ## Rate limit The API accepts up to **1 request per second** per API key. For bulk work — syncing a catalog, importing customers — send requests sequentially and space them out rather than firing them in parallel. If a request is rejected because of the limit, wait and retry with backoff. ## Response format Every endpoint that returns JSON wraps its result in the same envelope: ```json theme={null} { "success": true, "message": "Document created successfully", "error_code": "", "errors": {}, "data": { } } ``` * `success` — `true` when the request worked; check this first * `message` — human-readable summary of what happened * `error_code` — empty on success; a stable machine-readable code on failure * `errors` — field-level details when validation fails * `data` — the actual result (a document, a list, identifiers, and so on) File endpoints (such as [Get document PDF](/api-reference/document-v2/get-document-pdf)) return the file itself instead of JSON. ## Error handling Failed requests return the same envelope with `success: false`: ```json theme={null} { "success": false, "message": "The provided hash ID is invalid.", "error_code": "INVALID_HASH_ID", "errors": {} } ``` | HTTP status | Meaning | | ----------- | ------------------------------------------------------------------------------- | | `200` | Request succeeded | | `400` | The request is invalid — inspect `error_code` and fix the payload | | `401` | Authentication failed — see [Authentication](/authentication) | | `500` | Something went wrong on Swipe's side — retry with backoff, then contact support | Handle errors by `error_code`, not by matching `message` text — messages can change, codes are stable. The full catalog is on the [Error codes](/api-reference/error-codes) page. E-invoice and e-way bill failures surface government portal errors as `PORTAL_ERROR_{code}`. ## IDs: yours and Swipe's Two kinds of identifiers appear throughout the API: * **Your IDs** — the `id` you send for customers, vendors, and products (for example `CUST001`). Swipe maps them to its own records: send a new ID and the record is created automatically; send an existing ID and it's reused. The mapping endpoints ([customers](/api-reference/customer-v2/update-customer-mapping), [products](/api-reference/product-v2/update-items-mapping)) let you re-link these later. * **`hash_id`** — Swipe's identifier for a document, returned when you create one. It's the address for everything you do with that document afterwards: [get](/api-reference/document-v2/get-a-document), [edit](/api-reference/document-v2/edit-a-document), [cancel](/api-reference/document-v2/cancel-a-document), and [PDF](/api-reference/document-v2/get-document-pdf). ## Retries and duplicates Requests that create data are **not idempotent** — retrying a timed-out create request can create a second record. To stay safe: * Send your own `serial_number` when creating documents. If the first attempt actually succeeded, the retry fails with `DUPLICATE_DOC_SERIAL_NUMBER` instead of creating a duplicate. * Retry only on network errors and `500` responses, never on `400` — a validation error will fail the same way again until the payload changes. ## List endpoints List endpoints (documents, payments, ledgers) are filtered by a required date range: * `start_date` and `end_date` — `DD-MM-YYYY`, both required * Document lists also require `document_type` (for example `invoice`) * Some lists accept additional filters such as `payment_status` — see each endpoint's reference page Keep date ranges as narrow as your use case allows; requesting a year of documents in one call returns a large response. # Change Log Source: https://developers.getswipe.in/api-reference/change-log Updates and changes to the Swipe API The documentation got a full overhaul: * New [Quickstart](/quickstart), [Authentication](/authentication), and [API conventions](/api-conventions) pages — including the documented rate limit of **1 request per second** * Every guide rewritten around lifecycles and real payloads, with new [Vendors](/vendor) and [Inventory](/inventory) guides and the [subscription creation flow](/subscriptions#create-a-subscription) * A description on every endpoint, an upgraded [error reference](/api-reference/error-codes) with causes and resolutions, and playground examples that now show the minimal required payload * Every page can be copied as Markdown or opened in ChatGPT / Claude / Cursor from the contextual menu, and the docs are published as [llms.txt](https://developers.getswipe.in/llms.txt) for AI tools Added the `ship_to_gstin` field to [Create e-way bill](/api-reference/ewaybill/create-eway-bill) — the consignee's GSTIN (or `URP` for unregistered), required for Bill To – Ship To transactions. Added the `send_wtsp` flag to `subscription_details` in [Create a document](/api-reference/document-v2/create-a-document) — generated subscription invoices can now be delivered to the customer on WhatsApp, alongside the existing `send_email` and `send_sms`. Documented the `product_images` support on item endpoints — attach image URLs to catalog items. Added the `visibility` key on items: `1` makes the product visible to all branches, `0` restricts it to the branch it was created in. Added the `record_time` field to document payloads for capturing the time of the record alongside its date. Added the `delivery_challan` query parameter to [Get document PDF](/api-reference/document-v2/get-document-pdf) — set it to `1` to download a delivery-challan copy of the document. Added the `subscription_details` and `convert` keys to [Edit a document](/api-reference/document-v2/edit-a-document) — update a subscription's schedule, or convert an existing document to another type. Added Payload Validation for all Product and Customer Endpoints # Add a customer Source: https://developers.getswipe.in/api-reference/customer-v2/add-a-customer post /v2/customer Creates a customer keyed by your own `id`. Sending an ID that already exists fails with `CUSTOMER_ALREADY_EXISTS` — use Update a customer to change an existing record. Customers are also created automatically when a document references an unknown `party.id`. # Delete a customer Source: https://developers.getswipe.in/api-reference/customer-v2/delete-a-customer delete /v2/customer/{customer_id} Deletes a customer by your `customer_id`. Deleted customers move to the Deleted tab in the dashboard. # Get customer details Source: https://developers.getswipe.in/api-reference/customer-v2/get-customer-details get /v2/customer/{customer_id} Returns one customer's details by your `customer_id`. # Get list of customers Source: https://developers.getswipe.in/api-reference/customer-v2/get-list-of-customers get /v2/customer/list Lists your customers with their basic details. # Get payment ledger Source: https://developers.getswipe.in/api-reference/customer-v2/get-payment-ledger get /v2/customer/ledger Returns a customer's payment ledger over a required date range — documents, payments, and the running balance. # Update a customer Source: https://developers.getswipe.in/api-reference/customer-v2/update-a-customer put /v2/customer Updates an existing customer's details. Changes propagate to the documents linked to this customer. # Update customer mapping Source: https://developers.getswipe.in/api-reference/customer-v2/update-customer-mapping post /v2/customer/list Re-links your customer IDs to existing Swipe records in bulk. Use this after changing IDs in your own system, so future calls don't create duplicate customers. # Cancel a document Source: https://developers.getswipe.in/api-reference/document-v2/cancel-a-document delete /v2/doc/{doc_hash_id} Cancels an active document by its `hash_id`. The document remains in your account with a cancelled status. # Create a document Source: https://developers.getswipe.in/api-reference/document-v2/create-a-document post /v2/doc Creates a document — an invoice, purchase, estimate, return, delivery challan, or subscription — based on `document_type`. Unknown `party` and `items` IDs are created automatically from the details you send; existing IDs are reused. Returns the document's `hash_id`, which addresses the document in every subsequent call, plus the IRN and QR code when `einvoice` is set. Send your own `serial_number` to make retries safe — a duplicate fails with `DUPLICATE_DOC_SERIAL_NUMBER` instead of creating a second document. Customer id and Product id should be unique, if a new id is sent, a new Customer/Product with given details will be automatically created. For Product If an existing id is sent, the details will not override the original product details. They will be applicable only to the current document. For updating the product details, use the update product API # Edit a document Source: https://developers.getswipe.in/api-reference/document-v2/edit-a-document put /v2/doc/{doc_hash_id} Replaces the contents of an existing document. Send the complete payload with every field's updated value — this is a full replacement, not a partial update. The document keeps its `hash_id`. To update a document, include the document's unique `doc_hash_id` in the request URL and send all the keys with their updated values in the request body, ensuring the document is updated correctly with the provided data. # Get a document Source: https://developers.getswipe.in/api-reference/document-v2/get-a-document get /v2/doc/{doc_hash_id} Returns the full details of a document by its `hash_id` — party, items, amounts, and status. # Get document PDF Source: https://developers.getswipe.in/api-reference/document-v2/get-document-pdf get /v2/doc/pdf/{doc_hash_id} Returns the rendered PDF file for a document. The PDF uses the invoice templates and document settings configured on your Swipe account. Pass `delivery_challan=1` to get a delivery-challan copy instead. # List of documents Source: https://developers.getswipe.in/api-reference/document-v2/list-of-documents get /v2/doc/list Lists documents of one `document_type` within a required date range. Filter by `payment_status` to track pending, partially paid, or fully paid documents. # Error Codes Source: https://developers.getswipe.in/api-reference/error-codes Every error code the Swipe API returns, with its HTTP status, cause, and how to resolve it. Failed requests return the standard [response envelope](/api-conventions#response-format) with `success: false` and a stable `error_code`: ```json theme={null} { "success": false, "message": "The provided hash ID is invalid.", "error_code": "INVALID_HASH_ID", "errors": {} } ``` Handle errors by `error_code`, not by matching `message` text — messages can change, codes are stable. Validation and business errors come with HTTP `400`, authentication failures with `401`, and unexpected failures with `500` (safe to retry with backoff). ## Document errors All returned with HTTP `400`. | Error code | Cause and resolution | | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `HASH_ID_MISSING` | No `hash_id` in the request. Pass the `hash_id` returned when the document was created. | | `INVALID_HASH_ID` | The `hash_id` doesn't match any document. Check for typos, or find it via [List of documents](/api-reference/document-v2/list-of-documents). | | `DUPLICATE_DOC_SERIAL_NUMBER` | A document with this serial number already exists. If this was a retry, the original succeeded — fetch it instead of re-creating. Otherwise use a new serial number. | | `DOCUMENT_TYPE_NOT_FOUND` | Unknown `document_type`. Use one of the values listed in [Documents](/document#the-document-model). | | `INVALID_DOCUMENT_NUMBER` / `INVALID_SERIAL_NUMBER` | The document/serial number is malformed. Check the `serial_number` (or `serial_number_v2`) format. | | `DUPLICATE_SUPPLIER_INVOICE_SERIAL_NUMBER` | A purchase with this supplier invoice serial already exists. | | `FORBIDDEN_USING_BACK_DATE` | Back-dated documents are disabled on your account's settings. Use the current date or change the setting in the dashboard. | | `INVALID_TAX_RATE` | The `tax_rate` is not a valid GST rate. | | `ITEM_NOT_FOUND` | The referenced item doesn't exist. Check the item `id`, or send full item details to auto-create it. | | `CUSTOMER_NOT_FOUND` / `INVALID_CUSTOMER_ID` | The referenced customer doesn't exist or the ID is malformed. Check the `party.id`, or send full party details to auto-create. | | `INSUFFICIENT_STOCK` | The sale would take stock below zero. Add stock via [Inventory](/inventory) or adjust the quantity. | | `BATCH_OR_SERIAL_NUMBER_NOT_SELECTED` | The item is batch/serial tracked; the document must specify which batch or serial numbers move. | | `DUPLICATE_PRODUCT_SERIAL_NUMBER` | This product serial number is already in stock. | | `RETURN_NOT_POSSIBLE_FOR_AVAILABLE_SERIAL_NUMBER` | The serial number being returned is already in stock, so it can't be returned again. | | `CAN_NOT_APPLY_TDS_AND_TCS_TOGETHER` | A document can carry TDS or TCS, not both. Send only one of `tds_id` / `tcs_id` — see [Tax codes](/api-reference/tax-codes). | | `TDS_DETAILS_NOT_FOUND` / `TCS_DETAILS_NOT_FOUND` | The `tds_id` / `tcs_id` doesn't match a known code. Use an ID from [Tax codes](/api-reference/tax-codes). | | `MISSING_BANK_ACCOUNT` / `BANK_DETAILS_MISSING_NON_CASH` | Non-cash payments need a bank account configured on your Swipe account. Add one in the dashboard. | | `AMOUNT_RECEIVED_GREATER_THAN_TOTAL_AMOUNT` | The payment amount exceeds the document total. Reduce `amount_received` / `amount_paying`. | | `SUBSCRIPTIONS_NOT_ENABLED` | Enable subscriptions in the [dashboard](https://app.getswipe.in/list/subscriptions) before creating `document_type=subscription`. | | `SUBSCRIPTION_DETAILS_NOT_FOUND` | `document_type=subscription` needs a `subscription_details` object — see [Subscriptions](/subscriptions#create-a-subscription). | | `INVALID_REPEAT` | `subscription_details.repeat` / `repeat_type` is invalid. Use a positive number with one of `days`, `weeks`, `months`, `years`. | | `INVALID_CUSTOM_COLUMN_VALUE` / `INVALID_HEADER_FORMAT` | A custom column value or custom header doesn't match the columns configured on your account. | | `EINVOICE_NOT_FOUND` | No e-invoice exists for this document. Generate one by creating the document with `einvoice: true`. | | `FREE_USER_EXPORT_LIMIT_EXCEEDED` | Export document limit on the free plan reached. Upgrade the account to continue. | ## E-invoice and e-way bill portal errors | Error code | Cause and resolution | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PORTAL_ERROR_{code}` | The government portal rejected the request; `{code}` is the portal's own error number (for example `PORTAL_ERROR_2247`). Look the code up in the [official e-invoice error list](https://einv-apisandbox.nic.in/api-error-codes-list.html) — common causes are GSTIN mismatches, wrong state codes, and duplicate IRNs. | ## Customer, vendor, and product errors All returned with HTTP `400`. | Error code | Cause and resolution | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `CUSTOMER_ALREADY_EXISTS` | A customer with this `id` already exists. Use [Update a customer](/api-reference/customer-v2/update-a-customer) instead of adding again. | | `CUSTOMER_NOT_FOUND` | No customer with this `customer_id`. Check the ID or list customers to find it. | | `INVALID_CUSTOMER_ID` | The `customer_id` is malformed. | | `PRODUCT_ALREADY_EXISTS` | An item with this `id` already exists. Use [Update an item](/api-reference/product-v2/update-an-item) instead of adding again. | ## Authentication errors Returned with HTTP `401` — see [Authentication](/authentication). | Error code | Cause and resolution | | -------------- | -------------------------------------------------------------------------------------------------- | | `UNAUTHORIZED` | The API key is missing, malformed, or invalid. Send `Authorization: Bearer YOUR_API_KEY`. | | `FORBIDDEN` | The key is valid but not allowed to perform this action. Check the account's plan and permissions. | ## General errors | Error code | HTTP status | Cause and resolution | | --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `BAD_REQUEST` | `400` | The request is malformed — invalid JSON, wrong types, or missing required fields. Check `errors` for field-level details. | | `UNKNOWN_ERROR` | `500` | Something failed on Swipe's side. Retry with backoff; if it persists, contact [support](https://app.getswipe.in/user?tab=api_integration) with the request details. | # Create e-way bill Source: https://developers.getswipe.in/api-reference/ewaybill/create-eway-bill post /v2/ewaybill/{doc_hash_id} Generates an e-way bill for an existing document, identified by its `hash_id`. Requires the transport details: supply type, transport mode, dispatch addresses, and transporter document date. Your account must be connected to the e-way bill portal; portal rejections are returned as `PORTAL_ERROR_{code}`. By default this points to the government sandbox portal. To create an EwayBill first connect to [EwayBill Portal](https://app.getswipe.in/ewaybills). # Get e-way bill PDF Source: https://developers.getswipe.in/api-reference/ewaybill/get-ewaybill-pdf get /v2/ewaybill/pdf/{doc_hash_id} Returns the e-way bill PDF for a document whose e-way bill has already been generated. # Get all warehouses Source: https://developers.getswipe.in/api-reference/inventory-v2/get-all-warehouses get /v2/inventory/warehouses/list Returns all warehouses with their IDs, for use in stock operations. # Update inventory stock Source: https://developers.getswipe.in/api-reference/inventory-v2/inventory-stock-in-out post /v2/inventory/stock Records a manual stock movement for a product — `in` adds stock, `out` removes it. Use `warehouse_id` -1 for the default warehouse and `record_date` to backdate the movement. Sales and purchase documents also move stock automatically. # List of payments Source: https://developers.getswipe.in/api-reference/payment-v2/list-of-payments get /v2/payment/list Lists payments recorded within a required date range. # Record payment Source: https://developers.getswipe.in/api-reference/payment-v2/record-payment post /v2/payment Records a payment received from a customer. Optionally settle specific documents by pairing each `hash_id` with an `amount_paying` — partial settlement is supported and the document's payment status tracks what remains. Non-cash payment modes need a bank account configured on your account, otherwise the request fails with `MISSING_BANK_ACCOUNT`. Set `send_sms` or `send_email` to notify the customer. # Add an item Source: https://developers.getswipe.in/api-reference/product-v2/add-an-item post /v2/product Creates an item in your catalog keyed by your own `id`. Sending an ID that already exists fails with `PRODUCT_ALREADY_EXISTS` — use Update an item to change the catalog record. Items are also created automatically when a document references an unknown item `id`. **Uploading Product Images** To upload product images, use `multipart/form-data` instead of `application/json`. All the regular JSON fields are supported as form fields, plus: * `product_images`: Array of image files (JPEG, PNG, etc.) * For complex fields like `custom_columns`, `alternative_units`, and `preferences`, send them as JSON strings # Delete an item Source: https://developers.getswipe.in/api-reference/product-v2/delete-an-item delete /v2/product/{item_id} Deletes an item by your `item_id`. Deleted items move to the Deleted tab in the dashboard. # Get item details Source: https://developers.getswipe.in/api-reference/product-v2/get-item-details get /v2/product/{item_id} Returns one item's catalog details by your `item_id`. # Get list of items Source: https://developers.getswipe.in/api-reference/product-v2/get-list-of-items get /v2/product/list Lists the items in your catalog. # Update an item Source: https://developers.getswipe.in/api-reference/product-v2/update-an-item put /v2/product Updates an item's master record in the catalog. This is the only way to change catalog details — item fields sent inside a document apply to that document only. **Uploading Product Images** To upload or update product images, use `multipart/form-data` instead of `application/json`. All the regular JSON fields are supported as form fields, plus: * `product_images`: Array of image files (JPEG, PNG, etc.) * For complex fields like `custom_columns`, `alternative_units`, and `preferences`, send them as JSON strings # Update items mapping Source: https://developers.getswipe.in/api-reference/product-v2/update-items-mapping post /v2/product/list Re-links your item IDs to existing Swipe records in bulk. Use this after changing IDs in your own system, so future calls don't create duplicate items. # Currencies, States & Countries Source: https://developers.getswipe.in/api-reference/reference-data Accepted currency codes, Indian state names, and country names for API requests. ## Currency Details | **Country Name** | **Currency ID** | **Currency Name** | | -------------------------------- | --------------- | --------------------------------------- | | Zimbabwe | ZWL | Zimbabwean dollar | | Zambia | ZMW | Zambian kwacha | | South Africa | ZAR | South African rand | | Yemen | YER | Yemeni rial | | Jersey | GBP | British pound | | Samoa | WST | Samoan tālā | | Vanuatu | VUV | Vanuatu vatu | | Vietnam | VND | Vietnamese đồng | | Venezuela | VEF | Venezuelan bolívar | | Saint Vincent And The Grenadines | XCD | East Caribbean dollar | | Uzbekistan | UZS | Uzbekistani Som | | Uruguay | UYU | Uruguayan peso | | United States | USD | United States dollar | | Uganda | UGX | Ugandan shilling | | Ukraine | UAH | Ukrainian hryvnia | | Tanzania | TZS | Tanzanian shilling | | Taiwan | TWD | New Taiwan dollar | | Tuvalu | AUD | Australian dollar | | Trinidad And Tobago | TTD | Trinidad and Tobago dollar | | Turkey | TRY | Turkish lira | | East Timor | USD | United States dollar | | Tonga | TOP | Tongan paʻanga | | Tunisia | TND | Tunisian dinar | | Turkmenistan | TMT | Turkmenistan manat | | Tajikistan | TJS | Tajikistani somoni | | Thailand | THB | Thai baht | | Togo | XOF | West African CFA franc | | Chad | XAF | Central African CFA franc | | Turks And Caicos Islands | USD | United States dollar | | Swaziland | SZL | Swazi lilangeni | | El Salvador | USD | United States dollar | | Sao Tome and Principe | STD | São Tomé and Príncipe dobra | | South Sudan | SSP | South Sudanese pound | | Suriname | SRD | Surinamese dollar | | Somalia | SOS | Somali shilling | | Senegal | XOF | West African CFA franc | | San Marino | EUR | Euro | | Sierra Leone | SLL | Sierra Leonean leone | | Sri Lanka | LKR | Sri Lanka Rupee | | Slovakia | EUR | Euro | | Slovenia | EUR | Euro | | Saint Helena | SHP | Saint Helena pound | | Singapore | SGD | Singapore Dollar | | Sweden | SEK | Swedish krona | | Sudan | SDG | Sudanese pound | | Solomon Islands | SBD | Solomon Islands dollar | | Saudi Arabia | SAR | Saudi riyal | | Rwanda | RWF | Rwandan franc | | Russia | RUB | Russian Ruble | | Serbia | RSD | Serbian Dinar | | Romania | RON | Romanian leu | | Qatar | QAR | Qatari riyal | | Paraguay | PYG | Paraguayan guaraní | | Palau | | Palauan dollar | | Portugal | EUR | Euro | | Palestine | PSP | Palestine pound | | Puerto Rico | USD | US Dollar | | Poland | PLN | Polish złoty | | Pakistan | PKR | Pakistani rupee | | Philippines | PHP | Philippine peso | | Papua new Guinea | PGK | Papua New Guinean kina | | French Polynesia | XPF | CFP franc | | Peru | PEN | Peruvian nuevo sol | | Panama | PAB | Panamanian balboa | | Oman | OMR | Omani rial | | New Zealand | NZD | New Zealand dollar | | Niue | NZD | New Zealand dollar | | Nauru | AUD | Australian dollar | | Nepal | NPR | Nepalese rupee | | Norway | NOK | Norwegian krone | | Netherlands | EUR | Euro | | Nicaragua | NIO | Nicaraguan córdoba | | Nigeria | NGN | Nigerian naira | | Niger | XOF | West African CFA franc | | New Caledonia | XPF | CFP franc | | Namibia | NAD | Namibian dollar | | Mozambique | MZN | Mozambican metical | | Malaysia | MYR | Malaysian ringgit | | Mexico | MXN | Mexican peso | | Malawi | MWK | Malawian kwacha | | Maldives | MVR | Maldivian rufiyaa | | Mauritius | MUR | Mauritian rupee | | Malta | EUR | Euro | | Montserrat | XCD | East Caribbean dollar | | Mauritania | MRO | Mauritanian ouguiya | | Mongolia | MNT | Mongolian tögrög | | Myanmar | MMK | Burmese kyat | | Mali | XOF | West African CFA franc | | Marshall Islands | USD | United States dollar | | Madagascar | MGA | Malagasy ariary | | Moldova | MDL | Moldovan leu | | Monaco | EUR | Euro | | Morocco | MAD | Moroccan dirham | | Libya | LYD | Libyan dinar | | Latvia | EUR | Euro | | Luxembourg | EUR | Euro | | Lithuania | EUR | Euro | | Lesotho | LSL | Lesotho loti | | Liberia | LRD | Liberian dollar | | Liechtenstein | CHF | Swiss franc | | Saint Lucia | XCD | East Caribbean dollar | | Lebanon | LBP | Lebanese pound | | Laos | LAK | Lao kip | | Kazakhstan | KZT | Kazakhstani Tenge | | Cayman Islands | KYD | Cayman Islands dollar | | Kuwait | KWD | Kuwaiti dinar | | Republic of Korea (South Korea) | KRW | South Korean Won | | Saint Kitts And Nevis | XCD | East Caribbean dollar | | Comoros | KMF | Comorian franc | | Kiribati | AUD | Australian dollar | | Cambodia | KHR | Cambodian riel | | Kyrgyzstan | KGS | Kyrgyzstani som | | Kenya | KES | Kenyan shilling | | Japan | JPY | Japanese yen | | Jordan | JOD | Jordanian dinar | | Jamaica | JMD | Jamaican dollar | | Italy | EUR | Euro | | Iceland | ISK | Icelandic króna | | Iran | IRR | Iranian rial | | Iraq | IQD | Iraqi dinar | | British Indian Ocean Territory | USD | United States dollar | | India | INR | Indian rupee | | Isle of Man | IMP | Isle of Man Pound | | Israel | ILS | Israeli new shekel | | Ireland | EUR | Euro | | Indonesia | IDR | Indonesian rupiah | | Hungary | HUF | Hungarian forint | | Haiti | HTG | Haitian gourde | | Croatia | HRK | Croatian kuna | | Honduras | HNL | Honduran lempira | | Hong Kong | HKD | Hong Kong Dollar | | Egypt | EGP | Egyptian pound | | Guyana | GYD | Guyanese dollar | | Guinea-Bissau | XOF | West African CFA franc | | Guatemala | GTQ | Guatemalan quetzal | | Greece | EUR | Euro | | Equatorial Guinea | XAF | Central African CFA franc | | Guinea | GNF | Guinean franc | | Gibraltar | GIP | Gibraltar pound | | Ghana | GHS | Ghana cedi | | Georgia | GEL | Georgian lari | | Grenada | XCD | East Caribbean dollar | | United Kingdom | GBP | British pound | | Gabon | XAF | Central African CFA franc | | France | EUR | Euro | | Faroe Islands | DKK | Danish krone | | Micronesia | | Micronesian dollar | | Falkland Islands | FKP | Falkland Islands pound | | Finland | EUR | Euro | | Ethiopia | ETB | Ethiopian birr | | Spain | EUR | Euro | | Eritrea | ERN | Eritrean nakfa | | Estonia | EUR | Euro | | Ecuador | USD | United States dollar | | Algeria | DZD | Algerian dinar | | Dominican Republic | DOP | Dominican peso | | Dominica | XCD | East Caribbean dollar | | Denmark | DKK | Danish krone | | Djibouti | DJF | Djiboutian franc | | Germany | EUR | Euro | | Czech Republic | CZK | Czech koruna | | Cyprus | EUR | Euro | | Curacao | ANG | Antillean Guilder | | Cuba | CUC | Cuban convertible peso | | Costa Rica | CRC | Costa Rican colón | | Colombia | COP | Colombian peso | | Cameroon | XAF | Central African CFA franc | | Chile | CLP | Chilean peso | | Cook Islands | NZD | New Zealand dollar | | Côte d'Ivoire (Ivory Coast) | XOF | West African CFA franc | | China | CNY | Chinese Yuan | | Switzerland | CHF | Swiss franc | | Democratic Republic of Congo | CDF | Congolese Franc | | Central African Republic | XAF | Central African CFA franc | | Canada | CAD | Canadian dollar | | Belize | BZD | Belize dollar | | Belarus | BYR | Belarusian ruble | | Botswana | BWP | Botswana pula | | Bhutan | BTN | Bhutanese ngultrum | | Brazil | BRL | Brazilian real | | Bolivia | BOB | Bolivian boliviano | | Brunei | BND | Brunei dollar | | Bermuda | BMD | Bermudian dollar | | Benin | XOF | West African CFA franc | | Burundi | BIF | Burundian franc | | Bahrain | BHD | Bahraini dinar | | Bulgaria | BGN | Bulgarian lev | | Burkina Faso | XOF | West African CFA franc | | Belgium | EUR | Euro | | Bangladesh | BDT | Bangladeshi taka | | Barbados | BBD | Barbadian dollar | | Bosnia and Herzegovina | BAM | Bosnia and Herzegovina convertible mark | | Azerbaijan | AZN | Azerbaijani Manat | | Aruba | AWG | Aruban florin | | Australia | AUD | Australian dollar | | Austria | EUR | Euro | | Argentina | ARS | Argentine peso | | Angola | AOA | Angolan kwanza | | Armenia | AMD | Armenian dram | | Albania | ALL | Albanian lek | | Anguilla | XCD | East Caribbean dollar | | Antigua And Barbuda | XCD | East Caribbean dollar | | Afghanistan | AFN | Afghan afghani | | United Arab Emirates | AED | United Arab Emirates dirham | | Andorra | EUR | Euro | ## State Details You can copy the following array of state names and use it in your code: Send state values exactly as they appear in this list (including spelling and casing) — they must match the values the API validates against. ```json theme={null} [ "JAMMU AND KASHMIR", "HIMACHAL PRADESH", "PUNJAB", "CHANDIGARH", "UTTARAKHAND", "HARYANA", "DELHI", "RAJASTHAN", "UTTAR PRADESH", "BIHAR", "SIKKIM", "ARUNACHAL PRADESH", "NAGALAND", "MANIPUR", "MIZORAM", "TRIPURA", "MEGHALAYA", "ASSAM", "WEST BENGAL", "JHARKHAND", "ODISHA", "CHHATTISGARH", "MADHYA PRADESH", "GUJARAT", "DADRA & NAGAR HAVELI & DAMAN & DIU", "MAHARASHTRA", "ANDHRAPRADESH(BEFOREADDED)", "KARNATAKA", "GOA", "LAKSHWADEEP", "KERALA", "TAMIL NADU", "PUDUCHERRY", "ANDAMAN & NICOBAR", "TELANGANA", "ANDHRA PRADESH", "LADAKH(NEWLYADDED)", "OTHER TERRITORY" ] ``` ## Country Array Here is the list of countries that you can use in your code: ```json theme={null} [ "Afghanistan", "Albania", "Algeria", "Andorra", "Angola", "Antigua and Barbuda", "Argentina", "Armenia", "Australia", "Austria", "Azerbaijan", "Bahamas", "Bahrain", "Bangladesh", "Barbados", "Belarus", "Belgium", "Belize", "Benin", "Bhutan", "Bolivia", "Bosnia and Herzegovina", "Botswana", "Brazil", "Brunei", "Bulgaria", "Burkina Faso", "Burundi", "Cabo Verde", "Cambodia", "Cameroon", "Canada", "Central African Republic", "Chad", "Chile", "China", "Colombia", "Comoros", "Congo, Democratic Republic of the", "Congo, Republic of the", "Costa Rica", "Croatia", "Cuba", "Cyprus", "Czechia", "Denmark", "Djibouti", "Dominica", "Dominican Republic", "Ecuador", "Egypt", "El Salvador", "Equatorial Guinea", "Eritrea", "Estonia", "Eswatini", "Ethiopia", "Fiji", "Finland", "France", "Gabon", "Gambia", "Georgia", "Germany", "Ghana", "Greece", "Grenada", "Guatemala", "Guinea", "Guinea-Bissau", "Guyana", "Haiti", "Honduras", "Hungary", "Iceland", "India", "Indonesia", "Iran", "Iraq", "Ireland", "Israel", "Italy", "Jamaica", "Japan", "Jordan", "Kazakhstan", "Kenya", "Kiribati", "Korea, North", "Korea, South", "Kosovo", "Kuwait", "Kyrgyzstan", "Laos", "Latvia", "Lebanon", "Lesotho", "Liberia", "Libya", "Liechtenstein", "Lithuania", "Luxembourg", "Madagascar", "Malawi", "Malaysia", "Maldives", "Mali", "Malta", "Marshall Islands", "Mauritania", "Mauritius", "Mexico", "Micronesia", "Moldova", "Monaco", "Mongolia", "Montenegro", "Morocco", "Mozambique", "Myanmar", "Namibia", "Nauru", "Nepal", "Netherlands", "New Zealand", "Nicaragua", "Niger", "Nigeria", "North Macedonia", "Norway", "Oman", "Pakistan", "Palau", "Palestine", "Panama", "Papua New Guinea", "Paraguay", "Peru", "Philippines", "Poland", "Portugal", "Qatar", "Romania", "Russia", "Rwanda", "Saint Kitts and Nevis", "Saint Lucia", "Saint Vincent and the Grenadines", "Samoa", "San Marino", "Sao Tome and Principe", "Saudi Arabia", "Senegal", "Serbia", "Seychelles", "Sierra Leone", "Singapore", "Slovakia", "Slovenia", "Solomon Islands", "Somalia", "South Africa", "South Sudan", "Spain", "Sri Lanka", "Sudan", "Suriname", "Sweden", "Switzerland", "Syria", "Taiwan", "Tajikistan", "Tanzania", "Thailand", "Timor-Leste", "Togo", "Tonga", "Trinidad and Tobago", "Tunisia", "Turkey", "Turkmenistan", "Tuvalu", "Uganda", "Ukraine", "United Arab Emirates", "United Kingdom", "United States", "Uruguay", "Uzbekistan", "Vanuatu", "Vatican City", "Venezuela", "Vietnam", "Yemen", "Zambia", "Zimbabwe" ] ``` # Get subscription details Source: https://developers.getswipe.in/api-reference/subscriptions-v2/get-subscription-details get /v2/subscriptions/{subscription_hash_id} Returns one subscription's details, including the invoices generated from it so far. # List of subscriptions Source: https://developers.getswipe.in/api-reference/subscriptions-v2/list-of-subscriptions get /v2/subscriptions/list Lists subscriptions within a required date range, filterable by `status` and `customer_id`. Subscriptions are created through Create a document with `document_type=subscription`. # Tax Codes (TDS & TCS) Source: https://developers.getswipe.in/api-reference/tax-codes TDS and TCS code IDs to use in the tds_id and tcs_id fields when creating documents. Pass the **ID** from these tables as `tds_id` or `tcs_id` when [creating a document](/api-reference/document-v2/create-a-document). TDS and TCS cannot be applied together on the same document. ## TDS (Tax Deducted at Source) | **ID** | Name | Section | Tax | Apply On | | ------ | ---------------------------------------------------------------------------------------------------- | ------- | ---- | ------------ | | **1** | EPF premature withdrawal | 192A | 10.0 | Net Amount | | **2** | Interest of securities | 193 | 10.0 | Net Amount | | **3** | Dividends | 194 | 10.0 | Net Amount | | **4** | Interest (Banks) | 194A | 10.0 | Net Amount | | **5** | Senior Citizens | 194A | 10.0 | Net Amount | | **6** | Single contractor payment (Individual & HUF) | 194C | 1.0 | Net Amount | | **7** | Aggregate contractor payment (Individual & HUF) | 194C | 1.0 | Net Amount | | **8** | Insurance commission | 194D | 5.0 | Net Amount | | **9** | Insurance commission on Life Insurance policies | 194DA | 5.0 | Net Amount | | **10** | NSS | 194EE | 10.0 | Net Amount | | **11** | Repurchase Units by MFs | 194F | 20.0 | Net Amount | | **12** | Commission – Lottery | 194G | 5.0 | Net Amount | | **13** | Commission/Brokerage | 194H | 5.0 | Net Amount | | **14** | Plant/Equipment/Machinery Rent | 194I(a) | 2.0 | Net Amount | | **15** | Land Building and furniture rent | 194I(b) | 10.0 | Net Amount | | **16** | Transfer of certain immovable property other than agricultural land | 194IA | 1.0 | Net Amount | | **17** | Rent by Individual / HUF | 194IB | 5.0 | Net Amount | | **18** | Payment under specified agreement applicable for F.Y: 2017-18 onwards | 194IC | 10.0 | Net Amount | | **19** | Fees-tech services, call centre, royalty for sale etc. | 194J(a) | 2.0 | Net Amount | | **20** | Fee for professional service or royalty etc.. | 194J(b) | 10.0 | Net Amount | | **21** | Payment of dividends by mutual funds | 194K | 10.0 | Net Amount | | **22** | Compensation on the transfer of certain immovable property other than agricultural land | 194LA | 10.0 | Net Amount | | **23** | Income on infrastructure debt fund(non-resident) | 194LB | 5.0 | Net Amount | | **24** | Income from a business trust (applicable from 01.10.2014) | 194LBA | 10.0 | Net Amount | | **25** | Income from a business trust to non-resident (applicable from 01.10.2014) | 194LBA | 5.0 | Net Amount | | **26** | Interest on certain bonds and Govt. securities (from 01.06.2013) | 194LD | 5.0 | Net Amount | | **27** | Payment to commission or brokerage by individual & HUF | 194M | 5.0 | Net Amount | | **28** | Cash withdrawal exceeding 1 crore during the previous year from 1 or more accounts with a bank or co | 194N | 2.0 | Net Amount | | **29** | TDS on e-commerce participants | 194O | 1.0 | Net Amount | | **30** | Purchase of Goods (Recommended by Income Tax) | 194Q | 0.1 | Total Amount | | **31** | Single contractor payment (Others) | 194C | 2.0 | Net Amount | | **32** | Aggregate contractor payment (Others) | 194C | 2.0 | Net Amount | | **33** | Perquisite or benefit to a business or profession | 194R | 10.0 | Net Amount | | **34** | TDS on the transfer of virtual digital assets | 194S | 1.0 | Net Amount | | **45** | Purchase of Goods (Taxable Amount). Use this on your own discretion. | 194Q | 0.1 | Net Amount | | **49** | Short Term Capital gains under section 111A | 195 | 15.0 | Net Amount | | **50** | Insurance commission on Life Insurance policies - New | 194DA | 2.0 | Net Amount | | **51** | Commission – Lottery - New | 194G | 2.0 | Net Amount | | **52** | TDS on e-commerce participants - New | 194O | 0.1 | Net Amount | | **53** | Commission/Brokerage - New | 194H | 2.0 | Net Amount | ## TCS (Tax Collected at Source) | **ID** | Name | Section | Tax | Apply On | | ------ | ------------------------------------------------------------------------------------------------------ | ----------- | ---- | ------------ | | **35** | TCS upon receivables | 206C(IH) | 0.1 | Total Amount | | **36** | Liquor of alcoholic nature, made for consumption by humans | 206C | 1.0 | Total Amount | | **37** | Timber wood under a forest leased | 206C | 2.5 | Total Amount | | **38** | Tendu leaves | 206C | 5.0 | Total Amount | | **39** | Timber wood by any other mode than forest leased | 206c | 2.5 | Total Amount | | **40** | Forest produce other than Tendu leaves and timber | 206C | 2.5 | Total Amount | | **41** | Scrap | 206C | 1.0 | Total Amount | | **42** | Minerals like lignite, coal and iron ore | 206C | 1.0 | Total Amount | | **43** | Purchase of Motor vehicle exceeding Rs.10 Lakhs | 206C | 1.0 | Total Amount | | **44** | Parking lot, Toll Plaza and Mining and Quarrying | 206C | 2.0 | Total Amount | | **46** | Remittance out of India under the Liberalized Remittance Scheme of RBI | 206C(1G)(a) | 5.0 | Net Amount | | **47** | TCS on selling of overseas tour package | 206C(1G)(b) | 5.0 | Net Amount | | **48** | Collection at source on remittance under LRS except for the purposes of education or medical treatment | 206C | 20.0 | Net Amount | # Get GSTIN details Source: https://developers.getswipe.in/api-reference/utility-v2/get-gstin-v2 get /v2/utils/gstin/{gstin} Looks up a GSTIN on the GST portal and returns the registered business's details. Useful for validating a party's GSTIN and prefilling their name and address. # Add a vendor Source: https://developers.getswipe.in/api-reference/vendor-v2/add-a-vendor post /v2/vendor Creates a vendor keyed by your own `id`. Vendors are the parties on purchase-side documents. They are also created automatically when a document references an unknown vendor `party.id`. # Delete a vendor Source: https://developers.getswipe.in/api-reference/vendor-v2/delete-a-vendor delete /v2/vendor/{vendor_id} Deletes a vendor by your `vendor_id`. Deleted vendors move to the Deleted tab in the dashboard. # Get list of vendors Source: https://developers.getswipe.in/api-reference/vendor-v2/get-list-of-vendors get /v2/vendor/list Lists your vendors with their basic details. # Get payment ledger Source: https://developers.getswipe.in/api-reference/vendor-v2/get-payment-ledger get /v2/vendor/ledger Returns a vendor's payment ledger over a required date range — documents, payments, and the running balance. # Get vendor details Source: https://developers.getswipe.in/api-reference/vendor-v2/get-vendor-details get /v2/vendor/{vendor_id} Returns one vendor's details by your `vendor_id`. # Update a vendor Source: https://developers.getswipe.in/api-reference/vendor-v2/update-a-vendor put /v2/vendor Updates an existing vendor's details. Changes propagate to the documents linked to this vendor. # Update vendor mapping Source: https://developers.getswipe.in/api-reference/vendor-v2/update-vendor-mapping post /v2/vendor/list Re-links your vendor IDs to existing Swipe records in bulk. Use this after changing IDs in your own system, so future calls don't create duplicate vendors. # Authentication Source: https://developers.getswipe.in/authentication How to authenticate Swipe API requests with your API key. All Swipe API requests are authenticated with an API key sent as a Bearer token. ## Base URL Every endpoint in this documentation is relative to: ``` https://app.getswipe.in/api/partner ``` For example, the [Create a document](/api-reference/document-v2/create-a-document) endpoint `POST /v2/doc` resolves to `https://app.getswipe.in/api/partner/v2/doc`. ## Getting your API key 1. Sign in to your [Swipe dashboard](https://app.getswipe.in). 2. Open the [API Integration](https://app.getswipe.in/user?tab=api_integration) section. 3. Generate your API key and copy it. The key is scoped to the **company** you generate it in — every document, customer, and product you create through the API belongs to that company. To test without touching your real books, [add a separate test company](https://community.getswipe.in/t/how-to-add-new-company-on-web/1191), switch to it, and generate a key there; generate a key in your actual company when you go live. ## Using the key Send the key in the `Authorization` header of every request: ```bash theme={null} curl --request GET \ --url https://app.getswipe.in/api/partner/v2/product/list \ --header "Authorization: Bearer YOUR_API_KEY" ``` In the [API playground](/api-reference/document-v2/create-a-document), paste the key into the **Authorization** field and it is applied to every try-it request. ## Authentication errors Requests with a missing or invalid key fail with HTTP `401` and one of these error codes: | `error_code` | Meaning | | -------------- | ------------------------------------------------------------------- | | `UNAUTHORIZED` | The key is missing, malformed, or invalid. Check the header format. | | `FORBIDDEN` | The key is not allowed to perform this action. | See [Error codes](/api-reference/error-codes) for the full list. ## Keeping your key safe Your API key grants full access to your Swipe account's data. Treat it like a password. * Call the API **from your server only** — never embed the key in browser JavaScript, mobile apps, or public repositories. * Store it in an environment variable or a secrets manager, not in source code. * If a key is exposed, regenerate it from the [API Integration](https://app.getswipe.in/user?tab=api_integration) page and update your servers with the new key. # Build with AI Source: https://developers.getswipe.in/build-with-ai Connect Swipe to Claude, Cursor, and other AI tools - MCP servers, machine-readable docs, and a bootstrap prompt. Everything on this page is designed for AI tools: two MCP servers (one to operate Swipe, one to search these docs), machine-readable exports of every page, and a prompt to bootstrap an integration. ## The Swipe MCP server Connect your AI assistant directly to your Swipe account. The server exposes tools to create invoices, search customers and products, record stock movements, analyse reports, and more — your assistant does the work in your account, with your permission. ``` https://app.getswipe.in/api/mcp/sse ``` Authentication is OAuth: when you connect, your browser opens a Swipe login (OTP to your registered mobile), you pick which **company** the connection can access, and the client stays authorized for 30 days. The server includes tools that edit and cancel documents. Connect it to a [test company](https://community.getswipe.in/t/how-to-add-new-company-on-web/1191) while you experiment, the same way you would with a test API key. ### Connecting In [claude.ai](https://claude.ai) or the Claude desktop app: **Settings → Connectors → Add custom connector**, then paste the server URL. Claude walks you through the OTP login and company selection. ```bash theme={null} claude mcp add --transport http swipe https://app.getswipe.in/api/mcp/sse ``` Then run `/mcp` inside Claude Code to complete the OAuth login. Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in your project): ```json theme={null} { "mcpServers": { "swipe": { "url": "https://app.getswipe.in/api/mcp/sse" } } } ``` Cursor prompts for the OAuth login on first use. ### Available tools The exact list can vary with your company's plan and enabled features. Tools are annotated so clients know what's safe: | Read-only | Adds records | Edits or cancels records | | --------------------------- | --------------------- | --------------------------------- | | List Transactions | Create Document | Edit Document | | Get Document Details | Log Expense | Cancel Document | | Search Products | Add Product | Update Product | | Search Customers & Vendors | Add Customer | Update Customer | | Search HSN Codes | Add Vendor | Update Company Name / GSTIN | | Search GST Rate Changes | Record Stock In / Out | Update Company / Invoice Settings | | Analyse Financial Reports | | Get or Update Document Prefix | | Analyse Product Performance | | | | List Expense Categories | | | ## The docs MCP server A separate, unauthenticated server that gives AI tools **search and retrieval over this documentation** — useful while coding an integration, without connecting a Swipe account: ``` https://developers.getswipe.in/mcp ``` Add it the same way as above (for Claude Code: `claude mcp add --transport http swipe-docs https://developers.getswipe.in/mcp`), or use the contextual menu on any page of these docs — the copy/open options next to each page title connect the current page to ChatGPT, Claude, Cursor, or VS Code directly. ## Machine-readable documentation | Resource | URL | | ----------------------- | ---------------------------------------------------------------------------------------------- | | Docs index for AI tools | [`/llms.txt`](https://developers.getswipe.in/llms.txt) | | Entire docs as one file | [`/llms-full.txt`](https://developers.getswipe.in/llms-full.txt) | | Any page as Markdown | append `.md` to its URL, e.g. [`/quickstart.md`](https://developers.getswipe.in/quickstart.md) | | OpenAPI 3.0.1 spec | [`/api-reference/openapi.json`](https://developers.getswipe.in/api-reference/openapi.json) | ## Bootstrap prompt Starting an integration with an AI coding assistant? Paste this in first: ```text theme={null} You are helping me integrate the Swipe Partner API (Indian GST invoicing). - Base URL: https://app.getswipe.in/api/partner - Auth: Authorization: Bearer (keys are company-scoped; I'm using a test company) - Rate limit: 1 request/second — make calls sequentially - All dates are DD-MM-YYYY - Full API spec: https://developers.getswipe.in/api-reference/openapi.json - Docs index: https://developers.getswipe.in/llms.txt - Responses use the envelope {success, message, error_code, errors, data}; handle failures by error_code, not message text - Documents (invoices etc.) are addressed by the hash_id returned at creation Start by creating a minimal invoice (POST /v2/doc with document_type, document_date, party, items), then fetch its PDF (GET /v2/doc/pdf/{hash_id}) to verify the flow works. ``` # Customers Source: https://developers.getswipe.in/customer Manage customer records, keep your IDs mapped to Swipe, and pull payment ledgers. Customers are the parties you sell to. They appear as the `party` (type `customer`) on invoices, estimates, sales returns, and other sales-side [documents](/document), and every customer carries a running balance you can read as a ledger. ## Your IDs, mapped to Swipe Every customer API call uses **your** `customer_id` — the ID from your own system. Swipe keeps a mapping between your IDs and its records: * **New ID** → the customer is created automatically from the details you send. This also happens inline when you [create a document](/api-reference/document-v2/create-a-document) with an unknown `party.id` — you rarely need to pre-create customers. * **Existing ID** → the record is reused. If the details you send differ, the customer is updated, and existing documents linked to them reflect the change. * **Changed your IDs?** [Update customer mapping](/api-reference/customer-v2/update-customer-mapping) re-links your new IDs to the existing Swipe records in bulk, so you don't end up with duplicates after a migration. ## Add a customer ```bash theme={null} curl --request POST \ --url https://app.getswipe.in/api/partner/v2/customer \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "id": "CUST001", "name": "Test Customer", "phone_number": "1234567890", "email": "customer@example.com", "gstin": "27AARCS7202C1ZD" }' ``` Include `gstin` for registered businesses — it drives GST treatment on their invoices. Billing and shipping addresses use the state and country values listed in [Currencies, States & Countries](/api-reference/reference-data). ## The payment ledger [Get payment ledger](/api-reference/customer-v2/get-payment-ledger) returns a customer's transaction history — invoices, payments, and the resulting balance — over a date range. It's the API equivalent of the customer ledger in the dashboard. Customer list in the Swipe dashboard ## Endpoints Create a customer with your own ID. Fetch one customer by your `customer_id`. Change a customer's details. Remove a customer record. Transaction history and balance for one customer. Page through all customers. Re-link your IDs to Swipe records in bulk. Buying from someone instead? See [Vendors](/vendor) — the purchase-side mirror of this API. # Documents Source: https://developers.getswipe.in/document Create, edit, cancel, list, and download the business documents at the core of the Swipe API. Documents are the core resource of the Swipe API. An invoice, a purchase, an estimate, a sales return — they're all documents, created through one endpoint and addressed by one identifier. ## The document model Every document is created with [`POST /v2/doc`](/api-reference/document-v2/create-a-document). The `document_type` field decides what you're creating: | `document_type` | Use for | | ------------------- | --------------------------------------------------------- | | `invoice` | A standard GST sales invoice | | `purchase` | A purchase recorded against a vendor | | `estimate` | A quotation for a customer | | `pro_forma_invoice` | A pro forma invoice sent before the real one | | `sales_return` | Goods returned by a customer (credit note) | | `purchase_return` | Goods returned to a vendor (debit note) | | `delivery_challan` | Goods movement without a sale | | `subscription` | A recurring invoice — see [Subscriptions](/subscriptions) | Sales-side documents take a `party` of type `customer`; purchase-side documents (`purchase`, `purchase_return`) take a `party` of type `vendor`. ## The document lifecycle ```mermaid theme={null} flowchart LR A["Create
POST /v2/doc"] --> B["hash_id"] B --> C["Get / PDF"] B --> D["Edit
PUT /v2/doc/{hash_id}"] B --> E["Cancel
DELETE /v2/doc/{hash_id}"] B --> F["Record payment
POST /v2/payment"] ``` The `hash_id` returned on creation is the document's address for everything that follows — fetching it, editing it, cancelling it, downloading its PDF, generating an [e-way bill](/ewaybills) for it, or settling it with a [payment](/payment). ```json theme={null} { "success": true, "message": "Document created successfully", "data": { "hash_id": "PUlgCNPb", "serial_number": "INV-1" } } ``` For a complete first request, follow the [Quickstart](/quickstart) — it creates an invoice and downloads its PDF in two calls. ## Things to know before you build **Customers and products are auto-created.** The `party` and `items` in your payload carry your own IDs. If an ID is new, Swipe creates the record from the details you send; if it exists, the record is reused. See [API conventions](/api-conventions#ids-yours-and-swipes). * **Party updates propagate.** If you send changed details for an existing party ID, the party is updated — and existing documents linked to that party reflect the change. * **Item details in a document don't update the catalog.** Sending different details for an existing item ID applies them to that document only; use [Update an item](/api-reference/product-v2/update-an-item) to change the master record. * **Serial numbers must be unique.** Send your own `serial_number` (or `serial_number_v2`) and a retried create fails safely with `DUPLICATE_DOC_SERIAL_NUMBER` instead of duplicating the document. * **Edits replace the document.** [Edit a document](/api-reference/document-v2/edit-a-document) expects the full payload with every field's updated value, not a partial diff. * **E-invoices ride on creation.** Pass `einvoice: true` when creating to also generate a GST e-invoice with IRN and QR code — see [E-Invoices](/einvoices). ## Documents in the dashboard Everything the API creates appears in the [Swipe dashboard](https://app.getswipe.in/list/sales) alongside documents made in the app — the invoice creation screen below works on the same data. Create Invoice screen in the Swipe dashboard ## Endpoints The full payload — items, taxes, discounts, charges, export details. Fetch a document's details by `hash_id`. Download the rendered PDF. Replace a document's contents by `hash_id`. Cancel an active document. List documents by type, date range, and payment status. # E-Invoices Source: https://developers.getswipe.in/einvoices Generate GST e-invoices with IRN and QR code as part of document creation. An e-invoice is a GST invoice registered with the government portal, which assigns it an IRN (Invoice Reference Number) and QR code. In the Swipe API, e-invoicing is a flag on [document creation](/api-reference/document-v2/create-a-document) — not a separate endpoint. ## Before you start E-invoice APIs need the **E-Invoices & EwayBills plan** on your account. Mail [api@getswipe.in](mailto:api@getswipe.in) for a trial and integration support. Open [E-invoices in your dashboard](https://app.getswipe.in/einvoices) and click **Connect to E-Invoice Portal**. By default the API points to the **Government sandbox portal** — generated e-invoices aren't legally valid until you switch. Mail [api@getswipe.in](mailto:api@getswipe.in) to connect to the production portal. ## Generate an e-invoice Create the document as usual and set `einvoice: true`. The response then carries the government-issued identifiers alongside the normal document fields: ```json theme={null} { "success": true, "message": "Document created successfully", "data": { "hash_id": "PUlgCNPb", "serial_number": "INV-1", "irn": "35054cc24d1b3ad27b1b3aabf4966a1ae0d663fdb98f5b2f2fdbd5b0f0d5a133", "qr_code": "..." } } ``` For a valid e-invoice the government portal needs correct GST data — the party's `gstin`, item `hsn_code`s, and address state values from [Currencies, States & Countries](/api-reference/reference-data). Portal rejections come back as `PORTAL_ERROR_{code}` — see [Error codes](/api-reference/error-codes). ## Download the PDF The e-invoice PDF (with its QR code) comes from the standard [Get document PDF](/api-reference/document-v2/get-document-pdf) endpoint using the document's `hash_id`. ## Endpoints Set `einvoice: true` in the create payload. Download the e-invoice PDF. # E-Way Bills Source: https://developers.getswipe.in/ewaybills Generate GST e-way bills for your documents and download their PDFs. An e-way bill is the GST transport document required for moving goods. In the Swipe API, an e-way bill is generated **for an existing document** — create the invoice first, then request its e-way bill with the transport details. ## Before you start E-way bill APIs need the **E-Invoices & EwayBills plan** on your account. Mail [api@getswipe.in](mailto:api@getswipe.in) for a trial and integration support. Open [E-way bills in your dashboard](https://app.getswipe.in/ewaybills) and click **Connect to E-way Bill Portal**. By default the API points to the **Government sandbox portal** — generated bills aren't legally valid until you switch. Mail [api@getswipe.in](mailto:api@getswipe.in) to connect to the production portal. ## Generate an e-way bill Call [`POST /v2/ewaybill/{doc_hash_id}`](/api-reference/ewaybill/create-eway-bill) with the document's `hash_id` (from [document creation](/api-reference/document-v2/create-a-document)) and the transport details. The required fields are `supply_type`, `sub_supply_type`, `transport_mode`, `transporter_doc_date`, and the `dispatch_from` / `dispatch_to` addresses; vehicle and transporter details complete the bill: ```bash theme={null} curl --request POST \ --url https://app.getswipe.in/api/partner/v2/ewaybill/PUlgCNPb \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "supply_type": "Outward", "sub_supply_type": "Supply", "transport_mode": "Road", "vehicle_number": "KA01AB1234", "transporter_doc_date": "26-08-2026", "dispatch_from": { }, "dispatch_to": { } }' ``` Errors from the government portal are passed through as `PORTAL_ERROR_{code}` — see [Error codes](/api-reference/error-codes) for how to look them up. ## Download the PDF [`GET /v2/ewaybill/pdf/{doc_hash_id}`](/api-reference/ewaybill/get-ewaybill-pdf) returns the e-way bill PDF for the same `doc_hash_id`. E-way bill PDF example ## Endpoints Generate an e-way bill for a document. Download the e-way bill PDF. # Introduction Source: https://developers.getswipe.in/introduction Integrate invoicing, payments, and GST compliance into your application with the Swipe API. Swipe is a simple and powerful invoicing, payments, and GST platform trusted by 2 million+ businesses. The Swipe API is RESTful and JSON-based: your application creates invoices, records payments, and stays GST-compliant, while everything shows up in the [Swipe dashboard](https://app.getswipe.in) in real time. Hero Light Hero Dark ## Get set up Sign up on [Swipe](https://app.getswipe.in) — the dashboard and the API work on the same data. In the [API Integration](https://app.getswipe.in/user?tab=api_integration) section of your dashboard. See [Authentication](/authentication) for how requests are signed. Follow the [Quickstart](/quickstart) — create an invoice and download its PDF in two requests, or try any endpoint in the interactive playground on its reference page. Pick templates and document settings on the [settings page](https://app.getswipe.in/user?tab=settings\&sub_tab=document\&doc_tab=general) — PDFs generated by the API use them. ## What you can build with Invoices, purchases, estimates, returns — created, edited, and rendered as PDFs. The parties on your documents, mapped to your own IDs, each with a ledger. Record what customers pay and settle it against documents. Your catalog, with per-warehouse stock tracking. Recurring invoices generated on a schedule. GST compliance — IRN, QR codes, and transport documents. Real-time notifications for document and inventory events. Response envelope, errors, IDs, dates, and rate limits. ## Explore the API your way * **Playground** — every reference page has a **Try it** button with your key. * **Postman** — fork the [Swipe collection](https://god.gw.postman.com/run-collection/43895811-b7327b9d-1e50-4fed-af6f-660a918aa817?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D43895811-b7327b9d-1e50-4fed-af6f-660a918aa817%26entityType%3Dcollection%26workspaceId%3D5d3fc3f0-668c-499e-833b-03222666ba2a). * **AI tools** — every page has a contextual menu (top right) to copy it as Markdown or open it in ChatGPT, Claude, or your editor; the full docs are also available as [llms.txt](https://developers.getswipe.in/llms.txt). Questions? Reach the team via [Support](https://app.getswipe.in/user?tab=api_integration) or the [community forum](https://community.getswipe.in/c/api-integration/14). # Inventory Source: https://developers.getswipe.in/inventory Adjust stock in and out across warehouses, and track every movement with webhooks. Inventory tracks how much of each [product](/product) you hold, per warehouse. Stock moves in three ways: documents move it automatically (sales and sales returns move stock out and back in, purchases and purchase returns move it in and out), you adjust it directly through this API, or someone edits it in the dashboard. ## Adjust stock [`POST /v2/inventory/stock`](/api-reference/inventory-v2/inventory-stock-in-out) records a manual movement — a correction, an opening balance, damage, or an internal transfer: ```bash theme={null} curl --request POST \ --url https://app.getswipe.in/api/partner/v2/inventory/stock \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "product_id": "ITEM001", "action": "in", "quantity": 10, "warehouse_id": -1, "remarks": "Opening stock" }' ``` * `action` — `in` adds stock, `out` removes it * `product_id` — your item ID, the same one used in [documents](/document) * `warehouse_id` — from [Get all warehouses](/api-reference/inventory-v2/get-all-warehouses); use `-1` for the default warehouse * `record_date` — optional `DD-MM-YYYY` backdate for the movement Documents that would take stock below zero can fail with `INSUFFICIENT_STOCK` — see [Error codes](/api-reference/error-codes). ## React to movements in real time Enable the `inventory` [webhook](/webhooks) and Swipe calls your endpoint on every stock movement — API, dashboard, or document-driven — with the product, quantity, and direction: ```json theme={null} { "event_type": "inventory", "data": { "swipe_product_id": 39346, "partner_product_id": "ITEM001", "product_name": "Test Product", "qty": 1.0, "movement": "in", "timestamp": "2025-07-14 09:19:45.000000" } } ``` `partner_product_id` is `-1` when the product isn't mapped to one of your IDs yet — see [ID mapping](/api-conventions#ids-yours-and-swipes). ## Endpoints Record a manual stock movement. List warehouse IDs for stock operations. # Payments Source: https://developers.getswipe.in/payment Record customer payments and settle them against documents. Payments record money received from a customer. A payment belongs to a customer, and can settle one or more of that customer's [documents](/document) — fully or partially. ## Record a payment [`POST /v2/payment`](/api-reference/payment-v2/record-payment) needs four things: the customer, an amount, a date, and a payment mode. Add a `documents` array to settle specific invoices by `hash_id`: ```bash theme={null} curl --request POST \ --url https://app.getswipe.in/api/partner/v2/payment \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "customer": "CUST001", "amount": 118.0, "payment_date": "26-08-2026", "payment_mode": "UPI", "documents": [ { "hash_id": "PUlgCNPb", "amount_paying": 118.0 } ] }' ``` * `payment_mode` — one of `Cash`, `Cheque`, `UPI`, `Card`, `Net Banking`, `paylater`, `cardless_emi`, `EMI`, `TDS`, `Credits` * `documents` — optional; each entry pairs a document `hash_id` with the `amount_paying` toward it. Partial amounts are fine — the document's payment status tracks what's outstanding. * `send_sms` / `send_email` — notify the customer about the recorded payment * Non-cash modes need a bank account configured on your Swipe account — otherwise the request fails with `MISSING_BANK_ACCOUNT` Payments and balances also flow into each customer's [payment ledger](/api-reference/customer-v2/get-payment-ledger). Record payment screen in the Swipe dashboard ## Endpoints Record a payment and settle documents. List recorded payments over a date range. # Products Source: https://developers.getswipe.in/product Manage your item catalog - products and services, pricing, taxes, and units. Products (items) are what you sell and buy. They appear as `items` on every [document](/document), and stocked products are tracked by [Inventory](/inventory). ## The item model Items use the same ID model as [customers](/customer): every call carries **your** `item_id`, unknown IDs are auto-created (including inline during document creation), and [Update items mapping](/api-reference/product-v2/update-items-mapping) re-links your IDs in bulk if they change. The fields that matter most: * `item_type` — `Product` (stocked, tracked by inventory) or `Service` * `unit_price`, `tax_rate`, `price_with_tax` — pricing with GST; only valid GST tax rates are accepted * `hsn_code` — the HSN/SAC code that GST compliance (and e-invoicing) relies on * `unit` — a GST-approved UQC unit such as `kg`, `pcs`, `mtr` ## Add an item ```bash theme={null} curl --request POST \ --url https://app.getswipe.in/api/partner/v2/product \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "id": "ITEM001", "item_type": "Product", "name": "Test Product", "unit_price": 100.0, "tax_rate": 18.0, "price_with_tax": 118.0, "hsn_code": "8517", "unit": "pcs" }' ``` Item details sent inside a document apply to that document only — they never overwrite the catalog record. To change the master record, use [Update an item](/api-reference/product-v2/update-an-item). Products and services list in the Swipe dashboard ## Endpoints Create an item with your own ID. Fetch one item by your `item_id`. Change the catalog record. Remove an item from the catalog. Page through the catalog. Re-link your IDs to Swipe records in bulk. Tracking stock levels too? Continue to [Inventory](/inventory). # Quickstart Source: https://developers.getswipe.in/quickstart Create your first invoice and download its PDF in under five minutes. This guide takes you from zero to a real invoice PDF using two API calls. All you need is a Swipe account. **Test in a separate company.** API keys are scoped to a company, so the cleanest way to experiment is to [add a new company](https://community.getswipe.in/t/how-to-add-new-company-on-web/1191) in your Swipe account (e.g. "API Testing"), switch to it, and generate your API key from its [API Integration](https://app.getswipe.in/user?tab=api_integration) section. Everything you create with that key stays in the test company, leaving your real books untouched. When you go live, generate a key in your actual company and swap it in. Sign in to Swipe and open the [API Integration](https://app.getswipe.in/user?tab=api_integration) section of your dashboard. Generate an API key and store it securely — it is sent as a Bearer token with every request. See [Authentication](/authentication) for details. Send a `POST` request to `/v2/doc` with a minimal payload — a date, a document type, a customer, and one line item. Replace `YOUR_API_KEY` with the key from step 1. ```bash cURL theme={null} curl --request POST \ --url https://app.getswipe.in/api/partner/v2/doc \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "document_type": "invoice", "document_date": "26-08-2026", "party": { "id": "CUST001", "type": "customer", "name": "Test Customer" }, "items": [ { "id": "ITEM001", "item_type": "Product", "name": "Test Product", "quantity": 1, "unit_price": 100.0, "tax_rate": 18.0, "net_amount": 100.0, "price_with_tax": 118.0, "total_amount": 118.0 } ] }' ``` ```python Python theme={null} import requests API_KEY = "YOUR_API_KEY" payload = { "document_type": "invoice", "document_date": "26-08-2026", "party": {"id": "CUST001", "type": "customer", "name": "Test Customer"}, "items": [ { "id": "ITEM001", "item_type": "Product", "name": "Test Product", "quantity": 1, "unit_price": 100.0, "tax_rate": 18.0, "net_amount": 100.0, "price_with_tax": 118.0, "total_amount": 118.0, } ], } response = requests.post( "https://app.getswipe.in/api/partner/v2/doc", headers={"Authorization": f"Bearer {API_KEY}"}, json=payload, ) print(response.json()) ``` ```javascript JavaScript theme={null} const API_KEY = "YOUR_API_KEY"; const payload = { document_type: "invoice", document_date: "26-08-2026", party: { id: "CUST001", type: "customer", name: "Test Customer" }, items: [ { id: "ITEM001", item_type: "Product", name: "Test Product", quantity: 1, unit_price: 100.0, tax_rate: 18.0, net_amount: 100.0, price_with_tax: 118.0, total_amount: 118.0, }, ], }; const response = await fetch("https://app.getswipe.in/api/partner/v2/doc", { method: "POST", headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify(payload), }); console.log(await response.json()); ``` The customer `CUST001` and item `ITEM001` don't need to exist yet — Swipe creates them automatically from the details you send, and reuses them the next time you send the same IDs. See [Create a document](/api-reference/document-v2/create-a-document) for every available field. A successful call returns the document's identifiers. The `hash_id` is the document's address in every other API call — fetching, editing, cancelling, and downloading the PDF. ```json theme={null} { "success": true, "message": "Document created successfully", "error_code": "", "errors": {}, "data": { "hash_id": "PUlgCNPb", "serial_number": "INV-1", "irn": "", "qr_code": "" } } ``` Pass the `hash_id` to the PDF endpoint — the response is the PDF file itself. ```bash theme={null} curl --request GET \ --url https://app.getswipe.in/api/partner/v2/doc/pdf/PUlgCNPb \ --header "Authorization: Bearer YOUR_API_KEY" \ --output invoice.pdf ``` The invoice also appears in your [Swipe dashboard](https://app.getswipe.in/list/sales) alongside documents created in the app — the API and the dashboard work on the same data. ## Next steps Response format, error codes, dates, list endpoints, and rate limits. The full document payload — taxes, discounts, serial numbers, and more. Get notified in real time when documents or inventory change. Generate GST-compliant e-invoices with IRN and QR codes. # Subscriptions Source: https://developers.getswipe.in/subscriptions Set up recurring invoices through the document API, then track them and their generated invoices. A subscription generates invoices for a customer automatically on a schedule — daily, weekly, monthly, or yearly. Swipe creates each invoice when it falls due; you just define the schedule once. ## Create a subscription There's no separate create-subscription endpoint — a subscription **is a document**. Call [Create a document](/api-reference/document-v2/create-a-document) with `document_type: "subscription"` and a `subscription_details` object describing the schedule: ```bash theme={null} curl --request POST \ --url https://app.getswipe.in/api/partner/v2/doc \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "document_type": "subscription", "document_date": "26-08-2026", "party": { "id": "CUST001", "type": "customer", "name": "Test Customer" }, "items": [ { "id": "ITEM001", "item_type": "Service", "name": "Monthly Retainer", "quantity": 1, "unit_price": 100.0, "tax_rate": 18.0, "net_amount": 100.0, "price_with_tax": 118.0, "total_amount": 118.0 } ], "subscription_details": { "start_time": "01-09-2026", "end_time": "01-09-2027", "repeat": 1, "repeat_type": "months", "send_email": true } }' ``` * `repeat` + `repeat_type` — the cadence: every `1` × `months` above; `repeat_type` is one of `days`, `weeks`, `months`, `years` * `start_time` / `end_time` — when the schedule runs, `DD-MM-YYYY` * `send_email` / `send_sms` / `send_wtsp` — deliver each generated invoice to the customer automatically Subscriptions must be enabled on your Swipe account — otherwise creation fails with `SUBSCRIPTIONS_NOT_ENABLED`. Enable them in the [Swipe dashboard](https://app.getswipe.in/list/subscriptions). ## Track subscriptions and their invoices [List of subscriptions](/api-reference/subscriptions-v2/list-of-subscriptions) returns subscriptions over a date range, filterable by `status` and `customer_id`. Each entry's hash ID feeds [Get subscription details](/api-reference/subscriptions-v2/get-subscription-details), which includes the invoices generated so far. The generated invoices are ordinary [documents](/document) — fetch their PDFs and record [payments](/payment) against them as usual. Subscriptions list in the Swipe dashboard ## Endpoints Filter by date range, status, and customer. One subscription with its generated invoices. # Vendors Source: https://developers.getswipe.in/vendor Manage the vendors you buy from - the purchase-side mirror of the customer API. Vendors are the parties you buy from. They appear as the `party` (type `vendor`) on purchases, purchase orders, and purchase returns, and — like customers — each vendor has a ledger of what you owe and have paid. The vendor API mirrors the [customer API](/customer) exactly, including the ID model: every call uses **your** `vendor_id`, new IDs create vendors automatically (also inline during [document creation](/api-reference/document-v2/create-a-document)), existing IDs reuse and update the record, and [Update vendor mapping](/api-reference/vendor-v2/update-vendor-mapping) re-links your IDs in bulk after a migration. ## Add a vendor ```bash theme={null} curl --request POST \ --url https://app.getswipe.in/api/partner/v2/vendor \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "id": "VEND001", "name": "Test Vendor", "phone_number": "1234567890", "gstin": "27AARCS7202C1ZD" }' ``` ## Endpoints Create a vendor with your own ID. Fetch one vendor by your `vendor_id`. Change a vendor's details. Remove a vendor record. Transaction history and balance for one vendor. Page through all vendors. Re-link your IDs to Swipe records in bulk. # Webhooks Source: https://developers.getswipe.in/webhooks Receive real-time notifications for document and inventory events, with HMAC signature verification. Webhooks provide a powerful way to receive real-time notifications about events in your Swipe account. Instead of continuously polling our API, webhooks push data to your application immediately when events occur. ## Overview When enabled, Swipe will send HTTP POST requests to your configured webhook URL whenever specific events occur in your account. Each webhook request includes: * **Event data**: Details about what happened * **Signature**: For request verification using HMAC * **Event type**: The specific type of event * **Event id**: The unique event id ## Event Types ### Document Events Receive notifications for all document-related activities: | Event Type | Description | | ---------- | ---------------------------------------------------------- | | `document` | Triggered when documents are created, updated, or modified | **Document Event Data Fields:** * `document_type`: Type of document (e.g., "purchase", "invoice") * `serial_number`: Document serial number * `hash_id`: Unique document identifier * `message`: Event description (e.g., "Document Created") * `timestamp`: When the event occurred ### Inventory Events Get real-time updates about inventory changes: | Event Type | Description | | ----------- | ----------------------------------------------------- | | `inventory` | Triggered when inventory levels change (stock in/out) | **Inventory Event Data Fields:** * `swipe_product_id`: Internal Swipe product ID * `partner_product_id`: Your system's product ID (-1 if not mapped) * `product_name`: Name of the product * `qty`: Quantity changed * `movement`: Direction of movement ("in" or "out") * `timestamp`: When the inventory change occurred ## Security & Verification ### HMAC Signature Verification Every webhook request includes an `X-Signature` header containing an HMAC signature. This ensures the request is authentic and comes from Swipe. #### Verification Process 1. Extract the signature from the `X-Signature` header 2. Create an HMAC using your webhook secret and the raw request body 3. Compare the computed signature with the received signature #### Code Examples **Python** ```python theme={null} import hmac import hashlib import json def verify_webhook_signature(payload, signature, secret): expected_signature = hmac.new( secret.encode('utf-8'), payload.encode('utf-8'), hashlib.sha256 ).hexdigest() return hmac.compare_digest(signature, expected_signature) # Flask example from flask import Flask, request @app.route('/webhook', methods=['POST']) def handle_webhook(): signature = request.headers.get('X-Signature') payload = request.get_data(as_text=True) if not verify_webhook_signature(payload, signature, WEBHOOK_SECRET): return 'Invalid signature', 401 event = json.loads(payload) print(f"Received event: {event['event_type']}") return 'OK', 200 ``` ## Webhook Payloads ### Document Event Payload ```json theme={null} { "event_id": "ae24831c-6093-11f0-aef5-6045bd733335", "event_type": "document", "data": { "document_type": "purchase", "serial_number": "ui-1255test-25-26", "hash_id": "PUlgCNPb", "message": "Document Created", "timestamp": "2025-07-14 09:19:44.000000" } } ``` ### Inventory Event Payload ```json theme={null} { "event_id": "ae960d63-6093-11f0-aef5-6045bd733335", "event_type": "inventory", "data": { "swipe_product_id": 39346, "partner_product_id": -1, "product_name": "brazil", "qty": 1.0, "movement": "in", "timestamp": "2025-07-14 09:19:45.000000" } } ``` ### Sample Webhook Request Here's how a webhook request would look when sent to your endpoint: ```bash theme={null} curl -X POST https://your.webhook.endpoint \ -H "Content-Type: application/json" \ -H "X-Signature: f4c3b2d9d27d3fc4b0f53f2e1f1a9fda33e8b705f5155c9ef16e225b6a098765" \ -d '{"event_id":"236c2c42-58c7-11f0-aef5-6045bd733335","event_type":"inventory","data":{"swipe_product_id":4839,"partner_product_id":"install_1500_p","product_name":"Installation (Split AC)","qty":7.0,"timestamp":"2025-07-04 11:07:56.000000","movement":"in"}}' ``` This example shows: * **POST Request**: All webhooks are sent via HTTP POST * **Content-Type**: Always `application/json` * **X-Signature**: HMAC signature for request verification * **Payload**: The actual event data in JSON format ## Configuration ### Setting Up Webhooks 1. **Access Settings**: Go to [Swipe dashboard](https://app.getswipe.in/user?tab=api_integration) 2. **Add Webhook URL**: Enter your webhook endpoint URL 3. **Select Events**: Choose which event types you want to receive 4. **Set Secret**: Generate or provide a webhook secret for signature verification ### Webhook URL Requirements * Must be a valid HTTPS URL (HTTP not supported in production) * Should respond with a 200 status code within 10 seconds * Must be publicly accessible (no localhost or private IPs) ## Troubleshooting ### Common Issues 1. **Signature Verification Failures** * Ensure you're using the raw request body * Verify the webhook secret is correct * Check that the signature header name is `X-Signature` 2. **Webhook Not Receiving Events** * Confirm the webhook URL is correct and accessible * Check that the event types are properly configured * Verify your endpoint returns a 200 status code 3. **Timeout Issues** * Ensure your webhook endpoint responds within 10 seconds * Process webhooks asynchronously for heavy operations * Implement proper error handling For additional support with webhooks, contact our [support team](https://app.getswipe.in/user?tab=api_integration).