API Reference SubscriptionsCreate Subscription

Create Subscription

POST/v1/subscriptionsOptional

Create a recurring subscription. cardToken is optional — it falls back to the customer's default saved card. Accepts an optional Idempotency-Key header.

Authentication

Signature Pattern

HMAC-SHA256(secretKey, "{timestamp}\nPOST\n/v1/subscriptions\n{sha256(body)}")

Header	Value	Description
`X-Api-Key`	pk_live_a1b2c3d4e5f6g7h8	Merchant public API key
`X-Signature`	{hmac_sha256_hex}	Hex HMAC-SHA256 request signature
`X-Timestamp`	2026-04-13T10:00:00Z	ISO 8601 UTC request time (±5 min)

Request Parameters

Name	Type	Required	Description
`storeId`	string	Required	Store the subscription belongs to
`customerId`	string	Required	Customer being billed
`amountMinor`	integer	Required	Per-cycle amount in kuruş
`currency`	string	Required	Always "TRY"
`intervalCount`	integer	Required	Number of interval units per cycle
`intervalUnit`	string	Required	day\|week\|month\|year
`cardToken`	string	Optional	Saved card token (defaults to the customer default card)
`trialEndAt`	string	Optional	ISO 8601 — start trialing until this date
`generateInvoices`	boolean	Optional	Generate an invoice each renewal
`description`	string	Optional	Subscription description

Request Example

JSONRequest Body

{
  "storeId": "sto_5a6b7c8d",
  "customerId": "cus_a1b2c3d4e5f6",
  "amountMinor": 50000,
  "currency": "TRY",
  "intervalCount": 1,
  "intervalUnit": "month"
}

Response Parameters

Field	Type	Example
`id`	string	"sub_5e6f70819a2b"
`merchantId`	string	"mrc_8a1b2c3d4e5f"
`storeId`	string	"sto_5a6b7c8d"
`customerId`	string	"cus_a1b2c3d4e5f6"
`publicHash`	string	"kQ7rS1tV5wY8zaB3xK9mN2"
`status`	string	"active"
`amountMinor`	integer	50000
`currency`	string	"TRY"
`intervalCount`	integer	1
`intervalUnit`	string	"month"
`cycleNumber`	integer	0
`nextChargeAt`	string	"2026-05-13T10:00:00Z"
`cardLast4`	string	"4321"
`cardBrand`	string	"visa"
`createdAt`	string	"2026-04-13T10:00:00Z"

Response Example

JSONResponse

{
  "id": "sub_5e6f70819a2b",
  "merchantId": "mrc_8a1b2c3d4e5f",
  "storeId": "sto_5a6b7c8d",
  "customerId": "cus_a1b2c3d4e5f6",
  "publicHash": "kQ7rS1tV5wY8zaB3xK9mN2",
  "status": "active",
  "amountMinor": 50000,
  "currency": "TRY",
  "intervalCount": 1,
  "intervalUnit": "month",
  "cycleNumber": 0,
  "nextChargeAt": "2026-05-13T10:00:00Z",
  "cardLast4": "4321",
  "cardBrand": "visa",
  "createdAt": "2026-04-13T10:00:00Z"
}

Status Codes

200Success

201Created

400Bad Request

401Unauthorized

404Not Found

429Rate Limited

Try itMock

POSThttps://api.pay.sandbox.kvell.group

List Subscriptions→