> ## Documentation Index
> Fetch the complete documentation index at: https://developers.getswipe.in/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a document
> 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
## OpenAPI
````yaml post /v2/doc
openapi: 3.0.1
info:
title: SwipeAPI
version: '2.0'
description: >-
The Swipe Partner API — invoicing, payments, and GST compliance for your
application. Create GST invoices and other documents, manage customers,
vendors, products and inventory, record payments, and generate e-invoices
and e-way bills.
- Docs & guides: https://developers.getswipe.in
- Quickstart: https://developers.getswipe.in/quickstart
- Rate limit: 1 request/second per API key
- All dates are DD-MM-YYYY
servers:
- url: https://app.getswipe.in/api/partner
security:
- bearerAuth: []
paths:
/v2/doc:
post:
tags:
- Document V2
summary: Create a document
description: >-
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.
operationId: post_invoice_resource
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BaseDocumentV2'
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/DocCreateResponseV2'
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/DocCreateResponseV2'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/DocCreateResponseV2'
'409':
description: Idempotency Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/DocCreateResponseV2'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/DocCreateResponseV2'
'500':
description: Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/DocCreateResponseV2'
components:
schemas:
BaseDocumentV2:
required:
- document_date
- document_type
- items
properties:
serial_number:
type: string
description: Serial Number (deprecated, please use New Serial Number)
example: INV123
serial_number_v2:
example:
prefix: INV
doc_number: 1
suffix: '2024'
allOf:
- $ref: '#/components/schemas/SerialNumber'
document_type:
type: string
description: >-
Type of document to create. One of the enum values listed below; use
'invoice' for a standard GST invoice.
example: invoice
enum:
- invoice
- subscription
- pro_forma_invoice
- estimate
- sales_return
- purchase_return
- delivery_challan
- purchase
document_date:
type: string
description: DD-MM-YYYY
example: 11-06-2024
party:
description: >-
Party. If there are any changes made to the party details, we will
update those details and any documents linked to this party ID will
be updated to reflect the changes.
allOf:
- $ref: '#/components/schemas/Party'
due_date:
type: string
description: DD-MM-YYYY
example: 11-06-2024
reference:
type: string
description: Any references you want to add to the doc
example: Reference Text
notes:
type: string
description: >-
Notes to show in invoice - please check template in swipe
application to see where this is displayed
example: Notes for the document
terms:
type: string
description: >-
Terms to show in invoice - please check template in swipe
application to see where this is displayed
example: Terms and Conditions
items:
type: array
description: Array of Products/Services, refer Item Object below for parameters
items:
$ref: '#/components/schemas/DocItemV2'
warehouse_id:
type: integer
description: Warehouse ID
example: -1
extra_discount:
type: number
description: Adjustment on overall invoice, doesn’t effect any tax amounts.
default: 0
example: 20
round_off:
type: boolean
description: Should Round Off total amount
default: false
example: true
payments:
type: array
description: Array of Payments, refer Payment Object for parameters
items:
$ref: '#/components/schemas/PaymentV2'
bank_details:
description: >-
Bank Details, it is used to display bank details in document PDFs.
No payments are associated with these bank details.
allOf:
- $ref: '#/components/schemas/BankDetails'
tds_id:
type: integer
description: >-
You can check the tds id and details mapping from
https://developers.getswipe.in/api-reference/references#tds-tax-deducted-at-source
tcs_id:
type: integer
description: >-
You can check the tcs id and details mapping from
https://developers.getswipe.in/api-reference/references#tcs-tax-collected-at-source
charges_and_deductions:
type: array
description: >-
Array of Charges and Deductions, refer Additional Charges Deductions
Object for parameters
items:
$ref: '#/components/schemas/AdditionalChargesDeductionsV2'
company_shipping_address:
description: >-
Company shipping from Address, refer Shipping Address Object for
parameters
allOf:
- $ref: '#/components/schemas/ShippingAddressV2'
company_billing_address:
description: Company billing Address, refer Billing Address Object for parameters
allOf:
- $ref: '#/components/schemas/ShippingAddressV2'
einvoice:
type: boolean
description: Generate einvoice
example: false
is_export:
type: boolean
description: Is Export
example: false
is_multi_currency:
type: boolean
description: Is Multi Currency
example: false
export_invoice_details:
description: Export Invoice Details
allOf:
- $ref: '#/components/schemas/ExportInvoiceDetailsV2'
is_subscription:
type: boolean
description: Is Subscription
example: false
subscription_details:
description: Subscription Details
allOf:
- $ref: '#/components/schemas/Subscription'
convert:
description: >-
Convert Document. Needed only when the document is already created
and you want to convert it to another document
allOf:
- $ref: '#/components/schemas/Convert'
custom_headers:
type: array
description: >-
Document Custom Headers. Custom headers should already be added in
Swipe Portal.
example:
- label: Custom Header 1
value: Value 1
items:
$ref: '#/components/schemas/CustomHeaders'
type: object
DocCreateResponseV2:
properties:
success:
type: boolean
default: true
example: true
message:
type: string
description: Success Message
example: Message
error_code:
type: string
description: Error Code
example: ''
errors:
type: object
description: Error details
data:
$ref: '#/components/schemas/DocCreateData'
type: object
SerialNumber:
properties:
prefix:
type: string
example: INV-, INV/2024, INV-2024/25, INV/2024-25
doc_number:
type: integer
example: 1
suffix:
type: string
example: '-suffix, /-suffix,-/suffix, /suffix'
type: object
Party:
required:
- id
- name
- type
properties:
id:
type: string
description: Unique id for each party.
example: CUST123
type:
type: string
description: |-
Party type, use only specified values.
Party type customer can be used for creating invoices, sales returns, estimates, pro forma invoices and delivery challans.
Party type vendor can be used for creating purchases, purchase orders & purchase returns, .
example: customer
enum:
- customer
- vendor
name:
type: string
description: Name of the Party
example: John Doe
country_code:
type: string
description: Party Phone Number Country code
example: '91'
phone_number:
type: string
description: Party Phone Number
example: '1234567890'
company_name:
type: string
description: Company Name
example: Company Name
email:
type: string
description: Party Email
example: johndoe@example.com
gstin:
type: string
description: GSTIN
example: 27AARCS7202C1ZD
shipping_address:
description: >-
Party shipping to Address, refer Shipping Address Object for
parameters
allOf:
- $ref: '#/components/schemas/ShippingAddressV2'
billing_address:
description: >-
Party billing to Address, refer Shipping Address Object for
parameters
allOf:
- $ref: '#/components/schemas/ShippingAddressV2'
type: object
DocItemV2:
required:
- id
- item_type
- name
- net_amount
- price_with_tax
- quantity
- total_amount
- unit_price
properties:
id:
type: string
description: >-
Unique id for each item. If a new id is sent, a new Item with the
below details will be automatically created. if existing Item id is
sent the details will not override the original item details. They
will be applicable only to the current documents. Use update item to
actually update the item details in swipe
example: ITEM123
name:
type: string
description: Name of the Product
example: Item Name
quantity:
type: number
description: Quantity
example: 1
unit_price:
type: number
description: Price per item without Tax
example: 100
tax_rate:
type: number
description: Tax percentage for each item . Only valid tax rates are accepted
example: 18
price_with_tax:
type: number
description: Price per item with Tax
example: 118
net_amount:
type: number
description: Net Amount
example: 100
total_amount:
type: number
description: |-
Item total amount (Net Amount + Tax).
We calculate the discount amount by multiplying the item's quantity, unit price, and discount percentage. If a discount amount is provided instead, we reverse-calculate the percentage. If no discount is given, it is set to 0.
example: 118
discount_percent:
type: number
description: Discount Percent
default: 0
example: 10
discount_amount:
type: number
description: Discount Amount, will be ignored if discount_percent is provided
default: 0
example: 10
description:
type: string
description: Item Description
example: Item Description
hsn_code:
type: string
description: HSN Code. HSN Code can only be of length 4,6 & 8
example: '1234'
item_type:
type: string
description: Product or Service enum
example: Product
enum:
- Product
- Service
unit:
type: string
description: >-
Item quantity unit. You can find the GST-approved units in the UQC
Codes section at: https://einvoice1.gst.gov.in/Others/MasterCodes.
example: kg
category:
type: string
description: Category
example: Electronics
custom_columns:
type: array
description: >-
Item Custom Fields. Custom fields should already be added in Swipe
Portal.
example:
- label: Custom Field 1
value: Value 1
items:
$ref: '#/components/schemas/ItemCustomFields'
type: object
PaymentV2:
required:
- amount
- method
properties:
amount:
type: number
description: Payment Amount
example: 100
method:
type: string
description: Payment method, use only specified values
example: upi
enum:
- cash
- card
- upi
- netBanking
- cheque
- emi
notes:
type: string
description: Any internal notes for payment
example: Payment notes
bank_details:
description: >-
Bank Details, refer Bank Details Object below for parameters, If
account_number, ifsc matched with existing bank details, it will be
used, else new bank details will be added to your swipe account. It
will link document payments to your company bank details.
allOf:
- $ref: '#/components/schemas/BankDetails'
type: object
BankDetails:
required:
- account_number
- bank_name
- branch
- ifsc
properties:
account_number:
type: string
description: Account Number
example: '1234567890'
ifsc:
type: string
description: IFSC Code
example: SBIN0000001
bank_name:
type: string
description: Bank Name
example: State Bank of India
branch:
type: string
description: Branch
example: Mumbai
type: object
AdditionalChargesDeductionsV2:
required:
- amount
- id
- name
- tax_rate
- type
properties:
id:
type: integer
description: Unique ID for the charge/deduction. 0 < id <= 999999
example: 1
name:
type: string
description: Name of the charge/deduction.
example: Delivery Charge
amount:
type: number
description: Total Amount
example: 100
tax_rate:
type: number
description: Tax Rate
example: 18
sac_code:
type: string
description: SAC Code
example: '1234'
type:
type: string
description: Type
example: charge
enum:
- charge
- deduction
type: object
ShippingAddressV2:
required:
- address_line1
- address_line2
- city
- country
- pincode
- state
properties:
addr_id:
type: integer
description: Address ID. Value should be between 0 and 999999.
example: -1
addr_id_v2:
type: string
description: >-
Address ID. Value should be not be empty, It should be alphanumeric
with length upto 16 characters.
example: addr1
address_line1:
type: string
description: Address Line 1
example: 123 Street
address_line2:
type: string
description: Address Line 2
example: Apt 4B
city:
type: string
description: City
example: City Name
state:
type: string
description: |-
State.
Select OTHER TERRITORY for countries other than India.
You can copy the state details from https://developers.getswipe.in/api-reference/references#state-details
example: State Name
enum:
- 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)
- LADAKH(NEWLY ADDED)
- OTHER TERRITORY
country:
type: string
description: >-
Country. You can copy the country details from
https://developers.getswipe.in/api-reference/references#country-array
example: Country Name
enum:
- 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
- Republic of Korea (South Korea)
- 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
pincode:
type: string
description: Pincode
example: '123456'
type: object
ExportInvoiceDetailsV2:
required:
- conversion_factor
- export_type
properties:
shipping_bill_date:
type: string
description: Shipping Bill Date [DD-MM-YYYY]
example: 14-02-2024
shipping_bill_number:
type: string
description: Shipping Bill Number
example: '123456'
shipping_port_code:
type: string
description: Shipping Port Code
example: '123456'
export_type:
type: string
description: Export Type
example: With Payment of Tax
enum:
- Export under bond/LUT
- Export with IGST
- SEZ with IGST Payment
- SEZ without IGST Payment
- Deemed Export
- Multi Currency
conversion_factor:
type: number
description: >-
The conversion factor represents the rate used to convert foreign
currencies into Indian rupees. For example, if you're invoicing in
dollars, and 1 dollar equals 84 rupees, the conversion factor would
be 84
country_id:
type: string
description: Country ID
example: Afghanistan
enum:
- 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
- Republic of Korea (South Korea)
- 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
currency_id:
type: string
description: >-
Currency ID, if not provided, the default country currency will be
used, please refer to the currency list from
https://developers.getswipe.in/api-reference/references#currency-details
example: AED
enum:
- AED
- AFN
- ALL
- AMD
- ANG
- AOA
- ARS
- AUD
- AWG
- AZN
- BAM
- BBD
- BDT
- BGN
- BHD
- BIF
- BMD
- BND
- BOB
- BRL
- BSD
- BTN
- BWP
- BYN
- BZD
- CAD
- CDF
- CHF
- CLP
- CNY
- COP
- CRC
- CUP
- CVE
- CZK
- DJF
- DKK
- DOP
- DZD
- EGP
- ERN
- ETB
- EUR
- FJD
- FKP
- FOK
- GBP
- GEL
- GGP
- GHS
- GIP
- GMD
- GNF
- GTQ
- GYD
- HKD
- HNL
- HRK
- HTG
- HUF
- IDR
- ILS
- IMP
- INR
- IQD
- IRR
- ISK
- JEP
- JMD
- JOD
- JPY
- KES
- KGS
- KHR
- KID
- KMF
- KRW
- KWD
- KYD
- KZT
- LAK
- LBP
- LKR
- LRD
- LSL
- LYD
- MAD
- MDL
- MGA
- MKD
- MMK
- MNT
- MOP
- MRU
- MUR
- MVR
- MWK
- MXN
- MYR
- MZN
- NAD
- NGN
- NIO
- NOK
- NPR
- NZD
- OMR
- PAB
- PEN
- PGK
- PHP
- PKR
- PLN
- PYG
- QAR
- RON
- RSD
- RUB
- RWF
- SAR
- SBD
- SCR
- SDG
- SEK
- SGD
- SHP
- SLE
- SLL
- SOS
- SRD
- SSP
- STN
- SYP
- SZL
- THB
- TJS
- TMT
- TND
- TOP
- TRY
- TTD
- TVD
- TWD
- TZS
- UAH
- UGX
- USD
- UYU
- UZS
- VES
- VND
- VUV
- WST
- XAF
- XCD
- XDR
- XOF
- XPF
- YER
- ZAR
- ZMW
- ZWL
type: object
Subscription:
properties:
start_time:
type: string
format: date
description: Start Time [DD-MM-YYYY]
example: 14-02-2024
end_time:
type: string
format: date
description: End Time [DD-MM-YYYY]
example: 14-02-2025
repeat:
type: integer
description: 'Repeat in value, Frequency of the repetition '
example: 1
repeat_type:
type: string
description: Repeat type, Entity of the repetition
example: days
enum:
- days
- weeks
- months
- years
send_email:
type: boolean
send_sms:
type: boolean
send_wtsp:
type: boolean
type: object
Convert:
required:
- convert_from
- hash_id
properties:
convert_from:
type: string
description: The document type which is being converted
example: invoice
enum:
- invoice
- estimate
- pro_forma_invoice
- sales_return
- purchase_return
hash_id:
type: string
description: Hash ID
example: SL123
type: object
CustomHeaders:
required:
- label
- value
properties:
label:
type: string
value:
type: string
type: object
DocCreateData:
properties:
hash_id:
type: string
description: Hash ID
example: SL123
serial_number:
type: string
description: Serial Number
example: SL123
irn:
type: string
description: IRN
qr_code:
type: string
description: QR Code
type: object
ItemCustomFields:
required:
- label
- value
properties:
label:
type: string
value:
type: string
type: object
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
Bearer authentication header of the form `Bearer `, where
`` is an API key from the [API
Integration](https://app.getswipe.in/user?tab=api_integration) section
of your dashboard. Keys are scoped to the company they are generated in
— for testing, [add a separate test
company](https://community.getswipe.in/t/how-to-add-new-company-on-web/1191)
and generate the key there, so requests never touch your real books.
````