Subscription (billing)

Request

curl -X GET 'https://app.mailyte.com/api/v1/billing/subscription' \
  -H 'Authorization: Bearer mk_live_YOUR_API_KEY'

const response = await fetch('https://app.mailyte.com/api/v1/billing/subscription', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer mk_live_YOUR_API_KEY',
  },
});
const { data } = await response.json();

import requests
response = requests.get(
    "https://app.mailyte.com/api/v1/billing/subscription",
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
)
data = response.json()["data"]

<?php

$response = Http::withToken('mk_live_YOUR_API_KEY')
    ->get('https://app.mailyte.com/api/v1/billing/subscription');

$data = $response->json('data');

require "net/http"
require "json"
uri = URI("https://app.mailyte.com/api/v1/billing/subscription")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer mk_live_YOUR_API_KEY"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

Response

Success.

• dataobject

  The subscription this organization holds, or `null` (with HTTP 200) for an organization that has never subscribed — an empty state, not an error. NO PAYMENT PROVIDER IS NAMED anywhere in this object, and no provider-side customer or subscription reference appears. Which rail we settle on is our arrangement and it changes without the customer's involvement.

  • objectstringsubscription
  • idstring

    Unique identifier for the subscription.

  • statusstringpending | active | past_due | suspended | cancelled

    The one lifecycle answer, and the actionable half of our collections process: `past_due` means a payment failed, `suspended` means sending has stopped. How many times we have retried a card, and when data would be purged, are internal and deliberately not published.

  • currencystring

    ISO 4217 code, e.g. `NGN` or `USD`. THE CURRENCY THE CUSTOMER AGREED — nothing here is converted. Every amount below is in this currency's minor unit.

  • intervalstringmonth | year

    The billing period. (One-off prices exist for credit packs, which are bought outright and never appear on a subscription.)

  • itemsarray<object>

    Line by line — what lets a caller see "3 Standard, 4 Pro" rather than one plan name that would be a lie about what is held.

    • product_keystring

      The stable catalogue key, and the ONLY catalogue identifier published — it is the handle you pass to `POST /billing/subscription/items` to change quantity. Internal product and price row ids are not published.

    • tierstringstandard | pro | workplace

      The mailbox tier this line buys seats of. **null means NONE — this line is not a seat product** (a Send plan or an add-on), not that its tier is unknown. `product_key` identifies it in every case.

    • quantityinteger

      How many of this product.

    • unit_amountinteger

      Price of ONE unit per `interval`. Integer in the MINOR UNITS of `currency` — kobo when `currency` is `NGN`, cents when it is `USD`. Never a major-unit or decimal value: `150000` under `NGN` is ₦1,500.00, not ₦150,000. Divide by the currency's minor-unit exponent (100 for both NGN and USD) only at the point of display. This is the price locked to this line, so it can differ from today's list price.

    • subtotalinteger

      `quantity` x `unit_amount`, computed once so it cannot drift from the line it describes. Integer in the MINOR UNITS of `currency` — kobo when `currency` is `NGN`, cents when it is `USD`. Never a major-unit or decimal value: `150000` under `NGN` is ₦1,500.00, not ₦150,000. Divide by the currency's minor-unit exponent (100 for both NGN and USD) only at the point of display.

  • totalinteger

    The sum of every line's `subtotal` for one `interval`. Integer in the MINOR UNITS of `currency` — kobo when `currency` is `NGN`, cents when it is `USD`. Never a major-unit or decimal value: `150000` under `NGN` is ₦1,500.00, not ₦150,000. Divide by the currency's minor-unit exponent (100 for both NGN and USD) only at the point of display. Taxes and any payment fees are not included.

  • current_period_startstring

    When the current billing period began. **null means NONE — there is no period yet.** A subscription is created `pending` with no period at all, and a period is stamped only when the first successful payment activates it. So a null here is a fact about the subscription, not a gap in what we read, and it travels with `status: "pending"`.

  • current_period_endstring

    When the current period ends. With `auto_renew` true this is when `total` is charged again. **null means NONE — no period has started**, so there is no renewal date for `auto_renew` to act on yet. Do not read it as "does not renew": read `auto_renew` for that, and `status` for why no period exists.

  • auto_renewboolean
  • cancelled_atstring

    When cancellation was requested. **null means NONE — no cancellation has been requested.** Service continues to `current_period_end` after one is, so a date here does not mean sending has stopped; `status` says that.

  • price_locked_untilstring

    A promise about price the customer can hold us to: rates on this subscription will not rise before this date. **null means NONE — no lock applies**, which is the ordinary case: monthly terms buy no lock, annual prepay does.

  • created_atstring

    When the subscription row was created — which is when checkout produced it, NOT when it started billing. For that read `current_period_start`, which is stamped on first payment. **null means UNKNOWN — the stored timestamp was absent**; it is written on insert, so it should always be present.

  • updated_atstring

    When the subscription last changed. **null means UNKNOWN — the stored timestamp was absent**, never "never changed".

Returned inside the standard envelope.

Errors

Every status, with what causes it and what to do, is on the error reference.