Atualizar item
curl --request PATCH \
--url https://api.upag.io/v1/subscriptions/{subscriptionId}/items/{itemId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"price": {},
"quantity": 123,
"applyAt": "<string>"
}
'const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({price: {}, quantity: 123, applyAt: '<string>'})
};
fetch('https://api.upag.io/v1/subscriptions/{subscriptionId}/items/{itemId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://api.upag.io/v1/subscriptions/{subscriptionId}/items/{itemId}';
const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({price: {}, quantity: 123, applyAt: '<string>'})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));Assinaturas
Atualizar item
Troca o preço ou a quantidade de um item, agora ou na próxima renovação
PATCH
https://api.upag.io
/
v1
/
subscriptions
/
{subscriptionId}
/
items
/
{itemId}
Atualizar item
curl --request PATCH \
--url https://api.upag.io/v1/subscriptions/{subscriptionId}/items/{itemId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"price": {},
"quantity": 123,
"applyAt": "<string>"
}
'const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({price: {}, quantity: 123, applyAt: '<string>'})
};
fetch('https://api.upag.io/v1/subscriptions/{subscriptionId}/items/{itemId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://api.upag.io/v1/subscriptions/{subscriptionId}/items/{itemId}';
const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({price: {}, quantity: 123, applyAt: '<string>'})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));Altera o preço e/ou a quantidade de um item da assinatura. Com
Envie pelo menos
applyAt: "now" (padrão) a mudança vale na hora; com applyAt: "period_end" ela vira uma mudança agendada, aplicada na próxima renovação.
A alteração não gera fatura nem cobrança proporcional: o novo valor passa a valer na próxima renovação.
Permissão: subscription.write. Apenas chave secreta (sk_…).
Os exemplos usam o sandbox (
https://api.upag.dev/v1). Em produção use https://api.upag.io/v1 com sk_live_….Endpoint
curl -X PATCH https://api.upag.dev/v1/subscriptions/9a3c6e1f-0d58-4b72-a4e9-7c2f8b5d1e36/items/c6d2f9a4-7e18-4b35-9a60-3f1e8d5b2c07 \
-H "Authorization: Bearer sk_test_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"quantity": 3,
"applyAt": "period_end"
}'
import { Upag } from 'upag';
const upag = new Upag('sk_test_your_api_key');
const result = await upag.subscriptions.updateItem(
'9a3c6e1f-0d58-4b72-a4e9-7c2f8b5d1e36',
'c6d2f9a4-7e18-4b35-9a60-3f1e8d5b2c07',
{ quantity: 3, applyAt: 'period_end' },
);
Parâmetros
string (uuid)
required
ID da assinatura.
string (uuid)
required
ID do item (
items[].id da assinatura).string (uuid)
UUID do novo preço:
recurring, com o mesmo interval, intervalCount e moeda da assinatura.integer
Nova quantidade, mínimo 1.
string
default:"now"
now ou period_end.price ou quantity.
Resposta
200 OK. Com now, é o item já atualizado; com period_end, é a mudança agendada.
Response (applyAt: now)
{
"id": "c6d2f9a4-7e18-4b35-9a60-3f1e8d5b2c07",
"product": "7d2b5e90-1c34-4a68-b9f7-0e3a6c8d1f25",
"price": "3a7e9c14-6b2d-4f85-9e10-5c8d2a7b4f61",
"name": "Plano mensal",
"amount": 9900,
"quantity": 3,
"totalAmount": 29700,
"createdAt": "2026-10-07T19:00:00.000Z",
"updatedAt": "2026-10-12T14:20:00.000Z"
}
Response (applyAt: period_end)
{
"id": "2b7d4f91-8e06-4c53-a1d8-5f3c9e0a6b72",
"subscription": "9a3c6e1f-0d58-4b72-a4e9-7c2f8b5d1e36",
"operation": "update",
"item": "c6d2f9a4-7e18-4b35-9a60-3f1e8d5b2c07",
"price": null,
"quantity": 3,
"createdAt": "2026-10-12T14:20:00.000Z"
}
Erros
| Status | Código | Quando |
|---|---|---|
404 | SUBSCRIPTION_NOT_FOUND | A assinatura não existe ou é de outra conta |
404 | SUBSCRIPTION_ITEM_NOT_FOUND | O item não pertence à assinatura |
404 | PRICE_NOT_FOUND / PRODUCT_NOT_FOUND | O novo preço, ou o produto dele, não existe na conta |
400 | SUBSCRIPTION_NOT_EDITABLE | A assinatura está canceled ou void |
400 | SUBSCRIPTION_PRICE_MISMATCH | Intervalo ou moeda do novo preço diferentes da assinatura |
422 | VALIDATION_FAILED | Nem price nem quantity enviados |