Paymish Loading Docs Preparing guides, collections, and live API references...
Paymish Docs

Create a new subscription

Topics

Endpoint Overview

Subscription

Create a new subscription

POST /api/payment-service/external/v1/subscription Requires authentication

Purpose

Use this endpoint to create a new subscription. It belongs to the Subscription collection and is designed for backend integrations.

Request shape

0 parameters and 10 documented body fields using application/json.

Implementation Guide

Recommended workflow

1

Authenticate first and inject a valid bearer token or secret key before calling the endpoint.

2

Validate the input data, identifiers, and account state in your application before making the request.

3

Send the POST request from your backend using the required headers and the expected content type (application/json).

4

Persist the important identifiers returned in the response so later lookups, webhooks, or support actions can be linked correctly.

Implementation notes

  • Validate the request payload on your backend before sending it, especially the 10 documented body fields.
  • Protect state-changing operations with strong validation, logging, and retry rules to avoid duplicate mutations.

Request Body

Content type: application/json

planId required
number
The ID of the subscription plan.
planName required
string
The name of the subscription plan.
customerId required
string
The ID of the customer subscribing.
amount required
number
The amount charged for the subscription.
nextPaymentDate required
string
The date of the next payment.
startDate required
string
The start date of the subscription.
subscriptionCode required
string
A unique code for the subscription.
paymentCount required
integer
The number of payments made so far.
interval required
string
The interval of payments (e.g., monthly, yearly).
status required
string
The status of the subscription (e.g., active, canceled).

Responses

201 Subscription created successfully.
400 Bad request due to missing or invalid parameters.
401 Unauthorized access, bearer token required.
500 Internal server error.

Expected Outcomes

201

Success example

Subscription created successfully.

Representative Response 
{
  "message": "Subscription created successfully.",
  "subscription": "value"
}
400

Failure example

Bad request due to missing or invalid parameters.

Representative Error 
{
  "status": "error",
  "message": "Invalid request payload. Check `planId` and try again.",
  "errors": {
    "planId": [
      "`planId` is required."
    ]
  }
}
After the response:
  • Log the Paymish reference or request context returned by the API so support teams can trace the call later.
  • Retry only when the failure is safe to repeat; otherwise correct the payload or auth state first.
  • Store enough internal metadata to match the API response back to your order, payout, case, or checkout record.

Language Notes

Python

Use `requests` from a backend worker, service, or Django/Flask app and centralize headers in a reusable helper.

Node.js

Use `axios` or `fetch` from Node.js services only; do not place secret credentials in frontend bundles.

PHP

Wrap cURL usage in a small client class so auth headers, error handling, and logging stay consistent.

cURL

Use cURL for smoke testing and debugging, then move the final logic into your backend service code.

Code Examples

Python 
import requests

headers = {
    "Authorization": "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json",
}
payload = {
  "planId": 0.0,
  "planName": "value",
  "customerId": "value",
  "amount": 0.0,
  "nextPaymentDate": "value"
}

response = requests.post(
    "https://api.paymish.com/api/payment-service/external/v1/subscription",
    headers=headers,
    json=payload,
)

data = response.json()
print(data)
Node.js 
const axios = require("axios");

const response = await axios({
  method: "post",
  url: "https://api.paymish.com/api/payment-service/external/v1/subscription",
  headers: {
    Authorization: "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json",
  },
  data: {
  "planId": 0.0,
  "planName": "value",
  "customerId": "value",
  "amount": 0.0,
  "nextPaymentDate": "value"
}
});

console.log(response.data);
cURL 
curl https://api.paymish.com/api/payment-service/external/v1/subscription \
  -X POST \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{   "planId": 0.0,   "planName": "value",   "customerId": "value",   "amount": 0.0,   "nextPaymentDate": "value" }'
PHP 
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.paymish.com/api/payment-service/external/v1/subscription");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_SECRET_KEY",
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "planId" => 0.0,
    "planName" => "value",
    "customerId" => "value",
    "amount" => 0.0,
    "nextPaymentDate" => "value",
]));

$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
print_r($data);
Previous endpoint Retrieve a list of subscriptions Next endpoint Get a subscription by ID