Start a subscription

curl --request POST \
  --url https://api.beta.suby.fi/v3/subscriptions \
  --header 'Content-Type: application/json' \
  --header 'X-Suby-Api-Key: <api-key>' \
  --data '
{
  "productId": "pro_abc123",
  "customerId": "cus_abc123",
  "billingAddress": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postalCode": "<string>",
    "country": "<string>"
  },
  "businessData": {
    "purchaseAsBusiness": true,
    "businessName": "<string>",
    "taxId": "<string>"
  },
  "card": {
    "tokenizedInstrument": "<string>"
  },
  "crypto": {
    "chainId": 123,
    "assetId": 123
  },
  "successUrl": "<string>",
  "cancelUrl": "<string>",
  "externalRef": "<string>",
  "metadata": {}
}
'

import requests

url = "https://api.beta.suby.fi/v3/subscriptions"

payload = {
    "productId": "pro_abc123",
    "customerId": "cus_abc123",
    "billingAddress": {
        "line1": "<string>",
        "line2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "postalCode": "<string>",
        "country": "<string>"
    },
    "businessData": {
        "purchaseAsBusiness": True,
        "businessName": "<string>",
        "taxId": "<string>"
    },
    "card": { "tokenizedInstrument": "<string>" },
    "crypto": {
        "chainId": 123,
        "assetId": 123
    },
    "successUrl": "<string>",
    "cancelUrl": "<string>",
    "externalRef": "<string>",
    "metadata": {}
}
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_abc123',
    customerId: 'cus_abc123',
    billingAddress: {
      line1: '<string>',
      line2: '<string>',
      city: '<string>',
      state: '<string>',
      postalCode: '<string>',
      country: '<string>'
    },
    businessData: {purchaseAsBusiness: true, businessName: '<string>', taxId: '<string>'},
    card: {tokenizedInstrument: '<string>'},
    crypto: {chainId: 123, assetId: 123},
    successUrl: '<string>',
    cancelUrl: '<string>',
    externalRef: '<string>',
    metadata: {}
  })
};

fetch('https://api.beta.suby.fi/v3/subscriptions', 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.beta.suby.fi/v3/subscriptions",
  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_abc123',
    'customerId' => 'cus_abc123',
    'billingAddress' => [
        'line1' => '<string>',
        'line2' => '<string>',
        'city' => '<string>',
        'state' => '<string>',
        'postalCode' => '<string>',
        'country' => '<string>'
    ],
    'businessData' => [
        'purchaseAsBusiness' => true,
        'businessName' => '<string>',
        'taxId' => '<string>'
    ],
    'card' => [
        'tokenizedInstrument' => '<string>'
    ],
    'crypto' => [
        'chainId' => 123,
        'assetId' => 123
    ],
    'successUrl' => '<string>',
    'cancelUrl' => '<string>',
    'externalRef' => '<string>',
    'metadata' => [
        
    ]
  ]),
  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.beta.suby.fi/v3/subscriptions"

	payload := strings.NewReader("{\n  \"productId\": \"pro_abc123\",\n  \"customerId\": \"cus_abc123\",\n  \"billingAddress\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"postalCode\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"businessData\": {\n    \"purchaseAsBusiness\": true,\n    \"businessName\": \"<string>\",\n    \"taxId\": \"<string>\"\n  },\n  \"card\": {\n    \"tokenizedInstrument\": \"<string>\"\n  },\n  \"crypto\": {\n    \"chainId\": 123,\n    \"assetId\": 123\n  },\n  \"successUrl\": \"<string>\",\n  \"cancelUrl\": \"<string>\",\n  \"externalRef\": \"<string>\",\n  \"metadata\": {}\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.beta.suby.fi/v3/subscriptions")
  .header("X-Suby-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"productId\": \"pro_abc123\",\n  \"customerId\": \"cus_abc123\",\n  \"billingAddress\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"postalCode\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"businessData\": {\n    \"purchaseAsBusiness\": true,\n    \"businessName\": \"<string>\",\n    \"taxId\": \"<string>\"\n  },\n  \"card\": {\n    \"tokenizedInstrument\": \"<string>\"\n  },\n  \"crypto\": {\n    \"chainId\": 123,\n    \"assetId\": 123\n  },\n  \"successUrl\": \"<string>\",\n  \"cancelUrl\": \"<string>\",\n  \"externalRef\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.beta.suby.fi/v3/subscriptions")

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_abc123\",\n  \"customerId\": \"cus_abc123\",\n  \"billingAddress\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"postalCode\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"businessData\": {\n    \"purchaseAsBusiness\": true,\n    \"businessName\": \"<string>\",\n    \"taxId\": \"<string>\"\n  },\n  \"card\": {\n    \"tokenizedInstrument\": \"<string>\"\n  },\n  \"crypto\": {\n    \"chainId\": 123,\n    \"assetId\": 123\n  },\n  \"successUrl\": \"<string>\",\n  \"cancelUrl\": \"<string>\",\n  \"externalRef\": \"<string>\",\n  \"metadata\": {}\n}"

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

{
  "success": true,
  "data": {
    "subscription": {
      "id": "sub_abc123",
      "organizationId": "<string>",
      "customerId": "<string>",
      "productId": "<string>",
      "currentCycle": 123,
      "totalCycles": 123,
      "trialEndAt": "2023-11-07T05:31:56Z",
      "cancelAtPeriodEnd": true,
      "currentCycleDueAt": "2023-11-07T05:31:56Z",
      "renewalAttempt": 123,
      "nextRenewalAttemptAt": "2023-11-07T05:31:56Z",
      "externalRef": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    },
    "firstPayment": {
      "id": "<string>",
      "status": "<string>",
      "priceCents": "<string>",
      "currency": "<string>"
    },
    "checkout": {
      "providerPaymentId": "<string>",
      "threeDsChallengeUrl": "<string>",
      "redirectUrl": "<string>",
      "clientSecret": "<string>"
    },
    "instruction": {
      "kind": "qr_deposit",
      "chainId": 123,
      "depositAddress": "<string>",
      "expectedAmount": "<string>",
      "decimals": 123,
      "symbol": "<string>",
      "address": "<string>",
      "bip21Uri": "<string>",
      "surchargeNote": "<string>"
    }
  },
  "message": "<string>"
}

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

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

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Validation failed",
  "data": {
    "fieldErrors": [
      {
        "field": "method",
        "message": "method is a required field"
      }
    ]
  }
}

Subscriptions

Start a subscription

Start a subscription on a recurring product and run the first-cycle customer-initiated payment. Provide exactly one of customerId / customerData. method is one of CARD, APPLE_PAY, GOOGLE_PAY, CRYPTO.

Card family (CARD / APPLE_PAY / GOOGLE_PAY) — pass a fresh card.tokenizedInstrument. The first cycle is a customer-present CIT (3DS if the issuer requires SCA); the network credential is stored so Suby re-charges the renewal cycles off-session. Failed renewals are retried automatically on a progressive back-off schedule (up to 8 attempts over 30 days) — soft declines (insufficient funds, network/issuer errors, velocity limits) are retried; hard declines (stolen/lost card, closed account) end the subscription immediately.
Crypto (method=CRYPTO) — no card; instead pass crypto.mode (qr_deposit | wallet_connect), crypto.chainId, and crypto.assetId, exactly like a one-time crypto payment. The first cycle is a customer-present deposit (the response carries a deposit instruction rather than a card checkout handle). Renewals are driven by a per-cycle renew email (no off-session pull for crypto).

POST

subscriptions

curl --request POST \
  --url https://api.beta.suby.fi/v3/subscriptions \
  --header 'Content-Type: application/json' \
  --header 'X-Suby-Api-Key: <api-key>' \
  --data '
{
  "productId": "pro_abc123",
  "customerId": "cus_abc123",
  "billingAddress": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postalCode": "<string>",
    "country": "<string>"
  },
  "businessData": {
    "purchaseAsBusiness": true,
    "businessName": "<string>",
    "taxId": "<string>"
  },
  "card": {
    "tokenizedInstrument": "<string>"
  },
  "crypto": {
    "chainId": 123,
    "assetId": 123
  },
  "successUrl": "<string>",
  "cancelUrl": "<string>",
  "externalRef": "<string>",
  "metadata": {}
}
'

import requests

url = "https://api.beta.suby.fi/v3/subscriptions"

payload = {
    "productId": "pro_abc123",
    "customerId": "cus_abc123",
    "billingAddress": {
        "line1": "<string>",
        "line2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "postalCode": "<string>",
        "country": "<string>"
    },
    "businessData": {
        "purchaseAsBusiness": True,
        "businessName": "<string>",
        "taxId": "<string>"
    },
    "card": { "tokenizedInstrument": "<string>" },
    "crypto": {
        "chainId": 123,
        "assetId": 123
    },
    "successUrl": "<string>",
    "cancelUrl": "<string>",
    "externalRef": "<string>",
    "metadata": {}
}
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_abc123',
    customerId: 'cus_abc123',
    billingAddress: {
      line1: '<string>',
      line2: '<string>',
      city: '<string>',
      state: '<string>',
      postalCode: '<string>',
      country: '<string>'
    },
    businessData: {purchaseAsBusiness: true, businessName: '<string>', taxId: '<string>'},
    card: {tokenizedInstrument: '<string>'},
    crypto: {chainId: 123, assetId: 123},
    successUrl: '<string>',
    cancelUrl: '<string>',
    externalRef: '<string>',
    metadata: {}
  })
};

fetch('https://api.beta.suby.fi/v3/subscriptions', 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.beta.suby.fi/v3/subscriptions",
  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_abc123',
    'customerId' => 'cus_abc123',
    'billingAddress' => [
        'line1' => '<string>',
        'line2' => '<string>',
        'city' => '<string>',
        'state' => '<string>',
        'postalCode' => '<string>',
        'country' => '<string>'
    ],
    'businessData' => [
        'purchaseAsBusiness' => true,
        'businessName' => '<string>',
        'taxId' => '<string>'
    ],
    'card' => [
        'tokenizedInstrument' => '<string>'
    ],
    'crypto' => [
        'chainId' => 123,
        'assetId' => 123
    ],
    'successUrl' => '<string>',
    'cancelUrl' => '<string>',
    'externalRef' => '<string>',
    'metadata' => [
        
    ]
  ]),
  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.beta.suby.fi/v3/subscriptions"

	payload := strings.NewReader("{\n  \"productId\": \"pro_abc123\",\n  \"customerId\": \"cus_abc123\",\n  \"billingAddress\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"postalCode\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"businessData\": {\n    \"purchaseAsBusiness\": true,\n    \"businessName\": \"<string>\",\n    \"taxId\": \"<string>\"\n  },\n  \"card\": {\n    \"tokenizedInstrument\": \"<string>\"\n  },\n  \"crypto\": {\n    \"chainId\": 123,\n    \"assetId\": 123\n  },\n  \"successUrl\": \"<string>\",\n  \"cancelUrl\": \"<string>\",\n  \"externalRef\": \"<string>\",\n  \"metadata\": {}\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.beta.suby.fi/v3/subscriptions")
  .header("X-Suby-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"productId\": \"pro_abc123\",\n  \"customerId\": \"cus_abc123\",\n  \"billingAddress\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"postalCode\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"businessData\": {\n    \"purchaseAsBusiness\": true,\n    \"businessName\": \"<string>\",\n    \"taxId\": \"<string>\"\n  },\n  \"card\": {\n    \"tokenizedInstrument\": \"<string>\"\n  },\n  \"crypto\": {\n    \"chainId\": 123,\n    \"assetId\": 123\n  },\n  \"successUrl\": \"<string>\",\n  \"cancelUrl\": \"<string>\",\n  \"externalRef\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.beta.suby.fi/v3/subscriptions")

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_abc123\",\n  \"customerId\": \"cus_abc123\",\n  \"billingAddress\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"postalCode\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"businessData\": {\n    \"purchaseAsBusiness\": true,\n    \"businessName\": \"<string>\",\n    \"taxId\": \"<string>\"\n  },\n  \"card\": {\n    \"tokenizedInstrument\": \"<string>\"\n  },\n  \"crypto\": {\n    \"chainId\": 123,\n    \"assetId\": 123\n  },\n  \"successUrl\": \"<string>\",\n  \"cancelUrl\": \"<string>\",\n  \"externalRef\": \"<string>\",\n  \"metadata\": {}\n}"

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

{
  "success": true,
  "data": {
    "subscription": {
      "id": "sub_abc123",
      "organizationId": "<string>",
      "customerId": "<string>",
      "productId": "<string>",
      "currentCycle": 123,
      "totalCycles": 123,
      "trialEndAt": "2023-11-07T05:31:56Z",
      "cancelAtPeriodEnd": true,
      "currentCycleDueAt": "2023-11-07T05:31:56Z",
      "renewalAttempt": 123,
      "nextRenewalAttemptAt": "2023-11-07T05:31:56Z",
      "externalRef": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    },
    "firstPayment": {
      "id": "<string>",
      "status": "<string>",
      "priceCents": "<string>",
      "currency": "<string>"
    },
    "checkout": {
      "providerPaymentId": "<string>",
      "threeDsChallengeUrl": "<string>",
      "redirectUrl": "<string>",
      "clientSecret": "<string>"
    },
    "instruction": {
      "kind": "qr_deposit",
      "chainId": 123,
      "depositAddress": "<string>",
      "expectedAmount": "<string>",
      "decimals": 123,
      "symbol": "<string>",
      "address": "<string>",
      "bip21Uri": "<string>",
      "surchargeNote": "<string>"
    }
  },
  "message": "<string>"
}

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

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

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Validation failed",
  "data": {
    "fieldErrors": [
      {
        "field": "method",
        "message": "method is a required field"
      }
    ]
  }
}

Authorizations

X-Suby-Api-Key

string

header

required

Secret API key. sk_live_… (production) or sk_sandbox_… (sandbox).

Headers

Idempotency-Key

string

Optional key (≤255 chars, e.g. a UUID v4) that makes this POST safe to retry: the first request executes and its response is cached for 24h; a retry with the SAME key replays that response instead of re-executing (no duplicate payment/subscription). A reused key with a different request → 422 IDEMPOTENCY_KEY_CONFLICT; a retry while the first is still in flight → 409. See the Idempotency guide.

Maximum string length: 255

Example:

"5f3b9c2e-1a4d-4f2b-9c31-7e2a1b6d8c04"

Body

application/json

productId

string

required

Example:

"pro_abc123"

method

enum<string>

required

Available options:

CARD,

APPLE_PAY,

GOOGLE_PAY,

CRYPTO

customerId

string

Mutually exclusive with customerData.

Example:

"cus_abc123"

customerData

object

Inline customer for create-on-the-fly. Mutually exclusive with customerId.

Show child attributes

taxBehavior

enum<string>

MoR VAT for the recurring price (applies to every cycle). exclusive (default) adds VAT on top; inclusive treats the price as VAT-inclusive.

Available options:

inclusive,

exclusive

billingAddress

object

Show child attributes

businessData

object

B2B purchase details. Accepted on ALL accounts — businessName / taxId are always stored on the customer, and businessName doubles as the card holder name. The VAT reverse-charge it triggers (0% VAT except France) only takes effect on Merchant-of-Record accounts; on non-MoR accounts no VAT applies at all, so it has no tax effect.

Show child attributes

card

object

Card options. Required for the card family; omit for CRYPTO.

Show child attributes

crypto

object

Crypto first-cycle routing. Required when method=CRYPTO; omit for the card family.

Show child attributes

successUrl

string<uri>

cancelUrl

string<uri>

externalRef

string

Your business reference (plan/order id). Stored + echoed on the subscription. Not unique.

Maximum string length: 120

metadata

object

Key-value pairs. ≤50 keys, keys ≤40 chars, values are strings ≤500 chars (or null to clear). Nested structures must be JSON-stringified into a single string value.

Show child attributes

Response

Subscription started

success

boolean

required

Example:

true

data

object

required

Endpoint-specific payload.

Show child attributes

message

string

Get the receipt (PDF)Cancel a subscription

Overview

Endpoints

Start a subscription

Authorizations

Headers

Body

Response