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

# Update billing policy

> Choose consolidated or direct media billing while a seller policy is unlocked

`PUT /api/v2/buyer/storefronts/{storefrontId}/billing-policy`

Sets the buyer account's billing preference for one selected seller. The caller
must have the `ADMIN` or `SUPER_ADMIN` account role.

<Note title="Seller-sponsored accounts">
  If your account joined through a seller-sponsored link, the seller fixed the
  billing path when creating that link. You can see the resulting policy and
  readiness state, but you cannot change the policy or accept direct billing.
  The seller must disable the link and create another one to choose a different
  path for future sponsored buyers.
</Note>

Use `agent` for consolidated billing on your Apostra invoice and `operator`
for direct billing by the seller or connected platform. The seller must support
the requested party. Operator-auth platforms and direct-only sellers expose
only `operator` and should be shown as read-only when there is no choice.

## Lock boundary

The preference stays editable until Apostra dispatches the first real
activation for an eligible advertiser. Direct-billing acceptance by itself does
not lock the policy when no eligible advertiser exists. After dispatch begins,
the endpoint fails closed with `409 CONFLICT`; changing the policy then requires
a future billing migration process.

## Request

```bash theme={null}
curl -X PUT \
  "https://api.apostra.com/api/v2/buyer/storefronts/42/billing-policy" \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestedParty": "agent"
  }'
```

## Parameters

| Field            | In   | Type    | Required | Notes                                                             |
| ---------------- | ---- | ------- | -------- | ----------------------------------------------------------------- |
| `storefrontId`   | path | integer | Yes      | Exact selected, buyer-visible storefront ID                       |
| `requestedParty` | body | enum    | Yes      | `agent` for your Apostra invoice or `operator` for direct billing |

## Response

```json theme={null}
{
  "requestedParty": "agent"
}
```

## Errors

* `400 VALIDATION_ERROR` — the ID or billing party is invalid, or the seller
  does not support the requested policy.
* `401 UNAUTHORIZED` — the bearer token is missing or invalid.
* `403 FORBIDDEN` — the caller is not an account administrator, or the account
  is seller-sponsored and its billing path is controlled by the seller.
* `409 CONFLICT` — the seller is not selected, the policy is already locked,
  or it changed concurrently.

See [Errors](/v2/reference/errors) for the full error contract.

## Related

<CardGroup cols={2}>
  <Card title="Approve direct billing" href="/v2/buyer/storefronts/tasks/accept-direct-billing" icon="file-signature">
    Record the account-wide acceptance required by a direct policy
  </Card>

  <Card title="Update selection override" href="/v2/buyer/storefronts/tasks/update-selection-override" icon="toggle-on">
    Select the seller before changing its billing policy
  </Card>
</CardGroup>