# Memberships & Subscriptions

Create, update, and cancel subscription-based products through the API.

Source: https://developer.inoviopay.com/api/memberships.html  
Markdown: https://developer.inoviopay.com/api/memberships.md

The gateway provides full lifecycle management for subscription-based products. Subscriptions can be defined either in the portal or directly through the API during the initial authorization.

### Direct Creation Parameters

| Parameter | Description |
|---|---|
| `PROD_NAME` | Name for the new subscription product. |
| `PROD_TYPE` | 1 = Cancels after period; 2 = Auto-renews. |
| `PROD_REBILL_METRIC` | Interval type: M (Month), D (Day), Y (Year). |
| `PROD_REBILL_PERIOD` | Numeric interval (e.g., 30 for monthly). |

### Management Actions (Cancel & Update)

Use the following actions to manage an existing membership record.

| Parameter | Description |
|---|---|
| `REQUEST_ACTION` (required) | Must be set to `SUB_CANCEL` or `SUB_UPDATE`. |
| `REQUEST_REF_MBSHP_ID` (required) | The existing Membership ID you wish to modify. |
| `SUB_CANCEL_TYPE` (optional) | Used with `SUB_CANCEL`. Set to `1` to cancel immediately, or `2` to cancel on the next scheduled rebill date. |
| `SUB_UPDATE_PROD_ID` (optional) | Used with `SUB_UPDATE` to change the current product ID of the membership record. |
| `SUB_UPDATE_PMT_ID` (optional) | Used with `SUB_UPDATE` to change the credit card/payment method tied to the specific membership. |

### Handling the Response

When updating a membership, ensure the `SERVICE_RESPONSE` indicates success (e.g., `102` for "Membership Updated") and check the `MBSHP_REBILL_TS_UTC` to confirm the next billing cycle date.

| Field Name | Description |
|---|---|
| `API_RESPONSE / SERVICE_RESPONSE` | Check these values for `0` or `102` to verify the request was successfully processed. |
| `MBSHP_ID` | The unique Membership ID that was modified or cancelled. |
| `MBSHP_REBILL_TS_UTC` | The UTC timestamp of when the next billing cycle will occur. |
| `MBSHP_CANCEL_TS_UTC` | The UTC timestamp of when the cancellation is scheduled to take effect (if applicable). |
| `CUST_ID` | The Customer ID tied to the membership. |

### Update membership example


> **Not in the SDKs yet**
> Membership/subscription management is not implemented in any of the four SDKs. `SUB_UPDATE` and `SUB_CANCEL` exist only as labels in the generated `RequestAction` enum; no client method builds either request, and none of `sale()`/`authorize()`/`capture()` accept an arbitrary `REQUEST_ACTION` override. Use the cURL example directly, or see [the SDKs](https://developer.inoviopay.com/sdks/index.md).

### Cancel membership example


> **Not in the SDKs yet**
> Same as above: no SDK builds a `SUB_CANCEL` request. See [the SDKs](https://developer.inoviopay.com/sdks/index.md).

**cURL**

```bash
curl -X POST "https://api.inoviopay.com/payment/pmt_service.cfm" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "request_action=SUB_UPDATE&req_username=api_user&req_password=P%40ssw0rd%21&site_id=12345&request_api_version=4.14&request_response_format=JSON&request_ref_mbshp_id=83262&sub_update_prod_id=99281"
```

**Response**

```json
{
  "REQUEST_ACTION": "SUB_UPDATE",
  "API_RESPONSE": "0",
  "API_ADVICE": "",
  "SERVICE_RESPONSE": 102,
  "SERVICE_ADVICE": "Membership Updated",
  "REF_FIELD": "",
  "CUST_ID": 8076911,
  "MBSHP_ID": 83262,
  "MBSHP_CANCEL_TS_UTC": "",
  "MBSHP_REBILL_TS_UTC": "March, 25 2026 19:34:39"
}
```

**cURL**

```bash
curl -X POST "https://api.inoviopay.com/payment/pmt_service.cfm" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "request_action=SUB_CANCEL&req_username=api_user&req_password=P%40ssw0rd%21&site_id=12345&request_api_version=4.14&request_response_format=JSON&request_ref_mbshp_id=92831&sub_cancel_type=2"
```

**Response**

```json
{
  "REQUEST_ACTION": "SUB_CANCEL",
  "API_RESPONSE": "0",
  "API_ADVICE": "",
  "SERVICE_RESPONSE": 0,
  "SERVICE_ADVICE": "",
  "REF_FIELD": "",
  "CUST_ID": 7283921,
  "MBSHP_ID": 92831,
  "MBSHP_CANCEL_TS_UTC": "April, 30 2026 15:30:35",
  "MBSHP_REBILL_TS_UTC": ""
}
```