Subscriptions
Create a Subscription
Create a recurring subscription from a single-use card token or with Pix Automático.
POST
/
v2
/
subscriptions
Create a Subscription
curl --request POST \
--url https://api.pagou.ai/v2/subscriptions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"customer_id": "<string>",
"amount": 50000000,
"token": "<string>",
"interval_count": 1,
"failure_policy": "retry_then_cancel",
"retry_offsets_days": [
15
],
"currency": "BRL",
"metadata": {},
"informations": [
{
"key": "<string>",
"value": "<string>"
}
],
"idempotency_key": "<string>",
"products": [
{
"name": "<string>",
"price": 50000000,
"quantity": 1,
"tangible": false,
"sku": "<string>"
}
],
"payment_method": "credit_card",
"trial_end": "2023-11-07T05:31:56Z"
}
'import requests
url = "https://api.pagou.ai/v2/subscriptions"
payload = {
"customer_id": "<string>",
"amount": 50000000,
"token": "<string>",
"interval_count": 1,
"failure_policy": "retry_then_cancel",
"retry_offsets_days": [15],
"currency": "BRL",
"metadata": {},
"informations": [
{
"key": "<string>",
"value": "<string>"
}
],
"idempotency_key": "<string>",
"products": [
{
"name": "<string>",
"price": 50000000,
"quantity": 1,
"tangible": False,
"sku": "<string>"
}
],
"payment_method": "credit_card",
"trial_end": "2023-11-07T05:31:56Z"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
customer_id: '<string>',
amount: 50000000,
token: '<string>',
interval_count: 1,
failure_policy: 'retry_then_cancel',
retry_offsets_days: [15],
currency: 'BRL',
metadata: {},
informations: [{key: '<string>', value: '<string>'}],
idempotency_key: '<string>',
products: [
{
name: '<string>',
price: 50000000,
quantity: 1,
tangible: false,
sku: '<string>'
}
],
payment_method: 'credit_card',
trial_end: '2023-11-07T05:31:56Z'
})
};
fetch('https://api.pagou.ai/v2/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.pagou.ai/v2/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([
'customer_id' => '<string>',
'amount' => 50000000,
'token' => '<string>',
'interval_count' => 1,
'failure_policy' => 'retry_then_cancel',
'retry_offsets_days' => [
15
],
'currency' => 'BRL',
'metadata' => [
],
'informations' => [
[
'key' => '<string>',
'value' => '<string>'
]
],
'idempotency_key' => '<string>',
'products' => [
[
'name' => '<string>',
'price' => 50000000,
'quantity' => 1,
'tangible' => false,
'sku' => '<string>'
]
],
'payment_method' => 'credit_card',
'trial_end' => '2023-11-07T05:31:56Z'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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.pagou.ai/v2/subscriptions"
payload := strings.NewReader("{\n \"customer_id\": \"<string>\",\n \"amount\": 50000000,\n \"token\": \"<string>\",\n \"interval_count\": 1,\n \"failure_policy\": \"retry_then_cancel\",\n \"retry_offsets_days\": [\n 15\n ],\n \"currency\": \"BRL\",\n \"metadata\": {},\n \"informations\": [\n {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"idempotency_key\": \"<string>\",\n \"products\": [\n {\n \"name\": \"<string>\",\n \"price\": 50000000,\n \"quantity\": 1,\n \"tangible\": false,\n \"sku\": \"<string>\"\n }\n ],\n \"payment_method\": \"credit_card\",\n \"trial_end\": \"2023-11-07T05:31:56Z\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.pagou.ai/v2/subscriptions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"customer_id\": \"<string>\",\n \"amount\": 50000000,\n \"token\": \"<string>\",\n \"interval_count\": 1,\n \"failure_policy\": \"retry_then_cancel\",\n \"retry_offsets_days\": [\n 15\n ],\n \"currency\": \"BRL\",\n \"metadata\": {},\n \"informations\": [\n {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"idempotency_key\": \"<string>\",\n \"products\": [\n {\n \"name\": \"<string>\",\n \"price\": 50000000,\n \"quantity\": 1,\n \"tangible\": false,\n \"sku\": \"<string>\"\n }\n ],\n \"payment_method\": \"credit_card\",\n \"trial_end\": \"2023-11-07T05:31:56Z\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pagou.ai/v2/subscriptions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"customer_id\": \"<string>\",\n \"amount\": 50000000,\n \"token\": \"<string>\",\n \"interval_count\": 1,\n \"failure_policy\": \"retry_then_cancel\",\n \"retry_offsets_days\": [\n 15\n ],\n \"currency\": \"BRL\",\n \"metadata\": {},\n \"informations\": [\n {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"idempotency_key\": \"<string>\",\n \"products\": [\n {\n \"name\": \"<string>\",\n \"price\": 50000000,\n \"quantity\": 1,\n \"tangible\": false,\n \"sku\": \"<string>\"\n }\n ],\n \"payment_method\": \"credit_card\",\n \"trial_end\": \"2023-11-07T05:31:56Z\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"requestId": "0190a2b4-18a7-7de0-9a43-69b7cf261201",
"data": {
"id": "string",
"customerId": "string",
"status": "incomplete",
"paymentMethod": "credit_card",
"billingModel": "merchant_initiated",
"billingDayOfMonth": 1,
"interval": "day",
"intervalCount": 1,
"amount": 0,
"currency": "BRL",
"trialEnd": "2026-07-14T12:00:00.000Z",
"currentPeriodStart": "2026-07-14T12:00:00.000Z",
"currentPeriodEnd": "2026-07-14T12:00:00.000Z",
"cancelAtPeriodEnd": false,
"canceledAt": "2026-07-14T12:00:00.000Z",
"failurePolicy": "immediate_cancel",
"retryOffsetsDays": [
1
],
"cancellationReason": "user_requested",
"customerEmail": "string",
"cardLast4": "string",
"metadata": {},
"informations": [
{
"key": "string",
"value": "string"
}
],
"products": [
{
"name": "string",
"price": 0,
"quantity": 1,
"tangible": false
}
],
"recurringAuthorization": {
"status": "pending"
},
"createdAt": "2026-07-14T12:00:00.000Z",
"updatedAt": "2026-07-14T12:00:00.000Z"
}
}{
"title": "<string>",
"status": 0,
"type": "<string>",
"detail": "<string>",
"instance": "<string>"
}{
"title": "<string>",
"status": 0,
"type": "<string>",
"detail": "<string>",
"instance": "<string>"
}{
"title": "<string>",
"status": 0,
"type": "<string>",
"detail": "<string>",
"instance": "<string>"
}{
"title": "<string>",
"status": 0,
"type": "<string>",
"detail": "<string>",
"instance": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"instance": "<string>"
}Prerequisites
- Create the customer with
POST /v2/customers— the response includes thecustomer_id(UUID) you’ll pass below. - For a card subscription, vault the card through the secure Payment Element flow — this returns a single-use
pgct_payment token. A Pix Automático subscription needs no token.
customer_id returns 404.
Behavior
customer_id is the customer’s public id (UUID) returned by POST /v2/customers.
For a card subscription, token must be a single-use pgct_ token.
For a card subscription, when trial_end is supplied, we may charge a small amount and refund it to ensure the payment method is valid, and the subscription is created with status trialing until the trial expires. Without trial_end, the subscription is created with status active after the first charge succeeds.
With payment_method: "pix_automatic", do not send token. The subscription is created with status incomplete and an authorization QR code for the payer. It becomes active once the payer authorizes and the first debit is paid, or trialing when trial_end is set and the authorization is approved. See Pix Automático Subscriptions.
amount is in cents and is also used to bill every renewal cycle.Authorizations
BearerAuthApiKeyAuthBasicAuth
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
- Option 1
- Option 2
Public customer id (UUID) returned by POST /v2/customers.
Minimum string length:
1Available options:
day, week, month Billing amount in cents (max 100,000,000).
Required range:
0 < x <= 100000000Minimum string length:
6Required range:
1 <= x <= 365Available options:
immediate_cancel, retry_then_cancel Required array length:
1 - 10 elementsRequired range:
1 <= x <= 30Available options:
BRL, MXN, COP, CLP, ARS, PEN, USD, GTQ, CRC, NIO, PYG, UYU, BOB, PHP, RUB, INR, SAR, AED, KWD, QAR, OMR, KHR, SGD, IDR, KRW, THB, MYR, HKD, CNY, EGP, EUR, GBP, BHD, MAD, AUD, CAD, CHF, NZD, PLN, KZT, UZS, JPY, GLC Show child attributes
Show child attributes
Custom key/value metadata to attach to the subscription and echo on its webhooks.
Maximum array length:
50Show child attributes
Show child attributes
Required string length:
1 - 255Maximum array length:
100Show child attributes
Show child attributes
Available options:
credit_card Trial end timestamp (ISO 8601). Must be in the future.
Pattern:
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$Create a Subscription
curl --request POST \
--url https://api.pagou.ai/v2/subscriptions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"customer_id": "<string>",
"amount": 50000000,
"token": "<string>",
"interval_count": 1,
"failure_policy": "retry_then_cancel",
"retry_offsets_days": [
15
],
"currency": "BRL",
"metadata": {},
"informations": [
{
"key": "<string>",
"value": "<string>"
}
],
"idempotency_key": "<string>",
"products": [
{
"name": "<string>",
"price": 50000000,
"quantity": 1,
"tangible": false,
"sku": "<string>"
}
],
"payment_method": "credit_card",
"trial_end": "2023-11-07T05:31:56Z"
}
'import requests
url = "https://api.pagou.ai/v2/subscriptions"
payload = {
"customer_id": "<string>",
"amount": 50000000,
"token": "<string>",
"interval_count": 1,
"failure_policy": "retry_then_cancel",
"retry_offsets_days": [15],
"currency": "BRL",
"metadata": {},
"informations": [
{
"key": "<string>",
"value": "<string>"
}
],
"idempotency_key": "<string>",
"products": [
{
"name": "<string>",
"price": 50000000,
"quantity": 1,
"tangible": False,
"sku": "<string>"
}
],
"payment_method": "credit_card",
"trial_end": "2023-11-07T05:31:56Z"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
customer_id: '<string>',
amount: 50000000,
token: '<string>',
interval_count: 1,
failure_policy: 'retry_then_cancel',
retry_offsets_days: [15],
currency: 'BRL',
metadata: {},
informations: [{key: '<string>', value: '<string>'}],
idempotency_key: '<string>',
products: [
{
name: '<string>',
price: 50000000,
quantity: 1,
tangible: false,
sku: '<string>'
}
],
payment_method: 'credit_card',
trial_end: '2023-11-07T05:31:56Z'
})
};
fetch('https://api.pagou.ai/v2/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.pagou.ai/v2/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([
'customer_id' => '<string>',
'amount' => 50000000,
'token' => '<string>',
'interval_count' => 1,
'failure_policy' => 'retry_then_cancel',
'retry_offsets_days' => [
15
],
'currency' => 'BRL',
'metadata' => [
],
'informations' => [
[
'key' => '<string>',
'value' => '<string>'
]
],
'idempotency_key' => '<string>',
'products' => [
[
'name' => '<string>',
'price' => 50000000,
'quantity' => 1,
'tangible' => false,
'sku' => '<string>'
]
],
'payment_method' => 'credit_card',
'trial_end' => '2023-11-07T05:31:56Z'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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.pagou.ai/v2/subscriptions"
payload := strings.NewReader("{\n \"customer_id\": \"<string>\",\n \"amount\": 50000000,\n \"token\": \"<string>\",\n \"interval_count\": 1,\n \"failure_policy\": \"retry_then_cancel\",\n \"retry_offsets_days\": [\n 15\n ],\n \"currency\": \"BRL\",\n \"metadata\": {},\n \"informations\": [\n {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"idempotency_key\": \"<string>\",\n \"products\": [\n {\n \"name\": \"<string>\",\n \"price\": 50000000,\n \"quantity\": 1,\n \"tangible\": false,\n \"sku\": \"<string>\"\n }\n ],\n \"payment_method\": \"credit_card\",\n \"trial_end\": \"2023-11-07T05:31:56Z\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.pagou.ai/v2/subscriptions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"customer_id\": \"<string>\",\n \"amount\": 50000000,\n \"token\": \"<string>\",\n \"interval_count\": 1,\n \"failure_policy\": \"retry_then_cancel\",\n \"retry_offsets_days\": [\n 15\n ],\n \"currency\": \"BRL\",\n \"metadata\": {},\n \"informations\": [\n {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"idempotency_key\": \"<string>\",\n \"products\": [\n {\n \"name\": \"<string>\",\n \"price\": 50000000,\n \"quantity\": 1,\n \"tangible\": false,\n \"sku\": \"<string>\"\n }\n ],\n \"payment_method\": \"credit_card\",\n \"trial_end\": \"2023-11-07T05:31:56Z\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pagou.ai/v2/subscriptions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"customer_id\": \"<string>\",\n \"amount\": 50000000,\n \"token\": \"<string>\",\n \"interval_count\": 1,\n \"failure_policy\": \"retry_then_cancel\",\n \"retry_offsets_days\": [\n 15\n ],\n \"currency\": \"BRL\",\n \"metadata\": {},\n \"informations\": [\n {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"idempotency_key\": \"<string>\",\n \"products\": [\n {\n \"name\": \"<string>\",\n \"price\": 50000000,\n \"quantity\": 1,\n \"tangible\": false,\n \"sku\": \"<string>\"\n }\n ],\n \"payment_method\": \"credit_card\",\n \"trial_end\": \"2023-11-07T05:31:56Z\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"requestId": "0190a2b4-18a7-7de0-9a43-69b7cf261201",
"data": {
"id": "string",
"customerId": "string",
"status": "incomplete",
"paymentMethod": "credit_card",
"billingModel": "merchant_initiated",
"billingDayOfMonth": 1,
"interval": "day",
"intervalCount": 1,
"amount": 0,
"currency": "BRL",
"trialEnd": "2026-07-14T12:00:00.000Z",
"currentPeriodStart": "2026-07-14T12:00:00.000Z",
"currentPeriodEnd": "2026-07-14T12:00:00.000Z",
"cancelAtPeriodEnd": false,
"canceledAt": "2026-07-14T12:00:00.000Z",
"failurePolicy": "immediate_cancel",
"retryOffsetsDays": [
1
],
"cancellationReason": "user_requested",
"customerEmail": "string",
"cardLast4": "string",
"metadata": {},
"informations": [
{
"key": "string",
"value": "string"
}
],
"products": [
{
"name": "string",
"price": 0,
"quantity": 1,
"tangible": false
}
],
"recurringAuthorization": {
"status": "pending"
},
"createdAt": "2026-07-14T12:00:00.000Z",
"updatedAt": "2026-07-14T12:00:00.000Z"
}
}{
"title": "<string>",
"status": 0,
"type": "<string>",
"detail": "<string>",
"instance": "<string>"
}{
"title": "<string>",
"status": 0,
"type": "<string>",
"detail": "<string>",
"instance": "<string>"
}{
"title": "<string>",
"status": 0,
"type": "<string>",
"detail": "<string>",
"instance": "<string>"
}{
"title": "<string>",
"status": 0,
"type": "<string>",
"detail": "<string>",
"instance": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"instance": "<string>"
}