Update billing info

PUT /api/v2/billing/info Updates the billing (payer) info Apostra invoices you with. Admin-only. Send at least one field; omitted fields are left unchanged. The response returns the full updated record. At minimum, Apostra needs a payer name (contactName) and a payer address (address, city, countryAlpha2) to issue an invoice — set both before your first billing cycle. Also available in the UI under Settings → Plan & Billing → Payment & invoices.

Request

curl

curl -X PUT https://api.apostra.com/api/v2/billing/info \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactName": "Dana Whitfield",
    "email": ["ap@bluepeakbrands.example"],
    "ccEmails": ["finance@bluepeakbrands.example"],
    "phone": "+1 415 555 0182",
    "address": "225 Mission St",
    "address2": "Floor 8",
    "city": "San Francisco",
    "region": "CA",
    "postalCode": "94105",
    "countryAlpha2": "US",
    "taxId": "83-1234567"
  }'

Parameters

Field	Type	Required	Notes
`contactName`	string	No*	Billing contact / payer name (1–255). *Needed before an invoice can be issued
`email`	array	No	Up to 10 email addresses invoices are sent to
`ccEmails`	array	No	Up to 10 email addresses CC’d on invoices
`phone`	string	No	Billing phone number (max 64)
`address`	string	No*	Billing street address, line 1 (max 255). *Needed before an invoice can be issued
`address2`	string	No	Billing street address, line 2 (max 255)
`city`	string	No	Billing city (max 128)
`region`	string	No	State/province/region (max 128)
`postalCode`	string	No	Postal/ZIP code (max 32)
`countryAlpha2`	string	No	ISO 3166-1 alpha-2, uppercase (e.g. `US`)
`taxId`	string	No	Tax/VAT identifier shown on invoices (max 64)
`paymentTerms`	string	No	Payment terms to ask sellers for: `net_15`, `net_30`, `net_45`, `net_60`, or `net_90`. Unlike the other fields, `null` is refused: the choice can be changed but not cleared, so to use the default terms, send them. Send it on its own, without other fields. See Payment terms

Response

{
  "billingInfo": {
    "contactName": "Dana Whitfield",
    "email": ["ap@bluepeakbrands.example"],
    "ccEmails": ["finance@bluepeakbrands.example"],
    "phone": "+1 415 555 0182",
    "address": "225 Mission St",
    "address2": "Floor 8",
    "city": "San Francisco",
    "region": "CA",
    "postalCode": "94105",
    "countryAlpha2": "US",
    "taxId": "83-1234567"
  }
}

The response mirrors Get billing info after the update.

Set payment terms

Payment terms are writable through this endpoint. An organization admin sets the terms Apostra asks sellers for by sending paymentTerms on its own. No approval step follows: the choice is recorded immediately. The change is audited (Updated buyer payment terms, with the before and after values), and the write and its audit row commit together.

curl

curl -X PUT https://api.apostra.com/api/v2/billing/info \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"paymentTerms": "net_45"}'

The response is the full billing record with the recorded choice:

{
  "billingInfo": {
    "contactName": "Dana Whitfield",
    "email": ["ap@bluepeakbrands.example"],
    "ccEmails": ["finance@bluepeakbrands.example"],
    "phone": "+1 415 555 0182",
    "address": "225 Mission St",
    "address2": "Floor 8",
    "city": "San Francisco",
    "region": "CA",
    "postalCode": "94105",
    "countryAlpha2": "US",
    "taxId": "83-1234567",
    "paymentTerms": "net_45",
    "paymentTermsChosen": true
  }
}

Allowed values: net_15, net_30, net_45, net_60, net_90. prepay is not an organization-level value. net_60 applies until you choose.
Availability: the write is available only when requesting payment terms is enabled for your organization. Otherwise it is refused with 400 VALIDATION_ERROR and field: "paymentTerms".
Scope: the choice belongs to the organization and applies to every advertiser in it. It applies to accounts Apostra opens afterwards.

Organization terms and seller billing mode

How a seller account gets terms depends on who bills the buyer for that seller:

Consolidated billing (billing party agent): when Apostra opens a non-sandbox account with the seller, the request asks for your organization’s terms from this endpoint.
Direct billing (operator or advertiser) and sandbox accounts: Apostra’s account request carries no terms, so the seller’s default terms apply.
Explicit per-seller terms: to ask one seller for terms that differ from the organization’s choice, set payment_terms on that seller’s entry in sync_buyer_storefront_accounts. See Payment terms.

Errors

400 VALIDATION_ERROR — a malformed email in email/ccEmails, a lowercase or non-ISO countryAlpha2, or an empty body (at least one field is required). Also returned, with field: "paymentTerms", when paymentTerms is null, is sent with other fields, or is sent before choosing payment terms is available for your organization.
401 UNAUTHORIZED — missing or invalid bearer token.
403 FORBIDDEN — the caller is not an admin of the account.

See Errors for the full error contract.

Get billing info

Read the details on file

Billing overview

How invoicing and remittance work

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Update billing info

Request

Parameters

Response

Set payment terms

Organization terms and seller billing mode

Errors

Get billing info

Billing overview

​Request

​Parameters

​Response

​Set payment terms

​Organization terms and seller billing mode

​Errors

​Related

Get billing info

Billing overview

Request

Parameters

Response

Set payment terms

Organization terms and seller billing mode

Errors

Related