> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mf-atlas.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Start a SIP

> Register a systematic investment plan, authorise it once, and track the installments that are collected automatically.

A **SIP** (systematic investment plan) invests a fixed amount in a scheme on a
recurring schedule. You register it **once**; every installment after that is
debited automatically on its due date. You never create or pay an installment
yourself.

<Steps>
  <Step title="Register the SIP">
    `POST /api/orders/v1/` with `order_type: "SIP"`. Validated and persisted
    synchronously, then registered with the exchange in the background.
    Returns `202`.
  </Step>

  <Step title="Investor authorises it">
    Once the SIP is `ACCEPTED`, the order carries a `payment_link` — an
    authorisation page the investor opens to approve the plan.
  </Step>

  <Step title="Installments run on their own">
    The SIP becomes `REGISTERED` and each installment is debited on its due
    date against the investor's [mandate](/api-documentation/mandates).
    Progress shows up on the order and under `GET /api/orders/v1/:id/installments`.
  </Step>
</Steps>

## Prerequisites

* The investor is `status: REGISTERED` (see [Create an investor](/api-documentation/create-investor)).
* An [investment account](/api-documentation/investment-accounts) exists for the investor.
* A `REGISTERED` [mandate](/api-documentation/mandates) whose limit covers the
  installment `amount` — it is what funds each debit.
* The scheme has `sip_allowed: true`. Check its `sip_frequencies`, `sip_dates`
  and `min_sip` via [schemes](/api-documentation/schemes) first.

## Register the SIP

```http theme={null}
POST /api/orders/v1/
Authorization: Bearer <token>
Idempotency-Key: 3b1c9d52-...
Content-Type: application/json
```

```json theme={null}
{
  "order_type": "SIP",
  "investment_account_id": "A_RT_000001",
  "scheme_code": "128SDGP",
  "amount": 5000,
  "mandate_id": "mnd_4a1b2c",
  "sip": {
    "frequency": "MONTHLY",
    "day": 5,
    "start_date": "2026-11-05",
    "installments": 24
  },
  "euin": { "declaration": true, "euin": "E123456" },
  "client_ref": "sip-1042"
}
```

Response `202`:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "ord_5d6e7f8a",
    "status": "PENDING",
    "order_type": "SIP",
    "client_ref": "sip-1042",
    "created_at": "2026-10-11T10:20:00Z"
  }
}
```

### Fields

`amount` is the **per-installment** amount. Fields not listed here behave as
in [Create a Purchase Order](/api-documentation/purchase-orders#fields).

| Field | Required | Format / values | Notes |
| - | - | - | - |
| `order_type` | yes | `SIP` | |
| `investment_account_id` | yes | friendly account ID | The investor is derived from it (must be `REGISTERED`). |
| `scheme_code` | yes | string | Must allow SIPs. |
| `amount` | yes | number | Installment amount; at least the scheme's `min_sip`. |
| `mandate_id` | yes (in practice) | | Funds the installments. Checked for usability against `amount`. |
| `sip.frequency` | yes | `DAILY` \| `WEEKLY` \| `MONTHLY` \| `QUARTERLY` \| `HALF_YEARLY` \| `YEARLY` | Must be one of the scheme's `sip_frequencies`. |
| `sip.day` | yes | day of month | Must be one of the scheme's `sip_dates`. |
| `sip.start_date` | yes | `YYYY-MM-DD` | First installment date; at least 2 days after today. |
| `sip.installments` | conditional | integer > 0 | Total installments. Required unless `frequency` is `DAILY`. |
| `sip.first_order_today` | no | boolean | Also place the first installment today instead of waiting for `start_date`. |
| `sip.step_up` | no | object | Raise the installment amount on a schedule (below). |
| `holding_mode` | no | `CDSL` \| `NSDL` \| `PHYSICAL` | |
| `folio_no` | conditional | string | Required to add to an existing folio. |
| `euin`, `remarks`, `client_ref` | no | | As for purchase orders. |

### Step-up (optional)

```json theme={null}
"step_up": { "amount": 500, "frequency": "ANNUAL", "start_date": "2027-11-05", "end_date": "2030-11-05" }
```

| Field | Required | Notes |
| - | - | - |
| `amount` | yes | Amount added to the installment at each step. Must be > 0. |
| `frequency` | yes | `SEMI_ANNUAL` \| `ANNUAL`. |
| `start_date` | yes | When the first step applies. |
| `end_date` | no | Stop stepping up after this date. |

### Validation

Rejected synchronously before the `202`:

| Condition | Response |
| - | - |
| `sip` object missing | `400 VALIDATION_FAILED` |
| `sip.frequency` not supported, or not allowed for the scheme | `400 VALIDATION_FAILED` |
| `sip.day` not an allowed date for the scheme | `400 VALIDATION_FAILED` |
| `sip.installments` missing (non-`DAILY`) | `400 VALIDATION_FAILED` |
| `amount` below the scheme's `min_sip` | `400 VALIDATION_FAILED` |
| `sip.start_date` invalid or less than 2 days after today | `400 VALIDATION_FAILED` |
| `sip.step_up` malformed | `400 VALIDATION_FAILED` |
| Investor not `REGISTERED` | `422 KYC_INCOMPLETE` |
| `mandate_id` not usable for `amount` | `422 MANDATE_NOT_ACTIVE` / `INSUFFICIENT_MANDATE_LIMIT` |

<Note>
  Send an `Idempotency-Key` (UUID), exactly as for purchase orders.
</Note>

## Authorise the SIP

Once the order reaches `ACCEPTED`, `GET /api/orders/v1/:id` returns a
`payment_link`. Hand it to the investor to approve the plan. It is an
authorisation page, **not** a payment page — no money moves at this step, and
you do **not** call `POST /api/payments/v1/` for a SIP.

The link can take a moment to appear after the order is accepted; poll the
order, or wait for the `order.accepted` [webhook](/api-documentation/webhooks).

```mermaid theme={null}
sequenceDiagram
    participant You
    participant Atlas
    participant Investor
    participant Bank
    You->>Atlas: POST /api/orders/v1/ (order_type SIP)
    Atlas-->>You: 202 status PENDING
    Atlas-->>You: webhook order.accepted
    You->>Atlas: GET /api/orders/v1/:id
    Atlas-->>You: payment_link
    You->>Investor: Share authorisation link
    Investor->>Atlas: Approves the SIP
    Atlas-->>You: webhook order.registered
    loop Every due date
        Bank-->>Atlas: Installment debited from mandate
    end
    You->>Atlas: GET /api/orders/v1/:id/installments
```

## SIP lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> PENDING
    PENDING --> SUBMITTED
    PENDING --> REJECTED
    SUBMITTED --> ACCEPTED
    SUBMITTED --> REJECTED
    SUBMITTED --> FAILED
    ACCEPTED --> REGISTERED
    ACCEPTED --> REJECTED
    ACCEPTED --> CANCELLED
    REGISTERED --> PAUSED
    PAUSED --> REGISTERED
    REGISTERED --> CANCELLED
    PAUSED --> CANCELLED
    REGISTERED --> REJECTED
```

| Status | Meaning |
| - | - |
| `PENDING` | Persisted; queued for registration. |
| `SUBMITTED` | Sent to the exchange. |
| `ACCEPTED` | Registration accepted; waiting for the investor's authorisation. |
| `REGISTERED` | The SIP is live and installments are being collected. |
| `PAUSED` | Upcoming installments are being skipped (see [Pause](#pause-a-sip)). |
| `CANCELLED` | Cancelled by you, the investor or the fund house — including after repeated failed installments. |
| `REJECTED` | Rejected on business grounds; reason in `provider_remark`. |
| `FAILED` | Transport failure reaching the exchange; safe to investigate/retry. |

Unlike a lumpsum order, a SIP is never `ALLOTTED` itself: each installment is
allotted units individually.

## Track a SIP

`GET /api/orders/v1/:id` returns the schedule and live progress in a
`systematic` block:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "ord_5d6e7f8a",
    "order_type": "SIP",
    "status": "REGISTERED",
    "investor_id": "I_SI_IND_000042",
    "investment_account_id": "A_RT_000001",
    "scheme_code": "128SDGP",
    "amount": 5000,
    "provider_order_id": "9912345",
    "systematic": {
      "frequency": "MONTHLY",
      "day": 5,
      "start_date": "2026-11-05",
      "installments": 24,
      "installments_paid": 3,
      "total_paid": 15000,
      "next_due_date": "2027-02-05",
      "last_paid_date": "2027-01-05"
    },
    "payment_link": "https://...",
    "created_at": "2026-10-11T10:20:00Z",
    "updated_at": "2027-01-05T21:30:00Z"
  }
}
```

The progress fields (`installments_paid` onwards) are refreshed periodically,
so they can trail a debit by a few hours.

### Installments

```http theme={null}
GET /api/orders/v1/:id/installments
```

Read-only history of the installments collected so far, oldest first. There is
no endpoint to create one — they are debited automatically on their due dates.

```json theme={null}
{
  "success": true,
  "data": [
    {
      "installment_no": 1,
      "installment_date": "2026-11-05",
      "amount": 5000,
      "status": "PAID",
      "provider_order_id": "9912346",
      "updated_at": "2026-11-06T04:10:00Z"
    }
  ]
}
```

The next scheduled installment is `systematic.next_due_date` on the order, not
a row here. The list is empty for any order type other than `SIP`.

`GET /api/orders/v1/:id/events` returns the status trail
(`{ from, to, at, remark }`).

## Manage a live SIP

### Pause a SIP

```http theme={null}
POST /api/orders/v1/:id/pause
{ "from": "2027-03-05", "no_of_installments": 2 }
```

Skips `no_of_installments` installments starting from `from`. Allowed only
while the SIP is `REGISTERED` or `PAUSED` — otherwise `409 INVALID_STATE`.
The request is acknowledged immediately, but the order's status changes
asynchronously once the pause is confirmed.

### Modify a SIP

```http theme={null}
PATCH /api/orders/v1/:id
{ "amount": 7500 }
```

Only the installment `amount` and contact/administrative fields (`folio_no`,
`euin`, `sub_broker_code`, `sub_broker_arn`, `primary_holder_email`,
`primary_holder_mobile`, `remarks`) can change. Schedule fields — frequency,
day, start date, installments — cannot; cancel and register a new SIP instead.

### Cancel a SIP

```http theme={null}
POST /api/orders/v1/:id/cancel
{ "reason": "investor request" }
```

Allowed from `PENDING`, `SUBMITTED`, `ACCEPTED`, `REGISTERED` or `PAUSED` —
otherwise `409 INVALID_STATE`. Installments already collected are unaffected;
units already allotted stay with the investor.

## Webhooks

Subscribe to `order.*` (see [Webhooks](/api-documentation/webhooks)):

| Event | When |
| - | - |
| `order.accepted` | SIP registration accepted; authorisation link becomes available. |
| `order.registered` | The SIP is live. |
| `order.cancelled` | The SIP was cancelled, including by the investor or fund house. |
| `order.rejected` / `order.failed` | Registration was refused / could not reach the exchange. |

Payloads are the usual thin `{ order_id, status, provider_remark }` — `GET` the
order for the full record.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.