{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/bangermail-com/json-schema/bangermail-com-billing-snapshot-schema.json",
  "title": "BillingSnapshot",
  "x-generated": "2026-11-02",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/bangermail-com-openapi.json#/components/schemas/BillingSnapshot",
  "type": "object",
  "required": [
    "billing",
    "usagePricing",
    "usage",
    "catalog",
    "agentPayment"
  ],
  "properties": {
    "billing": {
      "type": "object",
      "required": [
        "workspaceId",
        "tier",
        "planKey",
        "status",
        "planInterval",
        "stripeCustomerId",
        "stripeSubscriptionId",
        "currentPeriodEnd",
        "cancelAtPeriodEnd",
        "prepaidPlanKey",
        "prepaidUntil"
      ],
      "properties": {
        "workspaceId": {
          "type": "string",
          "format": "uuid"
        },
        "tier": {
          "type": "string",
          "enum": [
            "free",
            "starter",
            "pro",
            "business",
            "scale",
            "enterprise"
          ]
        },
        "planKey": {
          "type": "string",
          "enum": [
            "free",
            "starter",
            "pro",
            "business",
            "scale",
            "enterprise"
          ]
        },
        "status": {
          "type": "string"
        },
        "planInterval": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "month",
            "year",
            null
          ]
        },
        "stripeCustomerId": {
          "type": [
            "string",
            "null"
          ]
        },
        "stripeSubscriptionId": {
          "type": [
            "string",
            "null"
          ]
        },
        "currentPeriodEnd": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Unix timestamp in milliseconds."
        },
        "cancelAtPeriodEnd": {
          "type": "boolean"
        },
        "prepaidPlanKey": {
          "type": [
            "string",
            "null"
          ]
        },
        "prepaidUntil": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Unix timestamp in milliseconds."
        }
      }
    },
    "usagePricing": {
      "type": "object",
      "description": "What Premium includes each month, what it pays per use past that, and the spending limit that caps it.",
      "required": [
        "active",
        "currency",
        "rates",
        "spendLimit",
        "spendLimitIsDefault",
        "included",
        "thisMonth"
      ],
      "properties": {
        "active": {
          "type": "boolean",
          "description": "Whether usage charges run for this workspace now."
        },
        "currency": {
          "type": "string",
          "description": "Lowercase ISO currency of the rates and the limit."
        },
        "rates": {
          "type": "object",
          "required": [
            "emailsPerThousand",
            "storagePerGbMonth",
            "triagePerThousand"
          ],
          "properties": {
            "emailsPerThousand": {
              "type": "number"
            },
            "storagePerGbMonth": {
              "type": "number"
            },
            "triagePerThousand": {
              "type": "number"
            }
          }
        },
        "spendLimit": {
          "type": "number",
          "description": "The monthly spending limit in whole units of currency."
        },
        "spendLimitIsDefault": {
          "type": "boolean"
        },
        "included": {
          "type": "object",
          "required": [
            "emails",
            "storageBytes",
            "triageRuns"
          ],
          "properties": {
            "emails": {
              "type": "integer"
            },
            "storageBytes": {
              "type": "integer"
            },
            "triageRuns": {
              "type": "integer"
            }
          }
        },
        "thisMonth": {
          "description": "While usage charges run, this billing period's use and charge so far. A monthly subscription's period is its subscription period (billed on its renewal invoice); a yearly one's is the UTC calendar month.",
          "anyOf": [
            {
              "type": "object",
              "required": [
                "emails",
                "averageStorageBytes",
                "triageRuns",
                "emailsOver",
                "storageGbOver",
                "triageOver",
                "chargeSoFar",
                "spendLimitUsedPercent",
                "nearSpendLimit",
                "reachedSpendLimit",
                "usageStopped",
                "periodStart",
                "periodEnd",
                "carriedOver"
              ],
              "properties": {
                "emails": {
                  "type": "integer"
                },
                "averageStorageBytes": {
                  "type": "integer"
                },
                "triageRuns": {
                  "type": "integer"
                },
                "emailsOver": {
                  "type": "integer"
                },
                "storageGbOver": {
                  "type": "number"
                },
                "triageOver": {
                  "type": "integer"
                },
                "chargeSoFar": {
                  "type": "number",
                  "description": "In whole units of currency",
                  "never more than the spending limit.": null
                },
                "spendLimitUsedPercent": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "How much of the spending limit this period's use has reached."
                },
                "nearSpendLimit": {
                  "type": "boolean",
                  "description": "At 80% of the spending limit or more but under it; the admins were emailed."
                },
                "reachedSpendLimit": {
                  "type": "boolean",
                  "description": "At the spending limit; the admins were emailed."
                },
                "usageStopped": {
                  "type": "boolean",
                  "description": "Sending",
                  "Triage and storage growth past what the plan includes are stopped until periodEnd or a higher limit.": null
                },
                "periodStart": {
                  "type": "integer",
                  "description": "Unix timestamp in milliseconds."
                },
                "periodEnd": {
                  "type": "integer",
                  "description": "Unix timestamp in milliseconds; the meters start over then."
                },
                "carriedOver": {
                  "type": "number",
                  "description": "Use from earlier months under the minimum usage invoice (about US$2)",
                  "waiting for the next invoice": null,
                  "in whole units of currency.": null
                }
              }
            },
            {
              "type": "null"
            }
          ]
        }
      }
    },
    "usage": {
      "type": "object",
      "required": [
        "storageBytes",
        "storageLimitBytes",
        "sendsThisMonth",
        "sendLimit",
        "includedSendLimit",
        "sendsToday",
        "dailySendLimit",
        "periodEnd"
      ],
      "properties": {
        "storageBytes": {
          "type": "number"
        },
        "storageLimitBytes": {
          "type": "number"
        },
        "sendsThisMonth": {
          "type": "number"
        },
        "sendLimit": {
          "type": "number",
          "description": "Where sending stops this month",
          "including what the spending limit buys.": null
        },
        "includedSendLimit": {
          "type": [
            "number",
            "null"
          ],
          "description": "What the plan includes while usage charges run; null otherwise."
        },
        "sendsToday": {
          "type": "number"
        },
        "dailySendLimit": {
          "type": [
            "number",
            "null"
          ]
        },
        "periodEnd": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Unix timestamp in milliseconds."
        }
      }
    },
    "catalog": {
      "type": "object",
      "required": [
        "plans",
        "addons"
      ],
      "properties": {
        "plans": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "planKey",
              "label",
              "sendLimit",
              "storageGb",
              "gmailImportLimit",
              "triageRuleLimit",
              "triageRunLimit",
              "prices"
            ],
            "properties": {
              "planKey": {
                "type": "string",
                "enum": [
                  "free",
                  "starter",
                  "pro",
                  "business",
                  "scale",
                  "enterprise"
                ]
              },
              "label": {
                "type": "string"
              },
              "sendLimit": {
                "type": "number"
              },
              "storageGb": {
                "type": "number"
              },
              "gmailImportLimit": {
                "type": "number"
              },
              "triageRuleLimit": {
                "type": "number"
              },
              "triageRunLimit": {
                "type": "number"
              },
              "prices": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "priceId",
                    "interval",
                    "currency",
                    "unitAmount"
                  ],
                  "properties": {
                    "priceId": {
                      "type": "string"
                    },
                    "interval": {
                      "type": "string",
                      "enum": [
                        "month",
                        "year"
                      ]
                    },
                    "currency": {
                      "type": "string",
                      "description": "Lowercase ISO currency."
                    },
                    "unitAmount": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "addons": {
          "type": "array",
          "maxItems": 0,
          "items": {}
        }
      }
    },
    "agentPayment": {
      "anyOf": [
        {
          "type": "object",
          "required": [
            "network_id",
            "currency",
            "how",
            "options"
          ],
          "properties": {
            "network_id": {
              "type": "string"
            },
            "currency": {
              "type": "string",
              "enum": [
                "usd"
              ]
            },
            "how": {
              "type": "string"
            },
            "options": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "plan_key",
                  "interval",
                  "months",
                  "amount_cents"
                ],
                "properties": {
                  "plan_key": {
                    "type": "string",
                    "enum": [
                      "starter"
                    ]
                  },
                  "interval": {
                    "type": "string",
                    "enum": [
                      "month",
                      "year"
                    ]
                  },
                  "months": {
                    "type": "integer",
                    "enum": [
                      1,
                      12
                    ]
                  },
                  "amount_cents": {
                    "type": "integer",
                    "description": "What to mint the token for",
                    "any switch discount already taken off.": null
                  },
                  "discount": {
                    "$ref": "#/$defs/AgentPaymentDiscount"
                  }
                }
              }
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "switchOffer": {
      "description": "The month free on a yearly plan this workspace gets for switching from Mailchimp; null when it doesn't.",
      "anyOf": [
        {
          "type": "object",
          "required": [
            "offer",
            "source",
            "appliesTo",
            "plans",
            "message"
          ],
          "properties": {
            "offer": {
              "type": "string",
              "enum": [
                "switch_from_mailchimp"
              ]
            },
            "source": {
              "type": "string",
              "enum": [
                "signup_campaign",
                "mailchimp_connection"
              ]
            },
            "appliesTo": {
              "type": "string",
              "enum": [
                "year"
              ]
            },
            "plans": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "planKey",
                  "currency",
                  "yearlyPrice",
                  "firstYearPrice"
                ],
                "properties": {
                  "planKey": {
                    "type": "string",
                    "enum": [
                      "starter"
                    ]
                  },
                  "currency": {
                    "type": "string"
                  },
                  "yearlyPrice": {
                    "type": "integer",
                    "description": "In the currency's smallest unit."
                  },
                  "firstYearPrice": {
                    "type": "integer",
                    "description": "In the currency's smallest unit."
                  }
                }
              }
            },
            "message": {
              "type": "string"
            }
          }
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "$defs": {
    "AgentPaymentDiscount": {
      "type": "object",
      "required": [
        "offer",
        "amount_off_cents",
        "full_price_cents",
        "message"
      ],
      "properties": {
        "offer": {
          "type": "string",
          "enum": [
            "switch_from_mailchimp"
          ]
        },
        "amount_off_cents": {
          "type": "integer"
        },
        "full_price_cents": {
          "type": "integer"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}