Skip to main content
POST
/
subscriptions
/
create
curl -X POST 'https://api.goatpay.com.br/v1/subscriptions/create' \
  -H 'X-API-Key: gp_live_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{ "salesCustomerId": "clx_customer", "billingType": "BOLETO", "value": 99.9, "cycle": "MONTHLY", "nextDueDate": "2026-08-01", "description": "Plano Premium" }'

{
  "success": true,
  "message": "Assinatura criada",
  "data": {
    "id": "clx_sub",
    "providerSubscriptionId": "sub_ext_xyz",
    "status": "ACTIVE",
    "cycle": "MONTHLY",
    "billingType": "BOLETO",
    "value": 99.9,
    "description": "Plano Premium",
    "nextDueDate": "2026-08-01T00:00:00.000Z",
    "createdAt": "2026-07-01T12:00:00.000Z",
    "customer": {
      "id": "clx_customer",
      "name": "Maria Silva",
      "taxId": "12345678909"
    },
    "plan": {
      "id": "clx_plan",
      "name": "Plano Premium"
    }
  },
  "requestId": "req_abc123"
}

curl -X POST 'https://api.goatpay.com.br/v1/subscriptions/create' \
  -H 'X-API-Key: gp_live_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{ "salesCustomerId": "clx_customer", "billingType": "BOLETO", "value": 99.9, "cycle": "MONTHLY", "nextDueDate": "2026-08-01", "description": "Plano Premium" }'

{
  "success": true,
  "message": "Assinatura criada",
  "data": {
    "id": "clx_sub",
    "providerSubscriptionId": "sub_ext_xyz",
    "status": "ACTIVE",
    "cycle": "MONTHLY",
    "billingType": "BOLETO",
    "value": 99.9,
    "description": "Plano Premium",
    "nextDueDate": "2026-08-01T00:00:00.000Z",
    "createdAt": "2026-07-01T12:00:00.000Z",
    "customer": {
      "id": "clx_customer",
      "name": "Maria Silva",
      "taxId": "12345678909"
    },
    "plan": {
      "id": "clx_plan",
      "name": "Plano Premium"
    }
  },
  "requestId": "req_abc123"
}

​
Corpo da requisição

​
salesCustomerId
string
required
ID do cliente cadastrado (POST /customers/create).
​
billingType
string
BOLETO, CREDIT_CARD, DEBIT_CARD ou VOUCHER.
​
value
number
Valor de cada ciclo em reais.
​
cycle
string
WEEKLY, MONTHLY, QUARTERLY, SEMIANNUALLY, YEARLY, etc.
​
nextDueDate
string
required
Primeiro vencimento (YYYY-MM-DD).
​
planId
string
ID do plano cadastrado.
​
description
string
Descrição da assinatura.
​
creditCardToken
string
Token do cartão quando billingType é CREDIT_CARD.
Recorrência com ciclo fixo. Para pagamento único use POST /billings/create. Confirme renovações via webhooks.

Authorizations

​
X-API-Key
string
header
required

Chave gp_live_... criada em Integrações → Chaves de API no dashboard.

Body

application/json
​
method
enum<string>
required
Available options:
BOLETO,
CARD_CREDIT,
PIX
​
amount
number
required
Required range: x >= 0.01
​
cycle
enum<string>
required
Available options:
WEEKLY,
BIWEEKLY,
MONTHLY,
BIMONTHLY,
QUARTERLY,
SEMIANNUALLY,
YEARLY
​
nextDueDate
string<date>
required
​
customer
object
required
​
description
string
​
cardToken
string

Token de cartão (cobranças seguintes)

​
creditCard
object
​
creditCardHolderInfo
object
​
remoteIp
string

IP do comprador (obrigatório em CARD_CREDIT)

​
authorizeOnly
boolean

Response

Operação concluída.

​
success
boolean
required
Example:

true

​
message
string
required
Example:

"Operação concluída com sucesso"

​
data
object
required
​
requestId
string