# Get Subscription by Merchant Subscription Reference

**Method:** `GET`

**Path:** `/ps/api/v1/public/subscriptions/reference/{merchant_subscription_reference}`

**Category:** Subscriptions - Subscriptions

**Authentication:** Required

## Description

Retrieves a specific subscription by the merchant subscription reference.


## Path Parameters

- `merchant_subscription_reference` (`string`) **required** — Unique identifier of the merchant subscription reference.

## Responses

- `200` — Subscription retrieved successfully.
- `500` — 

### Response Schema

- `order_id` (`string`) — Unique identifier of the order in the Pine Labs Online database.
- `subscription_id` (`string`) — Unique identifier for the subscription.
- `merchant_subscription_reference` (`string`) — Unique identifier of the merchant subscription reference.
- `enable_notification` (`boolean`) — Indicates if notifications are enabled.
- `plan_details` (`object`) — Plan object returned in create, get, and update responses.
  - `plan_id` (`string`) — Unique identifier for the subscription plan in the Pine Labs database.
  - `status` (`ACTIVE | INACTIVE | CREATED`) — Status of the plan. - ACTIVE: Plan creation completed and start time has passed. - INACTIVE: Plan is disabled or has exceeded its validity period. - CREATED: Plan creation completed but start time is in the future. 
  - `plan_name` (`string`) — Subscription plan name.
  - `plan_description` (`string`) — Corresponding description for a plan.
  - `frequency` (`Day | Week | Month | Year | Bi-Monthly | Quarterly | Half-Yearly | AS | OT | Not Applicable`) — Frequency of recurring transactions for this particular plan.
  - `amount` (`object`) — Monetary amount with currency for subscription-related APIs.
    - `value` (`integer`) **required** — Amount in the smallest currency unit (paisa for INR). Minimum ₹1 (100), maximum ₹10 lakh (100000000).
    - `currency` (`string`) **required** — Three-letter ISO 4217 currency code.

  - `max_limit_amount` (`object`) — Monetary amount with currency for subscription-related APIs.
    - `value` (`integer`) **required** — Amount in the smallest currency unit (paisa for INR). Minimum ₹1 (100), maximum ₹10 lakh (100000000).
    - `currency` (`string`) **required** — Three-letter ISO 4217 currency code.

  - `trial_period_in_days` (`integer`) — Duration of the trial period in days.
  - `start_date` (`string`) — The ISO 8601 UTC Timestamp when the subscription plan is active.
  - `end_date` (`string`) — The ISO 8601 UTC Timestamp when the subscription plan expires.
  - `merchant_metadata` (`object`) — Key-value pairs for additional information. Max 10 pairs, 256 chars each.
  - `merchant_plan_reference` (`string`) — Unique identifier of the merchant plan reference.
  - `created_at` (`string,null`) — ISO 8601 UTC Timestamp when the create plan request was received.
  - `modified_at` (`string,null`) — ISO 8601 UTC Timestamp when the plan was last updated.
  - `initial_debit_amount` (`object`) — Monetary amount with currency for subscription-related APIs.
    - `value` (`integer`) **required** — Amount in the smallest currency unit (paisa for INR). Minimum ₹1 (100), maximum ₹10 lakh (100000000).
    - `currency` (`string`) **required** — Three-letter ISO 4217 currency code.

  - `auto_debit_ot` (`string`) — Indicates whether auto-debit is enabled for one-time payments.

- `quantity` (`integer`) — The quantity of the subscription for the selected plan.
- `start_date` (`string`) — The ISO 8601 UTC Timestamp when the subscription starts.
- `end_date` (`string`) — The ISO 8601 UTC Timestamp when the subscription expires.
- `customer_id` (`string`) — Unique identifier of the customer.
- `payment_mode` (`CARD | UPI`) — Payment methods allowed for subscription.
- `allowed_payment_methods` (`string[]`) — The type of payment methods offered to customers.
- `integration_mode` (`SEAMLESS | REDIRECT`) — Type of integration.
- `merchant_metadata` (`object`) — Key-value pairs for additional information.
- `status` (`CREATED | TRIAL | ACTIVE | PAUSED | RESUMING | RESUMED | DEBIT_FAILED | UPDATING | COMPLETED | EXPIRED | CANCELLED | CANCELLING | HALTED | INACTIVE`) — Status of the Subscription.
- `is_tpv_enabled` (`boolean`) — Indicates if Third-Party Validation (TPV) is enabled.
- `bank_account` (`object`) — Bank account details for Third-Party Validation (TPV).
  - `account_number` (`string,null`) — Bank account number.
  - `name` (`string,null`) — Name of Customer.
  - `ifsc` (`string,null`) — IFSC code of the bank account.

- `created_at` (`string`) — ISO 8601 UTC Timestamp when the subscription was created.
- `modified_at` (`string`) — ISO 8601 UTC Timestamp when the subscription was last updated.
- `order_amount` (`object`) — Monetary amount with currency for subscription-related APIs.
  - `value` (`integer`) **required** — Amount in the smallest currency unit (paisa for INR). Minimum ₹1 (100), maximum ₹10 lakh (100000000).
  - `currency` (`string`) **required** — Three-letter ISO 4217 currency code.


### Example Response

```json
{
  "order_id": "v1-4405071524-aa-qlAtAf",
  "subscription_id": "v1-sub-4405071524-aa-qlAtAf",
  "merchant_subscription_reference": "1234567890",
  "enable_notification": true,
  "plan_details": {
    "plan_id": "v1-plan-4405071524-aa-qlAtAf",
    "status": "ACTIVE",
    "plan_name": "Monthly Plan",
    "plan_description": "Diwali dhammaka plan intended to attract customers on diwali time",
    "frequency": "Day",
    "amount": {
      "value": 1000,
      "currency": "INR"
    },
    "max_limit_amount": {
      "value": 1000,
      "currency": "INR"
    },
    "trial_period_in_days": 1,
    "start_date": "2022-02-01T17:32:28Z",
    "end_date": "2022-10-21T17:32:28Z",
    "merchant_metadata": {
      "key1": "DD",
      "key2": "XOF"
    },
    "merchant_plan_reference": "1234567890",
    "created_at": "2022-10-21T17:32:28Z",
    "modified_at": "2022-10-21T17:32:28Z",
    "initial_debit_amount": {
      "value": 1000,
      "currency": "INR"
    },
    "auto_debit_ot": "false"
  },
  "quantity": 1,
  "start_date": "2022-07-21T17:32:28Z",
  "end_date": "2022-09-21T17:32:28Z",
  "customer_id": "123456",
  "payment_mode": "UPI",
  "allowed_payment_methods": [
    "UPI"
  ],
  "integration_mode": "SEAMLESS",
  "merchant_metadata": {
    "key1": "DD",
    "key2": "XOF"
  },
  "status": "ACTIVE",
  "is_tpv_enabled": true,
  "bank_account": {
    "account_number": "12345678912345",
    "name": "Kevin Bob",
    "ifsc": "HDFC0001234"
  },
  "created_at": "2022-10-21T17:32:28Z",
  "modified_at": "2022-10-21T17:32:28Z",
  "order_amount": {
    "value": 1000,
    "currency": "INR"
  }
}
```

---

Reference: https://localhost:3000/api/subscriptions-subscriptions/get-subscription-by-merchant-reference