> ## 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.

# Customers

> 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.

<Frame caption="Customers in the Swipe dashboard, with balances and ledgers">
  <img src="https://mintcdn.com/swipe/TNGTRFRYClr_ZLaq/images/screenshots/customers.png?fit=max&auto=format&n=TNGTRFRYClr_ZLaq&q=85&s=6de5c6e2468314fe77fc038849d761cc" alt="Customer list in the Swipe dashboard" width="1887" height="950" data-path="images/screenshots/customers.png" />
</Frame>

## Endpoints

<CardGroup cols={2}>
  <Card title="Add a customer" icon="plus" href="/api-reference/customer-v2/add-a-customer">
    Create a customer with your own ID.
  </Card>

  <Card title="Get customer details" icon="magnifying-glass" href="/api-reference/customer-v2/get-customer-details">
    Fetch one customer by your `customer_id`.
  </Card>

  <Card title="Update a customer" icon="pen" href="/api-reference/customer-v2/update-a-customer">
    Change a customer's details.
  </Card>

  <Card title="Delete a customer" icon="trash" href="/api-reference/customer-v2/delete-a-customer">
    Remove a customer record.
  </Card>

  <Card title="Get payment ledger" icon="book-open" href="/api-reference/customer-v2/get-payment-ledger">
    Transaction history and balance for one customer.
  </Card>

  <Card title="Get list of customers" icon="list" href="/api-reference/customer-v2/get-list-of-customers">
    Page through all customers.
  </Card>

  <Card title="Update customer mapping" icon="link" href="/api-reference/customer-v2/update-customer-mapping">
    Re-link your IDs to Swipe records in bulk.
  </Card>
</CardGroup>

Buying from someone instead? See [Vendors](/vendor) — the purchase-side mirror of this API.