> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> O objeto Customer Portal Session

Uma `customer_portal.session` é uma autorização temporária para um customer
abrir o portal hospedado. Ela não cria login de cliente e não substitui os
objetos canônicos `customer`, `subscription` e `payment_method`; ações feitas
no portal atualizam esses recursos e emitem os webhooks correspondentes.

## Objeto

| Campo           | Tipo             | Observação                                                                                                                                                     |
| --------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`            | `string`         | ID da sessão (`cps_*`)                                                                                                                                         |
| `object`        | `string`         | Sempre `"customer_portal.session"`                                                                                                                             |
| `configuration` | `string \| null` | Reservado para configurações de portal futuras. No V1 retorna `null`.                                                                                          |
| `created_at`    | `string`         | ISO 8601                                                                                                                                                       |
| `customer`      | `string`         | Customer que abrirá o portal                                                                                                                                   |
| `expires_at`    | `string`         | ISO 8601. Antes do primeiro acesso, a URL deve ser aberta antes desse horário. Depois do primeiro acesso, passa a refletir a expiração da sessão hosted curta. |
| `flow`          | `object \| null` | Fluxo inicial da hosted page. `null` abre a home do portal.                                                                                                    |
| `livemode`      | `boolean`        | `true` em produção; `false` em ambiente de teste                                                                                                               |
| `locale`        | `string \| null` | Locale sugerido para a hosted page                                                                                                                             |
| `metadata`      | `object`         | Metadata da sessão                                                                                                                                             |
| `return_url`    | `string \| null` | URL de volta para seu app                                                                                                                                      |
| `status`        | `string`         | `created`, `opened`, `completed` ou `expired`                                                                                                                  |
| `updated_at`    | `string \| null` | ISO 8601                                                                                                                                                       |
| `url`           | `string`         | URL hospedada que você redireciona o cliente para abrir                                                                                                        |

<ResponseExample>
  ```json 200 theme={}
  {
    "id": "cps_123",
    "object": "customer_portal.session",
    "configuration": null,
    "created_at": "2026-05-27T12:00:00Z",
    "customer": "cus_123",
    "expires_at": "2026-05-27T13:00:00Z",
    "flow": {
      "after_completion": {
        "redirect": {
          "return_url": "https://example.com/account/subscription-canceled"
        },
        "type": "redirect"
      },
      "subscription_cancel": {
        "subscription": "sub_123"
      },
      "type": "subscription_cancel"
    },
    "livemode": true,
    "locale": "pt-BR",
    "metadata": {},
    "return_url": "https://example.com/account",
    "status": "created",
    "updated_at": null,
    "url": "https://billing.chargefy.io/portal/session/cps_123?authorization_code=..."
  }
  ```
</ResponseExample>

## Flows

`flow` é opcional. Quando enviado, a hosted page abre direto no fluxo indicado.

| Tipo                    | Uso                                                                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `customer_update`       | Cliente atualiza nome, email, telefone ou dados de cobrança.                                                             |
| `payment_method_update` | Cliente troca o cartão salvo. Opcionalmente recebe `subscription` e/ou `invoice` para atualizar o padrão desses objetos. |
| `subscription_cancel`   | Cliente agenda cancelamento no fim do período. Exige uma `subscription`.                                                 |

## Expiração

O link inicial contém um `authorization_code` de uso único. Esse link pode ser
aberto pela primeira vez em até 1 hora depois da criação da sessão. Quando o
cliente abre o link com sucesso, o código é consumido e não pode ser reutilizado.

Depois disso, a hosted page usa uma sessão curta no navegador por até 1 hora. Se
o cliente precisar acessar o portal depois da expiração, crie uma nova
`customer_portal.session`.

## Webhooks

O portal não emite evento próprio no V1. Acompanhe os objetos alterados:

| Ação no portal                        | Webhook                                                                                                       |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Atualizar dados do cliente            | `customer.updated`                                                                                            |
| Atualizar cartão                      | `payment.method.created`, `payment.method.attached`, `subscription.updated` quando vinculado a uma assinatura |
| Cancelar assinatura no fim do período | `subscription.updated`                                                                                        |

## Referências

* [Criar customer portal session](/api-reference/customer-portal-sessions/create)