curl --request POST \
--url https://api.abacatepay.com/v2/subscriptions/create \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"items": [
{
"id": "prod-1234",
"quantity": 1
}
],
"customerId": "cust_abc123xyz",
"methods": [
"CARD"
]
}
'import requests
url = "https://api.abacatepay.com/v2/subscriptions/create"
payload = {
"items": [
{
"id": "prod-1234",
"quantity": 1
}
],
"customerId": "cust_abc123xyz",
"methods": ["CARD"]
}
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({
items: [{id: 'prod-1234', quantity: 1}],
customerId: 'cust_abc123xyz',
methods: ['CARD']
})
};
fetch('https://api.abacatepay.com/v2/subscriptions/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.abacatepay.com/v2/subscriptions/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([
'items' => [
[
'id' => 'prod-1234',
'quantity' => 1
]
],
'customerId' => 'cust_abc123xyz',
'methods' => [
'CARD'
]
]),
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.abacatepay.com/v2/subscriptions/create"
payload := strings.NewReader("{\n \"items\": [\n {\n \"id\": \"prod-1234\",\n \"quantity\": 1\n }\n ],\n \"customerId\": \"cust_abc123xyz\",\n \"methods\": [\n \"CARD\"\n ]\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.abacatepay.com/v2/subscriptions/create")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"items\": [\n {\n \"id\": \"prod-1234\",\n \"quantity\": 1\n }\n ],\n \"customerId\": \"cust_abc123xyz\",\n \"methods\": [\n \"CARD\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.abacatepay.com/v2/subscriptions/create")
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 \"items\": [\n {\n \"id\": \"prod-1234\",\n \"quantity\": 1\n }\n ],\n \"customerId\": \"cust_abc123xyz\",\n \"methods\": [\n \"CARD\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "bill_abc123xyz",
"externalId": "pedido-123",
"url": "https://app.abacatepay.com/pay/bill_abc123xyz",
"amount": 10000,
"paidAmount": null,
"items": [
{
"id": "prod_456",
"quantity": 2
}
],
"status": "PENDING",
"coupons": [],
"devMode": false,
"customerId": null,
"returnUrl": null,
"completionUrl": null,
"receiptUrl": null,
"upSellProductId": "prod_bump456xyz",
"installmentsCount": 3,
"dueDate": "2026-08-15",
"interest": {
"value": 100
},
"fine": {
"value": 200,
"type": "PERCENTAGE"
},
"metadata": {},
"createdAt": "2024-11-04T18:38:28.573Z",
"updatedAt": "2024-11-04T18:38:28.573Z"
},
"error": null,
"success": true
}{
"error": "Token de autenticação inválido ou ausente."
}Criar Checkout de assinatura
Cria um Checkout de assinatura — uma página de pagamento igual ao Checkout comum, mas para cobrança recorrente.
Aceita os mesmos parâmetros do Checkout (returnUrl, completionUrl, customerId, externalId, metadata, coupons, methods). O Checkout de assinatura aceita apenas um produto; o ciclo (frequência) já deve estar definido no produto ao criá-lo na loja — não é enviado no checkout.
curl --request POST \
--url https://api.abacatepay.com/v2/subscriptions/create \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"items": [
{
"id": "prod-1234",
"quantity": 1
}
],
"customerId": "cust_abc123xyz",
"methods": [
"CARD"
]
}
'import requests
url = "https://api.abacatepay.com/v2/subscriptions/create"
payload = {
"items": [
{
"id": "prod-1234",
"quantity": 1
}
],
"customerId": "cust_abc123xyz",
"methods": ["CARD"]
}
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({
items: [{id: 'prod-1234', quantity: 1}],
customerId: 'cust_abc123xyz',
methods: ['CARD']
})
};
fetch('https://api.abacatepay.com/v2/subscriptions/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.abacatepay.com/v2/subscriptions/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([
'items' => [
[
'id' => 'prod-1234',
'quantity' => 1
]
],
'customerId' => 'cust_abc123xyz',
'methods' => [
'CARD'
]
]),
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.abacatepay.com/v2/subscriptions/create"
payload := strings.NewReader("{\n \"items\": [\n {\n \"id\": \"prod-1234\",\n \"quantity\": 1\n }\n ],\n \"customerId\": \"cust_abc123xyz\",\n \"methods\": [\n \"CARD\"\n ]\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.abacatepay.com/v2/subscriptions/create")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"items\": [\n {\n \"id\": \"prod-1234\",\n \"quantity\": 1\n }\n ],\n \"customerId\": \"cust_abc123xyz\",\n \"methods\": [\n \"CARD\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.abacatepay.com/v2/subscriptions/create")
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 \"items\": [\n {\n \"id\": \"prod-1234\",\n \"quantity\": 1\n }\n ],\n \"customerId\": \"cust_abc123xyz\",\n \"methods\": [\n \"CARD\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "bill_abc123xyz",
"externalId": "pedido-123",
"url": "https://app.abacatepay.com/pay/bill_abc123xyz",
"amount": 10000,
"paidAmount": null,
"items": [
{
"id": "prod_456",
"quantity": 2
}
],
"status": "PENDING",
"coupons": [],
"devMode": false,
"customerId": null,
"returnUrl": null,
"completionUrl": null,
"receiptUrl": null,
"upSellProductId": "prod_bump456xyz",
"installmentsCount": 3,
"dueDate": "2026-08-15",
"interest": {
"value": 100
},
"fine": {
"value": 200,
"type": "PERCENTAGE"
},
"metadata": {},
"createdAt": "2024-11-04T18:38:28.573Z",
"updatedAt": "2024-11-04T18:38:28.573Z"
},
"error": null,
"success": true
}{
"error": "Token de autenticação inválido ou ausente."
}Pré-requisito
items deve ter um cycle definido (WEEKLY, MONTHLY, SEMIANNUALLY ou ANNUALLY). Produtos avulsos retornam erro.{
"items": [
{ "id": "prod_abc123xyz", "quantity": 1 }
],
"customerId": "cust_abc123xyz",
"externalId": "subs-123",
"completionUrl": "https://seusite.com/sucesso",
"methods": ["CARD"],
"retryPolicy": {
"maxRetry": 3,
"retryEvery": 2
}
}
data.url para concluir o primeiro pagamento e ativar a assinatura.CARD.trialDays configurado, o checkout cobra R$ 0,00 — apenas tokeniza o cartão. A primeira cobrança pelo valor integral ocorre automaticamente ao final do trial. Consulte a referência de assinaturas para mais detalhes.Authorizations
Todas as requisições devem incluir sua chave de API no header Authorization usando o formato Bearer <abacatepay-api-key>. Sem esse header a requisição será rejeitada.
Saiba mais sobre como criar e usar chaves de API na documentação de autenticação.
Body
Mesmos parâmetros do Checkout, com items contendo exatamente um item (id e quantity).
O produto referenciado deve ter sido criado com ciclo de assinatura (frequency) na loja.
Lista com exatamente um item. O produto deve ter sido criado com ciclo de assinatura (frequency). O valor total é calculado a partir do produto.
1 elementShow child attributes
Show child attributes
Métodos de pagamento disponíveis. Assinaturas suportam apenas CARD. Padrão ["CARD"].
1PIX, CARD URL para onde o cliente será redirecionado ao clicar em "Voltar" no checkout.
URL para onde o cliente será redirecionado após o pagamento ser concluído.
ID de um cliente já cadastrado na sua loja. Se informado, o checkout será pré-preenchido com os dados deste cliente.
Lista de cupons que podem ser utilizados nesta cobrança.
50ID da assinatura no seu sistema, caso queira manter uma referência própria.
Metadados adicionais. Campo livre para a sua aplicação.
Configuração do pagamento por cartão. Só tem efeito quando methods inclui CARD.
Show child attributes
Show child attributes
ID de um produto avulso (sem cycle) a ser ofertado como upsell após a conclusão do pagamento.
O produto deve estar com status: ACTIVE e não pode ter cycle — apenas produtos de pagamento único são aceitos.
Exemplo: "prod_bump456xyz"
Data de vencimento do boleto no formato YYYY-MM-DD (ex: "2026-08-15"). Opcional. Só é válido quando methods inclui BOLETO; ignorado nos demais métodos.
Se omitido, o vencimento padrão é de 3 dias úteis. Não pode ser data no passado. Máximo de 365 dias no futuro.
"2026-08-15"
Juros por atraso, aplicados apenas quando methods inclui BOLETO. Ignorado para PIX/CARD.
Show child attributes
Show child attributes
Multa por atraso, aplicada apenas quando methods inclui BOLETO. Ignorado para PIX/CARD.
Show child attributes
Show child attributes
Política de novas tentativas quando uma cobrança da assinatura falha. Se omitida, a assinatura usa 3 tentativas com 1 dia de intervalo.
Show child attributes
Show child attributes
Was this page helpful?