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.

POST /v2/doc

Create a document

cURL

curl --request POST \
  --url https://app.getswipe.in/api/partner/v2/doc \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "document_type": "invoice",
  "document_date": "11-06-2024",
  "items": [
    {
      "id": "ITEM123",
      "name": "Item Name",
      "quantity": 1,
      "unit_price": 100,
      "price_with_tax": 118,
      "net_amount": 100,
      "total_amount": 118,
      "item_type": "Product",
      "tax_rate": 18,
      "discount_percent": 10,
      "discount_amount": 10,
      "description": "Item Description",
      "hsn_code": "1234",
      "unit": "kg",
      "category": "Electronics",
      "custom_columns": [
        {
          "label": "Custom Field 1",
          "value": "Value 1"
        }
      ]
    }
  ]
}
'

200

{
  "success": true,
  "message": "Message",
  "error_code": "",
  "errors": {},
  "data": {
    "hash_id": "SL123",
    "serial_number": "SL123",
    "irn": "<string>",
    "qr_code": "<string>"
  }
}

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

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is an API key from the API Integration section of your dashboard. Keys are scoped to the company they are generated in — for testing, add a separate test company and generate the key there, so requests never touch your real books.

Body

application/json

document_type · enum<string> · required

Type of document to create. One of the enum values listed below; use 'invoice' for a standard GST invoice.

Available options: invoice, subscription, pro_forma_invoice, estimate, sales_return, purchase_return, delivery_challan, purchase

Example:

"invoice"

document_date · string · required

DD-MM-YYYY

Example:

"11-06-2024"

items · object[] · required

Array of Products/Services, refer Item Object below for parameters

Show child attributes

serial_number · string

Serial Number (deprecated, please use New Serial Number)

Example:

"INV123"

serial_number_v2 · object

Show child attributes

Example:

{
  "prefix": "INV",
  "doc_number": 1,
  "suffix": "2024"
}

party · object

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.

Show child attributes

due_date · string

DD-MM-YYYY

Example:

"11-06-2024"

reference · string

Any references you want to add to the doc

Example:

"Reference Text"

notes · string

Notes to show in invoice - please check template in swipe application to see where this is displayed

Example:

"Notes for the document"

terms · string

Terms to show in invoice - please check template in swipe application to see where this is displayed

Example:

"Terms and Conditions"

warehouse_id · integer

Warehouse ID

Example:

-1

extra_discount · number · default: 0

Adjustment on overall invoice, doesn’t effect any tax amounts.

Example:

20

round_off · boolean · default: false

Should Round Off total amount

Example:

true

payments · object[]

Array of Payments, refer Payment Object for parameters

Show child attributes

bank_details · object

Bank Details, it is used to display bank details in document PDFs. No payments are associated with these bank details.

Show child attributes

tds_id · integer

You can check the tds id and details mapping from https://developers.getswipe.in/api-reference/references#tds-tax-deducted-at-source

tcs_id · integer

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 · object[]

Array of Charges and Deductions, refer Additional Charges Deductions Object for parameters

Show child attributes

company_shipping_address · object

Company shipping from Address, refer Shipping Address Object for parameters

Show child attributes

company_billing_address · object

Company billing Address, refer Billing Address Object for parameters

Show child attributes

einvoice · boolean

Generate einvoice

Example:

false

is_export · boolean

Is Export

Example:

false

is_multi_currency · boolean

Is Multi Currency

Example:

false

export_invoice_details · object

Export Invoice Details

Show child attributes

is_subscription · boolean

Is Subscription

Example:

false

subscription_details · object

Subscription Details

Show child attributes

convert · object

Convert Document. Needed only when the document is already created and you want to convert it to another document

Show child attributes

custom_headers · object[]

Document Custom Headers. Custom headers should already be added in Swipe Portal.

Show child attributes

Example:

[
  {
    "label": "Custom Header 1",
    "value": "Value 1"
  }
]

Response

200

application/json

Success

success · boolean · default: true

Example:

true

message · string

Success Message

Example:

"Message"

error_code · string

Error Code

Example:

""

errors · object

Error details

data · object

Show child attributes