Skip to main content
POST
/
api
/
subscription
/
create
Create a subscription payment
curl --request POST \
  --url https://api.suby.fi/api/subscription/create \
  --header 'Content-Type: application/json' \
  --header 'X-Suby-Api-Key: <api-key>' \
  --data '
{
  "productId": "pro_sub456",
  "customerEmail": "customer@example.com",
  "customerFirstName": "John",
  "customerLastName": "Doe",
  "priceCents": "999",
  "externalRef": "sub_ref_001",
  "metadata": {},
  "customFields": [
    {
      "key": "discord_username",
      "label": "Discord username",
      "required": false,
      "placeholder": "e.g. test#1234",
      "options": [
        {
          "value": "twitter",
          "label": "Twitter / X"
        }
      ],
      "validation": {
        "regex": "^.{2,32}$",
        "errorMessage": "Please enter a valid Discord username"
      }
    }
  ],
  "successUrl": "<string>",
  "cancelUrl": "<string>"
}
'
{
  "success": true,
  "data": {
    "paymentId": "pay_sub789",
    "paymentUrl": "https://checkout.suby.fi/sub/pay_sub789",
    "metadata": {},
    "customFields": [
      {
        "key": "discord_username",
        "label": "Discord username",
        "required": false,
        "placeholder": "e.g. test#1234",
        "options": [
          {
            "value": "twitter",
            "label": "Twitter / X"
          }
        ],
        "validation": {
          "regex": "^.{2,32}$",
          "errorMessage": "Please enter a valid Discord username"
        }
      }
    ]
  }
}

Documentation Index

Fetch the complete documentation index at: https://documentation.suby.fi/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
X-Suby-Api-Key
string
header
required

API key authentication

Body

application/json
​
productId
string
required

ID of a subscription product

Example:

"pro_sub456"

​
customerEmail
string<email>

Optional. If provided, a user account is created (or reused) immediately and linked to the payment. If omitted, the payment is created without a customer; the email is collected on the hosted checkout page and the user is linked at that moment.

Example:

"customer@example.com"

​
customerFirstName
string

Optional. Customer first name. Used to prefill checkout fields. Ignored when customerEmail is omitted.

Maximum string length: 100
Example:

"John"

​
customerLastName
string

Optional. Customer last name. Used to prefill checkout fields. Ignored when customerEmail is omitted.

Maximum string length: 100
Example:

"Doe"

​
priceCents
string

Price in cents as a string. Required when the product has isCustomPrice: true. Must NOT be provided for fixed-price products. This price is locked for all future renewals.

Example:

"999"

​
currency
enum<string>

Currency for the price. Required when priceCents is provided, ignored otherwise.

Available options:
USD,
EUR
​
externalRef
string
Maximum string length: 255
Example:

"sub_ref_001"

​
metadata
object
​
customFields
object[]

Extra fields shown on the checkout page to collect information from the customer (e.g. Discord username, referral source, terms acceptance). Fields are collected on the initial checkout only — renewal payments do not re-prompt the customer. The initial payment webhook carries the responses in context.customFieldsResponse; renewal webhooks have it set to null.

Maximum 10 fields per subscription.

Maximum array length: 10
​
successUrl
string<uri>
​
cancelUrl
string<uri>

Response

Subscription payment created

​
success
boolean
Example:

true

​
data
object