PHP

$client->billing

هر متد در این فضای نام: امضا، پارامترها، آنچه برمی‌گرداند و یک نمونه.

متدها

The plan of the workspace and what it costs, as Plans & Billing shows them: the plan and its usage, the plans on sale, pay as you go, every charge with its invoice, and the links that start a checkout or open the billing portal. Only the workspace owner reaches it, and nothing is paid through the API.

`billing->get`

Read the plan

billing:read

امضای متد

get(?string $apiKey = null): array

Returns the plan of the workspace and what it includes, as Plans & Billing shows it: how it is billed, when it renews or ends and the next charge, how many domains it holds, how much of this month's sends and today's AI actions are used, and pay as you go. metered is false when billing is off on the install, and then nothing is capped.

Billing belongs to the owner of the workspace: an API key acts for the owner, and an OAuth access token reaches billing only when the owner connected the app with every address. A token that acts for a member is 403 owner_only, and a key or token limited to particular addresses or domains is 422 capability_unsupported.

پارامترها

apiKeystring: Overrides the client's API key for this call only.

خروجی

An array with plan, planName, interval, renewsAt, nextCharge, domains, usage and payAsYouGo.

نمونه

$billing = $client->billing->get();$sends = $billing['usage']['sends']; echo $billing['planName'], ': ', $sends['used'], ' of ', $sends['limit'] ?? 'unlimited', ' sends this month', PHP_EOL;

نکته‌ها

A limit of null means the plan has none.

همچنین در دسترس در

API: GET /billing
TypeScript: billing.get()
Python: billing.get()
Ruby: billing.get
CLI: openemail billing get

`billing->listPlans`

List the plans

billing:read

امضای متد

listPlans(?string $apiKey = null): array

Returns every plan, cheapest first, with its price in US cents and what it includes. available says whether it is sold on the install, and intervals the billing intervals it is sold at.

پارامترها

apiKeystring: Overrides the client's API key for this call only.

خروجی

An array with data, a list with one array per plan.

نمونه

$plans = $client->billing->listPlans(); foreach ($plans['data'] as $plan) {    if ($plan['available']) {        echo $plan['name'], ': ', number_format($plan['monthlyPriceCents'] / 100, 2), ' USD a month', PHP_EOL;    }}

همچنین در دسترس در

API: GET /billing/plans
TypeScript: billing.listPlans()
Python: billing.list_plans()
Ruby: billing.list_plans
CLI: openemail billing list-plans

`billing->getUsage`

Read the usage history

billing:read

امضای متد

getUsage(string|int|null $days = null, ?string $apiKey = null): array

Returns the sends and AI actions of each day, and what pay as you go extras cost each month, as the Usage charts show them.

پارامترها

daysint|string: How many days back to go, from 1 to 3,660, or all (OpenEmail\Constants\BillingUsageWindows::ALL) for every day since the workspace was made. The server defaults to 30.
apiKeystring: Overrides the client's API key for this call only.

خروجی

An array with days, months, dailyAiActions and monthlySends.

نمونه

$usage = $client->billing->getUsage(days: 90); echo array_sum(array_column($usage['days'], 'sends')), ' sends in the last 90 days', PHP_EOL; foreach ($usage['months'] as $month) {    echo $month['month'], ': ', $month['cents'], ' cents of extras', PHP_EOL;}

همچنین در دسترس در

API: GET /billing/usage
TypeScript: billing.getUsage()
Python: billing.get_usage()
Ruby: billing.get_usage
CLI: openemail billing get-usage

`billing->listAlerts`

List the billing alerts

billing:read

امضای متد

listAlerts(?string $apiKey = null): array

Returns what the billing banner of the app would say now, most urgent first: a failed payment, paused pay as you go, sending or AI paused at a limit, a plan about to end, an allowance nearly used and a charge coming soon. An empty list means there is nothing to say.

پارامترها

apiKeystring: Overrides the client's API key for this call only.

خروجی

An array with data, a list with one array per alert.

نمونه

use OpenEmail\Constants\BillingAlertSeverities; $alerts = $client->billing->listAlerts(); foreach ($alerts['data'] as $alert) {    if ($alert['severity'] === BillingAlertSeverities::BLOCKED) {        echo 'Blocked: ', $alert['kind'], PHP_EOL;    }}

نکته‌ها

An alert keeps its id while the same thing is true, so one that was dismissed can stay dismissed.

همچنین در دسترس در

API: GET /billing/alerts
TypeScript: billing.listAlerts()
Python: billing.list_alerts()
Ruby: billing.list_alerts
CLI: openemail billing list-alerts

`billing->listCountries`

List the billing countries

billing:read

امضای متد

listCountries(?string $apiKey = null): array

Returns every country a billing address can be in, as the two-letter ISO 3166 codes saveInvoiceDetails takes as country.

پارامترها

apiKeystring: Overrides the client's API key for this call only.

خروجی

An array with the codes in data, a list of strings.

نمونه

$countries = $client->billing->listCountries(); $billable = array_flip($countries['data']); echo isset($billable['DE']) ? 'Germany can be billed' : 'Germany cannot be billed', PHP_EOL;

همچنین در دسترس در

API: GET /billing/countries
TypeScript: billing.listCountries()
Python: billing.list_countries()
Ruby: billing.list_countries
CLI: openemail billing list-countries

`billing->getPayAsYouGo`

Read pay as you go

billing:read

امضای متد

getPayAsYouGo(?string $apiKey = null): array

Returns pay as you go on the workspace: whether usage past the allowances is billed, the monthly limit and what extras cost so far, the current billing period once it is set up, the limits that can be chosen and the prices.

پارامترها

apiKeystring: Overrides the client's API key for this call only.

خروجی

An array with the state, limits, prices and period.

نمونه

$payAsYouGo = $client->billing->getPayAsYouGo(); echo $payAsYouGo['enabled'] ? 'On' : 'Off', ', ', $payAsYouGo['spentCents'], ' of ', $payAsYouGo['limitCents'], ' cents spent', PHP_EOL;echo 'Limits on offer: ', implode(', ', $payAsYouGo['limits']), PHP_EOL;

نکته‌ها

Amounts are in US cents.

همچنین در دسترس در

API: GET /billing/pay-as-you-go
TypeScript: billing.getPayAsYouGo()
Python: billing.get_pay_as_you_go()
Ruby: billing.get_pay_as_you_go
CLI: openemail billing get-pay-as-you-go

`billing->setPayAsYouGo`

Turn pay as you go on or off

billing:write

امضای متد

setPayAsYouGo(array $body, ?string $apiKey = null): array

Turns pay as you go on or off, as the switch on Plans & Billing does. Off takes effect at once, and usage stops at the allowances. On takes effect at once when a card is already saved. The first time, checkoutUrl is a link where the person adds a card, and pay as you go starts once they have: call confirmPayAsYouGo after they return.

Nothing is paid through the API: the person pays, changes the card or cancels on the billing provider's page the link opens, as they do from the app.

پارامترها

enabledboolالزامی: true to turn it on, false to turn it off.
themestring: light or dark, for the page the link opens, as in OpenEmail\Constants\BillingThemes.
localestring: A language tag such as de or pt-PT, for the page the link opens.
apiKeystring: Overrides the client's API key for this call only.

خروجی

An array with enabled, suspended, activating and checkoutUrl.

نمونه

$result = $client->billing->setPayAsYouGo(['enabled' => true, 'theme' => 'dark']); if ($result['checkoutUrl'] !== null) {    echo 'Add a card here: ', $result['checkoutUrl'], PHP_EOL;}

نکته‌ها

With an OAuth access token it asks for a verification code: until the app has verified one, it is refused with 403 step_up_required. An API key is never asked.
Turning it on where pay as you go is not set up on the install is 503 billing_not_configured.
The SDK does not retry it.

همچنین در دسترس در

API: PATCH /billing/pay-as-you-go
TypeScript: billing.setPayAsYouGo()
Python: billing.set_pay_as_you_go()
Ruby: billing.set_pay_as_you_go
CLI: openemail billing set-pay-as-you-go

`billing->setPayAsYouGoLimit`

Set the pay as you go limit

billing:write

امضای متد

setPayAsYouGoLimit(array $body, ?string $apiKey = null): array

Sets the monthly spending limit of pay as you go, in US cents, one of the amounts getPayAsYouGo lists in limits. Extras stop for the rest of a calendar month once it is reached.

پارامترها

limitCentsintالزامی: The limit in US cents: 1,000, 2,500, 5,000, 10,000, 25,000, 50,000, 100,000, 250,000 or 500,000, the amounts in OpenEmail\Constants\PayAsYouGoLimitsCents::ALL.
apiKeystring: Overrides the client's API key for this call only.

خروجی

An array with limitCents.

نمونه

$saved = $client->billing->setPayAsYouGoLimit(['limitCents' => 10000]); echo 'Extras stop at ', $saved['limitCents'] / 100, ' USD a month', PHP_EOL;

نکته‌ها

With an OAuth access token it asks for a verification code: until the app has verified one, it is refused with 403 step_up_required. An API key is never asked.
A workspace where pay as you go was never set up is 409 pay_as_you_go_not_enrolled.
The SDK does not retry it.

همچنین در دسترس در

API: PUT /billing/pay-as-you-go/limit
TypeScript: billing.setPayAsYouGoLimit()
Python: billing.set_pay_as_you_go_limit()
Ruby: billing.set_pay_as_you_go_limit
CLI: openemail billing set-pay-as-you-go-limit

`billing->confirmPayAsYouGo`

Confirm pay as you go

billing:write

امضای متد

confirmPayAsYouGo(?string $apiKey = null): array

Checks with the billing provider whether the card from a pay as you go checkout was saved, and records it, as the app does when the person comes back from the checkout. enabled says whether pay as you go is on now.

پارامترها

apiKeystring: Overrides the client's API key for this call only.

خروجی

An array with enabled.

نمونه

$confirmation = $client->billing->confirmPayAsYouGo(); echo $confirmation['enabled'] ? 'Pay as you go is on' : 'No card was saved', PHP_EOL;

نکته‌ها

With an OAuth access token it asks for a verification code: until the app has verified one, it is refused with 403 step_up_required. An API key is never asked.
It is safe to call again.
The SDK does not retry it.

همچنین در دسترس در

API: POST /billing/pay-as-you-go/confirm
TypeScript: billing.confirmPayAsYouGo()
Python: billing.confirm_pay_as_you_go()
Ruby: billing.confirm_pay_as_you_go
CLI: openemail billing confirm-pay-as-you-go

`billing->startCheckout`

Start a checkout

billing:write

امضای متد

startCheckout(array $body, ?string $apiKey = null): array

Starts buying a paid plan for a workspace on Free, as choosing a plan in the app does, and returns the link to the checkout. Nothing is charged until the person pays there, and the plan starts once they have. A workspace that already pays for a plan changes it with openPortal instead.

Nothing is paid through the API: the person pays, changes the card or cancels on the billing provider's page the link opens, as they do from the app.

پارامترها

planstringالزامی: starter, business or enterprise, as in OpenEmail\Constants\PaidPlanIds.
intervalstring: month or year, as in OpenEmail\Constants\BillingIntervals. Defaults to month.
themestring: light or dark, for the page the link opens, as in OpenEmail\Constants\BillingThemes.
localestring: A language tag such as de or pt-PT, for the page the link opens.
apiKeystring: Overrides the client's API key for this call only.

خروجی

An array with url.

نمونه

use OpenEmail\Constants\BillingIntervals;use OpenEmail\Constants\PaidPlanIds; $checkout = $client->billing->startCheckout([    'plan' => PaidPlanIds::BUSINESS,    'interval' => BillingIntervals::YEAR,    'locale' => 'de',]); echo 'Pay here: ', $checkout['url'], PHP_EOL;

نکته‌ها

With an OAuth access token it asks for a verification code: until the app has verified one, it is refused with 403 step_up_required. An API key is never asked.
A workspace that already pays for a plan is 409 plan_conflict, and a plan or interval not sold on the install is 422 plan_unavailable.
The SDK does not retry it.

همچنین در دسترس در

API: POST /billing/checkout
TypeScript: billing.startCheckout()
Python: billing.start_checkout()
Ruby: billing.start_checkout
CLI: openemail billing start-checkout

`billing->openPortal`

Open the billing portal

billing:write

امضای متد

openPortal(?array $body = null, ?string $apiKey = null): array

Returns a link to the billing portal, where the person changes or cancels the plan, updates the card and downloads past invoices, as Manage does in the app.

Nothing is paid through the API: the person pays, changes the card or cancels on the billing provider's page the link opens, as they do from the app.

پارامترها

themestring: light or dark, for the page the link opens, as in OpenEmail\Constants\BillingThemes.
localestring: A language tag such as de or pt-PT, for the page the link opens.
apiKeystring: Overrides the client's API key for this call only.

خروجی

An array with url.

نمونه

$portal = $client->billing->openPortal(['theme' => 'dark']); echo 'Manage the plan here: ', $portal['url'], PHP_EOL;

نکته‌ها

With an OAuth access token it asks for a verification code: until the app has verified one, it is refused with 403 step_up_required. An API key is never asked.
The SDK does not retry it.

همچنین در دسترس در

API: POST /billing/portal
TypeScript: billing.openPortal()
Python: billing.open_portal()
Ruby: billing.open_portal
CLI: openemail billing open-portal

`billing->listInvoices`

List the charges

billing:read

امضای متد

listInvoices(    ?int $page = null,    ?int $limit = null,    ?string $sort = null,    ?string $search = null,    ?string $apiKey = null,): array

Returns every charge of the workspace with the state of its invoice, a page at a time, as History on Plans & Billing lists them. search: matches the plan, the invoice number, the charge id and the name billed.

پارامترها

pageint: Which page, from 1.
limitint: Charges per page, from 1 to 100. The server defaults to 25.
sortstring: newest, the default, or oldest, as in OpenEmail\Constants\BillingInvoiceSorts.
searchstring: Words to look for, up to 120 characters.
apiKeystring: Overrides the client's API key for this call only.

خروجی

An array with data, total, page, limit, hasMore and metered.

نمونه

$invoices = $client->billing->listInvoices(limit: 10); foreach ($invoices['data'] as $charge) {    if (!$charge['paid']) {        echo $charge['id'], ' ', $charge['amountCents'], ' cents, ', $charge['status'], PHP_EOL;    }} echo $invoices['hasMore'] ? 'More on page 2' : 'That is every charge', PHP_EOL;

نکته‌ها

A provider that does not answer is 502 billing_unreachable.

همچنین در دسترس در

API: GET /billing/invoices
TypeScript: billing.listInvoices()
Python: billing.list_invoices()
Ruby: billing.list_invoices
CLI: openemail billing list-invoices

`billing->getInvoice`

Get the invoice of a charge

billing:read

امضای متد

getInvoice(string $orderId, ?string $apiKey = null): array

Returns the link to the invoice of one charge, as a PDF, and its file name. An invoice that was not written yet is written first, which can take a few seconds. The link is signed by the billing provider, downloads the PDF and stops working after a while, so fetch it again rather than keeping it.

پارامترها

orderIdstringالزامی: The charge id, as listInvoices returns it.
apiKeystring: Overrides the client's API key for this call only.

خروجی

An array with url and fileName.

نمونه

$latest = $client->billing->listInvoices(limit: 1)['data'][0] ?? null; if ($latest !== null) {    $invoice = $client->billing->getInvoice($latest['id']);     echo $invoice['fileName'], ': ', $invoice['url'], PHP_EOL;}

نکته‌ها

A charge with no billing name and address is 409 billing_details_required: save them with saveInvoiceDetails. A draft or void charge is 409 invoice_unavailable, and an invoice still being written is 504 invoice_not_ready.

همچنین در دسترس در

API: GET /billing/invoices/{orderId}
TypeScript: billing.getInvoice()
Python: billing.get_invoice()
Ruby: billing.get_invoice
CLI: openemail billing get-invoice

`billing->saveInvoiceDetails`

Save the billing details of a charge

billing:write

امضای متد

saveInvoiceDetails(string $orderId, array $body, ?string $apiKey = null): array

Saves the name and address billed on a charge, as the Billing address dialog does, keeps the address for later charges, and starts writing its invoice. invoice is ready when the charge already had one, started when it is being written, and refused with the reason in message.

پارامترها

orderIdstringالزامی: The charge id, as listInvoices returns it.
namestringالزامی: Who is billed, up to 200 characters.
line1stringالزامی: The street address, up to 200 characters.
line2string: A flat, suite or building, up to 200 characters.
citystringالزامی: Up to 120 characters.
postalCodestring: Up to 40 characters.
statestring: The state or region, up to 60 characters. In the US and Canada, its two-letter code.
countrystringالزامی: A two-letter ISO 3166 code, one of those listCountries returns.
apiKeystring: Overrides the client's API key for this call only.

خروجی

An array with invoice and message.

نمونه

$result = $client->billing->saveInvoiceDetails('3b9f2c4e-7a1d-4e8b-9c0f-5d6a7b8c9d0e', [    'name' => 'Acme Ltd',    'line1' => '1 Market Street',    'city' => 'London',    'postalCode' => 'EC1A 1AA',    'country' => 'GB',]); echo 'Invoice ', $result['invoice'], PHP_EOL;

نکته‌ها

With an OAuth access token it asks for a verification code: until the app has verified one, it is refused with 403 step_up_required. An API key is never asked.
An address the billing provider refuses is 422 billing_address_rejected.
The SDK does not retry it.

همچنین در دسترس در

API: PUT /billing/invoices/{orderId}/details
TypeScript: billing.saveInvoiceDetails()
Python: billing.save_invoice_details()
Ruby: billing.save_invoice_details
CLI: openemail billing save-invoice-details

$client->billing

متدها

پارامترها

خروجی

نمونه

نکته‌ها

همچنین در دسترس در

پارامترها

خروجی

نمونه

همچنین در دسترس در

پارامترها

خروجی

نمونه

همچنین در دسترس در

پارامترها

خروجی

نمونه

نکته‌ها

همچنین در دسترس در

پارامترها

خروجی

نمونه

همچنین در دسترس در

پارامترها

خروجی

نمونه

نکته‌ها

همچنین در دسترس در

پارامترها

خروجی

نمونه

نکته‌ها

همچنین در دسترس در

پارامترها

خروجی

نمونه

نکته‌ها

همچنین در دسترس در

پارامترها

خروجی

نمونه

نکته‌ها

همچنین در دسترس در

پارامترها

خروجی

نمونه

نکته‌ها

همچنین در دسترس در

پارامترها

خروجی

نمونه

نکته‌ها

همچنین در دسترس در

پارامترها

خروجی

نمونه

نکته‌ها

همچنین در دسترس در

پارامترها

خروجی

نمونه

نکته‌ها

همچنین در دسترس در

پارامترها

خروجی

نمونه

نکته‌ها

همچنین در دسترس در

صندوق ورودی شما،با شرایط خودتان.

صندوق ورودی شما،
با شرایط خودتان.