Checkouts

Um checkout é a configuração visual da página de compra. Não é um endpoint de processamento de pagamento.

O objeto checkout

{
  "object": "checkout",
  "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "name": "Checkout padrão",
  "is_default": true,
  "archived": false,
  "banner_url": null,
  "settings_json": {
    "checkout_logo_enabled": true,
    "checkout_logo_url": null,
    "checkout_banner_enabled": false,
    "checkout_banner_url": null,
    "checkout_titulo": "Finalize sua compra",
    "checkout_subtitulo": null,
    "checkout_descricao": null,
    "checkout_garantia": "7 dias",
    "checkout_selos_enabled": true,
    "checkout_cupom_enabled": false,
    "checkout_fundo_tipo": "pitra",
    "checkout_fundo_cor": null,
    "checkout_fundo_imagem": null
  },
  "created_at": "2026-07-30T12:00:00.000Z",
  "updated_at": "2026-07-30T12:00:00.000Z"
}

Checkout padrão: cada loja tem um checkout com is_default: true. Ele é usado por produtos sem checkout_id e serve de base visual para novos checkouts. O checkout padrão não pode ser arquivado.

Listar checkouts

GET/api/public/v1/checkoutsscope checkouts:read

Query	Tipo	Descrição
`limit`	integer	1–100, padrão 20.
`starting_after`	string	Cursor da página anterior.

curl "https://pitra.com.br/api/public/v1/checkouts?limit=20" \
  -H "Authorization: Bearer sk_live_..."

Resposta 200: envelope de lista com objetos checkout.

Criar checkout

POST/api/public/v1/checkoutsscope checkouts:write

Campo	Tipo	Obrigatório	Regras
`name`	string	Sim	1–120 caracteres.
`product_id`	uuid	Não	Vincula o produto ao novo checkout.
`settings_json`	object	Não	Somente as chaves visuais listadas acima.

Chaves desconhecidas em settings_json são rejeitadas. Campos não informados herdam a configuração do checkout padrão da loja. Aceita Idempotency-Key.

curl -X POST https://pitra.com.br/api/public/v1/checkouts \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Black Friday","settings_json":{"checkout_titulo":"Oferta especial"}}'

Resposta 201: o objeto checkout.

Consultar checkout

GET/api/public/v1/checkouts/{id}scope checkouts:read

curl https://pitra.com.br/api/public/v1/checkouts/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer sk_live_..."

Resposta 200. Checkout de outra loja devolve 404 not_found.

Arquivar checkout

POST/api/public/v1/checkouts/{id}/archivescope checkouts:write

Marca o checkout como arquivado (archived: true) e desvincula os produtos que o utilizavam — eles passam a usar o checkout padrão. O checkout padrão não pode ser arquivado (400 invalid_request).

curl -X POST https://pitra.com.br/api/public/v1/checkouts/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d/archive \
  -H "Authorization: Bearer sk_live_..."

Resposta 200: o checkout arquivado.