> ## Documentation Index
> Fetch the complete documentation index at: https://scaleup-c34c4386.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /api/v1/sdk/organizations/:orgId/checkouts

> Cria uma sessão de checkout garantindo que os produtos pertencem à sub-organização do path; autenticação com JWT da organização pai.

Cria uma sessão de checkout com o **mesmo corpo** que `POST /v1/checkouts`, com uma regra extra:

* Todo produto envolvido na criação (`product_id`, ou produto derivado de `product_price_id`, ou cada ID em `products[]`) deve ter `organization_id` **igual** a `:orgId`.
* Se você tentar usar um produto de **outra** sub-organização ou da org pai, a API responde **`422`** com mensagem clara (não expõe dados do produto alheio).

Isso evita ambiguidade em marketplaces com muitos vendedores: a URL deixa explícito **para qual filho** aquela sessão está sendo aberta.

## Autenticação

**JWT da organização pai**, com vínculo direto para `:orgId` em `organization_relationships`.

## Escopos

Pelo menos um de: `web:write` ou `checkouts:write`.

## Parâmetros de path

**orgId** `string` *required*

UUID da sub-organização dona do catálogo. Os produtos do corpo devem pertencer a essa org.

## Corpo

Igual a [POST /v1/checkouts](https://scaleup-c34c4386.mintlify.site/api-reference/checkouts/create.md) (campos em `snake_case` no HTTP). É obrigatório fornecer **um** entre:

* `product_id`
* `product_price_id` (produto inferido do preço)
* `products` (lista de IDs de produto; o fluxo interno usa o primeiro como principal, como no endpoint principal)

Campos frequentes:

**product\_id** `string`

ID do produto **da sub-org** `:orgId`.

**product\_price\_id** `string`

ID de preço; o produto associado deve ser da sub-org `:orgId`.

**customer\_email** `string`

E-mail pré-preenchido no checkout.

**customer\_name** `string`

Nome do comprador.

**customer\_tax\_id** `string`

CPF/CNPJ quando aplicável.

**amount** `integer`

Valor em **centavos** quando usar preço customizado (mesmas regras do endpoint principal).

**success\_url** `string`

URL de retorno após sucesso.

**metadata** `object`

Metadados arbitrários gravados na sessão.

## Resposta

`201 Created` com o objeto checkout (inclui `client_secret`, `url` para abrir o fluxo, etc.), no mesmo formato que `POST /v1/checkouts`.

## Erros

| HTTP | Motivo |
| - | - |
| `401` / `403` | Token ou escopo; ou pai não é pai de `:orgId` |
| `404` | Produto/preço inexistente |
| `422` | Produto não pertence a `:orgId`, ou validação de preço |
| `500` | Erro interno |

## Exemplos

### Checkout simples com produto e e-mail

```bash cURL theme={null}
curl -s -X POST "${API_BASE:-https://api.chargefy.io/api}/v1/sdk/organizations/${CHILD_ORG_ID}/checkouts" \
  -H "Authorization: Bearer ${PARENT_JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "'"${CHILD_PRODUCT_ID}"'",
    "customer_email": "comprador@loja-filha.com",
    "customer_name": "Maria Silva",
    "success_url": "https://marketplace.exemplo.com/obrigado"
  }' | jq .
```

```typescript SDK theme={null}
import { Chargefy } from '@chargefy/sdk'

const chargefy = new Chargefy({ accessToken: process.env.PARENT_JWT! })

const created = await chargefy.subOrganizations.createCheckout(process.env.CHILD_ORG_ID!, {
  productId: process.env.CHILD_PRODUCT_ID!,
  customerEmail: 'comprador@loja-filha.com',
  customerName: 'Maria Silva',
  successUrl: 'https://marketplace.exemplo.com/obrigado',
})

if (!created.ok) {
  console.error(created.error)
  process.exit(1)
}

console.log('Abrir checkout:', created.value.url)
console.log('client_secret (guardar só no backend):', created.value.clientSecret)
```

### Usando `product_price_id` (mesmo filho, preço explícito)

```bash cURL theme={null}
curl -s -X POST "${API_BASE:-https://api.chargefy.io/api}/v1/sdk/organizations/${CHILD_ORG_ID}/checkouts" \
  -H "Authorization: Bearer ${PARENT_JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "product_price_id": "'"${CHILD_PRICE_ID}"'",
    "customer_email": "b2b@cliente.com",
    "require_billing_address": true
  }' | jq .
```

```typescript SDK theme={null}
const byPrice = await chargefy.subOrganizations.createCheckout(process.env.CHILD_ORG_ID!, {
  productPriceId: process.env.CHILD_PRICE_ID!,
  customerEmail: 'b2b@cliente.com',
  requireBillingAddress: true,
})
if (byPrice.ok) console.log(byPrice.value.id, byPrice.value.status)
```

### Erro esperado: produto de outra org no mesmo marketplace

Se `OTHER_PRODUCT_ID` for de **outro** filho (ou da pai), o path ainda aponta para `CHILD_ORG_ID`:

```bash theme={null}
curl -s -o /dev/stderr -w "%{http_code}" -X POST "${API_BASE}/v1/sdk/organizations/${CHILD_ORG_ID}/checkouts" \
  -H "Authorization: Bearer ${PARENT_JWT}" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "'"${OTHER_PRODUCT_ID}"'"}'
# Esperado: HTTP 422 — corpo com mensagem sobre produto e sub-organização da URL
```

### Variáveis (bash)

```bash theme={null}
export API_BASE="https://api.chargefy.io/api"
export PARENT_JWT="<supabase_jwt>..."
export CHILD_ORG_ID="uuid_sub_org"
export CHILD_PRODUCT_ID="uuid_produto"
export CHILD_PRICE_ID="uuid_preco"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.