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",
  "customerId": "usr_abc123",
  "customerEmail": "customer@example.com",
  "customerFirstName": "John",
  "customerLastName": "Doe",
  "priceCents": "999",
  "discountCode": "WELCOME10",
  "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>"
}
'

import requests

url = "https://api.suby.fi/api/subscription/create"

payload = {
    "productId": "pro_sub456",
    "customerId": "usr_abc123",
    "customerEmail": "customer@example.com",
    "customerFirstName": "John",
    "customerLastName": "Doe",
    "priceCents": "999",
    "discountCode": "WELCOME10",
    "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>"
}
headers = {
    "X-Suby-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Suby-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    productId: 'pro_sub456',
    customerId: 'usr_abc123',
    customerEmail: 'customer@example.com',
    customerFirstName: 'John',
    customerLastName: 'Doe',
    priceCents: '999',
    discountCode: 'WELCOME10',
    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>'
  })
};

fetch('https://api.suby.fi/api/subscription/create', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.suby.fi/api/subscription/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'productId' => 'pro_sub456',
    'customerId' => 'usr_abc123',
    'customerEmail' => 'customer@example.com',
    'customerFirstName' => 'John',
    'customerLastName' => 'Doe',
    'priceCents' => '999',
    'discountCode' => 'WELCOME10',
    '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>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Suby-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.suby.fi/api/subscription/create"

	payload := strings.NewReader("{\n  \"productId\": \"pro_sub456\",\n  \"customerId\": \"usr_abc123\",\n  \"customerEmail\": \"customer@example.com\",\n  \"customerFirstName\": \"John\",\n  \"customerLastName\": \"Doe\",\n  \"priceCents\": \"999\",\n  \"discountCode\": \"WELCOME10\",\n  \"externalRef\": \"sub_ref_001\",\n  \"metadata\": {},\n  \"customFields\": [\n    {\n      \"key\": \"discord_username\",\n      \"label\": \"Discord username\",\n      \"required\": false,\n      \"placeholder\": \"e.g. test#1234\",\n      \"options\": [\n        {\n          \"value\": \"twitter\",\n          \"label\": \"Twitter / X\"\n        }\n      ],\n      \"validation\": {\n        \"regex\": \"^.{2,32}$\",\n        \"errorMessage\": \"Please enter a valid Discord username\"\n      }\n    }\n  ],\n  \"successUrl\": \"<string>\",\n  \"cancelUrl\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Suby-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.suby.fi/api/subscription/create")
  .header("X-Suby-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"productId\": \"pro_sub456\",\n  \"customerId\": \"usr_abc123\",\n  \"customerEmail\": \"customer@example.com\",\n  \"customerFirstName\": \"John\",\n  \"customerLastName\": \"Doe\",\n  \"priceCents\": \"999\",\n  \"discountCode\": \"WELCOME10\",\n  \"externalRef\": \"sub_ref_001\",\n  \"metadata\": {},\n  \"customFields\": [\n    {\n      \"key\": \"discord_username\",\n      \"label\": \"Discord username\",\n      \"required\": false,\n      \"placeholder\": \"e.g. test#1234\",\n      \"options\": [\n        {\n          \"value\": \"twitter\",\n          \"label\": \"Twitter / X\"\n        }\n      ],\n      \"validation\": {\n        \"regex\": \"^.{2,32}$\",\n        \"errorMessage\": \"Please enter a valid Discord username\"\n      }\n    }\n  ],\n  \"successUrl\": \"<string>\",\n  \"cancelUrl\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.suby.fi/api/subscription/create")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Suby-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"productId\": \"pro_sub456\",\n  \"customerId\": \"usr_abc123\",\n  \"customerEmail\": \"customer@example.com\",\n  \"customerFirstName\": \"John\",\n  \"customerLastName\": \"Doe\",\n  \"priceCents\": \"999\",\n  \"discountCode\": \"WELCOME10\",\n  \"externalRef\": \"sub_ref_001\",\n  \"metadata\": {},\n  \"customFields\": [\n    {\n      \"key\": \"discord_username\",\n      \"label\": \"Discord username\",\n      \"required\": false,\n      \"placeholder\": \"e.g. test#1234\",\n      \"options\": [\n        {\n          \"value\": \"twitter\",\n          \"label\": \"Twitter / X\"\n        }\n      ],\n      \"validation\": {\n        \"regex\": \"^.{2,32}$\",\n        \"errorMessage\": \"Please enter a valid Discord username\"\n      }\n    }\n  ],\n  \"successUrl\": \"<string>\",\n  \"cancelUrl\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
        }
      }
    ]
  }
}

{
  "success": false,
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "Product not found"
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

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",
  "customerId": "usr_abc123",
  "customerEmail": "customer@example.com",
  "customerFirstName": "John",
  "customerLastName": "Doe",
  "priceCents": "999",
  "discountCode": "WELCOME10",
  "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>"
}
'

import requests

url = "https://api.suby.fi/api/subscription/create"

payload = {
    "productId": "pro_sub456",
    "customerId": "usr_abc123",
    "customerEmail": "customer@example.com",
    "customerFirstName": "John",
    "customerLastName": "Doe",
    "priceCents": "999",
    "discountCode": "WELCOME10",
    "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>"
}
headers = {
    "X-Suby-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Suby-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    productId: 'pro_sub456',
    customerId: 'usr_abc123',
    customerEmail: 'customer@example.com',
    customerFirstName: 'John',
    customerLastName: 'Doe',
    priceCents: '999',
    discountCode: 'WELCOME10',
    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>'
  })
};

fetch('https://api.suby.fi/api/subscription/create', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.suby.fi/api/subscription/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'productId' => 'pro_sub456',
    'customerId' => 'usr_abc123',
    'customerEmail' => 'customer@example.com',
    'customerFirstName' => 'John',
    'customerLastName' => 'Doe',
    'priceCents' => '999',
    'discountCode' => 'WELCOME10',
    '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>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Suby-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.suby.fi/api/subscription/create"

	payload := strings.NewReader("{\n  \"productId\": \"pro_sub456\",\n  \"customerId\": \"usr_abc123\",\n  \"customerEmail\": \"customer@example.com\",\n  \"customerFirstName\": \"John\",\n  \"customerLastName\": \"Doe\",\n  \"priceCents\": \"999\",\n  \"discountCode\": \"WELCOME10\",\n  \"externalRef\": \"sub_ref_001\",\n  \"metadata\": {},\n  \"customFields\": [\n    {\n      \"key\": \"discord_username\",\n      \"label\": \"Discord username\",\n      \"required\": false,\n      \"placeholder\": \"e.g. test#1234\",\n      \"options\": [\n        {\n          \"value\": \"twitter\",\n          \"label\": \"Twitter / X\"\n        }\n      ],\n      \"validation\": {\n        \"regex\": \"^.{2,32}$\",\n        \"errorMessage\": \"Please enter a valid Discord username\"\n      }\n    }\n  ],\n  \"successUrl\": \"<string>\",\n  \"cancelUrl\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Suby-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.suby.fi/api/subscription/create")
  .header("X-Suby-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"productId\": \"pro_sub456\",\n  \"customerId\": \"usr_abc123\",\n  \"customerEmail\": \"customer@example.com\",\n  \"customerFirstName\": \"John\",\n  \"customerLastName\": \"Doe\",\n  \"priceCents\": \"999\",\n  \"discountCode\": \"WELCOME10\",\n  \"externalRef\": \"sub_ref_001\",\n  \"metadata\": {},\n  \"customFields\": [\n    {\n      \"key\": \"discord_username\",\n      \"label\": \"Discord username\",\n      \"required\": false,\n      \"placeholder\": \"e.g. test#1234\",\n      \"options\": [\n        {\n          \"value\": \"twitter\",\n          \"label\": \"Twitter / X\"\n        }\n      ],\n      \"validation\": {\n        \"regex\": \"^.{2,32}$\",\n        \"errorMessage\": \"Please enter a valid Discord username\"\n      }\n    }\n  ],\n  \"successUrl\": \"<string>\",\n  \"cancelUrl\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.suby.fi/api/subscription/create")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Suby-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"productId\": \"pro_sub456\",\n  \"customerId\": \"usr_abc123\",\n  \"customerEmail\": \"customer@example.com\",\n  \"customerFirstName\": \"John\",\n  \"customerLastName\": \"Doe\",\n  \"priceCents\": \"999\",\n  \"discountCode\": \"WELCOME10\",\n  \"externalRef\": \"sub_ref_001\",\n  \"metadata\": {},\n  \"customFields\": [\n    {\n      \"key\": \"discord_username\",\n      \"label\": \"Discord username\",\n      \"required\": false,\n      \"placeholder\": \"e.g. test#1234\",\n      \"options\": [\n        {\n          \"value\": \"twitter\",\n          \"label\": \"Twitter / X\"\n        }\n      ],\n      \"validation\": {\n        \"regex\": \"^.{2,32}$\",\n        \"errorMessage\": \"Please enter a valid Discord username\"\n      }\n    }\n  ],\n  \"successUrl\": \"<string>\",\n  \"cancelUrl\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
        }
      }
    ]
  }
}

{
  "success": false,
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "Product not found"
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

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"

customerId

string

Optional. Links the subscription to an existing customer by their stable id (as returned by GET /api/customer and on payment responses/webhooks). Keeps the same customer linked even if their email has changed. Takes precedence over customerEmail. Returns 404 if unknown.

Maximum string length: 255

Example:

"usr_abc123"

customerEmail

string<email>

Optional. If provided (and no customerId is given), a user account is created (or reused by email) immediately and linked to the payment. If both are omitted, the payment is created without a customer; the email is collected on the hosted checkout page.

Example:

"customer@example.com"

customerFirstName

string

Optional. Customer first name. Backfills the display name when the customer has none. Ignored when neither customerId nor customerEmail is provided.

Maximum string length: 100

Example:

"John"

customerLastName

string

Optional. Customer last name. Backfills the display name when the customer has none. Ignored when neither customerId nor customerEmail is provided.

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

discountCode

string

Optional. A discount code (created via POST /api/discount/create) to pre-apply to this subscription checkout. Applied to the amount the customer pays. Ignored if the code is invalid, expired, exhausted, or not attached to this product.

Maximum string length: 50

Example:

"WELCOME10"

externalRef

string

Your internal reference for this subscription (e.g. an end-user account or wallet id). It is the subscription-ownership key: reusing the same externalRef for the same customer + product renews the existing subscription, while a different externalRef creates a separate subscription that is billed and renewed independently. Omit it to place the subscription in the shared "no external reference" bucket for that customer + product. Returned on the subscription object and on every subscription webhook.

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

Show child attributes

successUrl

string<uri>

cancelUrl

string<uri>

Response

Subscription payment created

success

boolean

Example:

true

data

object

Show child attributes

Initiate a payment (deprecated)List subscriptions

Overview

Endpoints

Create a subscription payment

Authorizations

Body

Response